# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The FreeBSD Project
# This file is distributed under the same license as the FreeBSD Documentation package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: FreeBSD Documentation VERSION\n"
"POT-Creation-Date: 2026-02-22 15:58+0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#. type: YAML Front Matter: description
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1
#, no-wrap
msgid "FreeBSD Sockets"
msgstr ""

#. type: YAML Front Matter: title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1
#, no-wrap
msgid "Chapter 7. Sockets"
msgstr ""

#. type: Title =
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:16
#, no-wrap
msgid "Sockets"
msgstr ""

#. type: Title ==
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:54
#, no-wrap
msgid "Synopsis"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:59
msgid ""
"BSD sockets take interprocess communications to a new level.  It is no "
"longer necessary for the communicating processes to run on the same "
"machine.  They still _can_, but they do not have to."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:62
msgid ""
"Not only do these processes not have to run on the same machine, they do not "
"have to run under the same operating system.  Thanks to BSD sockets, your "
"FreeBSD software can smoothly cooperate with a program running on a "
"Macintosh(R), another one running on a Sun(TM) workstation, yet another one "
"running under Windows(R) 2000, all connected with an Ethernet-based local "
"area network."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:64
msgid ""
"But your software can equally well cooperate with processes running in "
"another building, or on another continent, inside a submarine, or a space "
"shuttle."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:67
msgid ""
"It can also cooperate with processes that are not part of a computer (at "
"least not in the strict sense of the word), but of such devices as printers, "
"digital cameras, medical equipment.  Just about anything capable of digital "
"communications."
msgstr ""

#. type: Title ==
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:69
#, no-wrap
msgid "Networking and Diversity"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:75
msgid ""
"We have already hinted on the _diversity_ of networking.  Many different "
"systems have to talk to each other.  And they have to speak the same "
"language.  They also have to _understand_ the same language the same way."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:80
msgid ""
"People often think that _body language_ is universal.  But it is not.  Back "
"in my early teens, my father took me to Bulgaria.  We were sitting at a "
"table in a park in Sofia, when a vendor approached us trying to sell us some "
"roasted almonds."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:83
msgid ""
"I had not learned much Bulgarian by then, so, instead of saying no, I shook "
"my head from side to side, the \"universal\" body language for _no_.  The "
"vendor quickly started serving us some almonds."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:91
msgid ""
"I then remembered I had been told that in Bulgaria shaking your head "
"sideways meant _yes_.  Quickly, I started nodding my head up and down.  The "
"vendor noticed, took his almonds, and walked away.  To an uninformed "
"observer, I did not change the body language: I continued using the language "
"of shaking and nodding my head.  What changed was the _meaning_ of the body "
"language.  At first, the vendor and I interpreted the same language as "
"having completely different meaning.  I had to adjust my own interpretation "
"of that language so the vendor would understand."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:95
msgid ""
"It is the same with computers: The same symbols may have different, even "
"outright opposite meaning.  Therefore, for two computers to understand each "
"other, they must not only agree on the same _language_, but on the same "
"_interpretation_ of the language."
msgstr ""

#. type: Title ==
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:97
#, no-wrap
msgid "Protocols"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:104
msgid ""
"While various programming languages tend to have complex syntax and use a "
"number of multi-letter reserved words (which makes them easy for the human "
"programmer to understand), the languages of data communications tend to be "
"very terse.  Instead of multi-byte words, they often use individual _bits_.  "
"There is a very convincing reason for it: While data travels _inside_ your "
"computer at speeds approaching the speed of light, it often travels "
"considerably slower between two computers."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:106
msgid ""
"As the languages used in data communications are so terse, we usually refer "
"to them as _protocols_ rather than languages."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:111
msgid ""
"As data travels from one computer to another, it always uses more than one "
"protocol.  These protocols are _layered_.  The data can be compared to the "
"inside of an onion: You have to peel off several layers of \"skin\" to get "
"to the data.  This is best illustrated with a picture:"
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:112
#, no-wrap
msgid "Protocol Layers"
msgstr ""

#. type: Target for macro image
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:113
#, no-wrap
msgid "layers.png"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:116
msgid ""
"In this example, we are trying to get an image from a web page we are "
"connected to via an Ethernet."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:119
msgid ""
"The image consists of raw data, which is simply a sequence of RGB values "
"that our software can process, i.e., convert into an image and display on "
"our monitor."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:124
msgid ""
"Alas, our software has no way of knowing how the raw data is organized: Is "
"it a sequence of RGB values, or a sequence of grayscale intensities, or "
"perhaps of CMYK encoded colors? Is the data represented by 8-bit quanta, or "
"are they 16 bits in size, or perhaps 4 bits? How many rows and columns does "
"the image consist of? Should certain pixels be transparent?"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:126
msgid "I think you get the picture..."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:129
msgid ""
"To inform our software how to handle the raw data, it is encoded as a PNG "
"file.  It could be a GIF, or a JPEG, but it is a PNG."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:131
msgid "And PNG is a protocol."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:133
msgid ""
"At this point, I can hear some of you yelling, _\"No, it is not! It is a "
"file format!\"_"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:138
msgid ""
"Well, of course it is a file format.  But from the perspective of data "
"communications, a file format is a protocol: The file structure is a "
"_language_, a terse one at that, communicating to our _process_ how the data "
"is organized.  Ergo, it is a _protocol_."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:141
msgid ""
"Alas, if all we received was the PNG file, our software would be facing a "
"serious problem: How is it supposed to know the data is representing an "
"image, as opposed to some text, or perhaps a sound, or what not? Secondly, "
"how is it supposed to know the image is in the PNG format as opposed to GIF, "
"or JPEG, or some other image format?"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:145
msgid ""
"To obtain that information, we are using another protocol: HTTP.  This "
"protocol can tell us exactly that the data represents an image, and that it "
"uses the PNG protocol.  It can also tell us some other things, but let us "
"stay focused on protocol layers here."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:148
msgid ""
"So, now we have some data wrapped in the PNG protocol, wrapped in the HTTP "
"protocol.  How did we get it from the server?"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:152
msgid ""
"By using TCP/IP over Ethernet, that is how.  Indeed, that is three more "
"protocols.  Instead of continuing inside out, I am now going to talk about "
"Ethernet, simply because it is easier to explain the rest that way."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:156
msgid ""
"Ethernet is an interesting system of connecting computers in a _local area "
"network_ (LAN).  Each computer has a _network interface card_ (NIC), which "
"has a unique 48-bit ID called its _address_.  No two Ethernet NICs in the "
"world have the same address."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:162
msgid ""
"These NICs are all connected with each other.  Whenever one computer wants "
"to communicate with another in the same Ethernet LAN, it sends a message "
"over the network.  Every NIC sees the message.  But as part of the Ethernet "
"_protocol_, the data contains the address of the destination NIC (among "
"other things).  So, only one of all the network interface cards will pay "
"attention to it, the rest will ignore it."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:166
msgid ""
"But not all computers are connected to the same network.  Just because we "
"have received the data over our Ethernet does not mean it originated in our "
"own local area network.  It could have come to us from some other network "
"(which may not even be Ethernet based) connected with our own network via "
"the Internet."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:170
msgid ""
"All data is transferred over the Internet using IP, which stands for "
"_Internet Protocol_.  Its basic role is to let us know where in the world "
"the data has arrived from, and where it is supposed to go to.  It does not "
"_guarantee_ we will receive the data, only that we will know where it came "
"from _if_ we do receive it."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:173
msgid ""
"Even if we do receive the data, IP does not guarantee we will receive "
"various chunks of data in the same order the other computer has sent it to "
"us.  So, we can receive the center of our image before we receive the upper "
"left corner and after the lower right, for example."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:175
msgid ""
"It is TCP (_Transmission Control Protocol_) that asks the sender to resend "
"any lost data and that places it all into the proper order."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:178
msgid ""
"All in all, it took _five_ different protocols for one computer to "
"communicate to another what an image looks like.  We received the data "
"wrapped into the PNG protocol, which was wrapped into the HTTP protocol, "
"which was wrapped into the TCP protocol, which was wrapped into the IP "
"protocol, which was wrapped into the Ethernet protocol."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:182
msgid ""
"Oh, and by the way, there probably were several other protocols involved "
"somewhere on the way.  For example, if our LAN was connected to the Internet "
"through a dial-up call, it used the PPP protocol over the modem which used "
"one (or several) of the various modem protocols, et cetera, et cetera, et "
"cetera..."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:184
msgid ""
"As a developer you should be asking by now, _\"How am I supposed to handle "
"it all?\"_"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:189
msgid ""
"Luckily for you, you are _not_ supposed to handle it all.  You _are_ "
"supposed to handle some of it, but not all of it.  Specifically, you need "
"not worry about the physical connection (in our case Ethernet and possibly "
"PPP, etc).  Nor do you need to handle the Internet Protocol, or the "
"Transmission Control Protocol."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:192
msgid ""
"In other words, you do not have to do anything to receive the data from the "
"other computer.  Well, you do have to _ask_ for it, but that is almost as "
"simple as opening a file."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:195
msgid ""
"Once you have received the data, it is up to you to figure out what to do "
"with it.  In our case, you would need to understand the HTTP protocol and "
"the PNG file structure."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:199
msgid ""
"To use an analogy, all the internetworking protocols become a gray area: Not "
"so much because we do not understand how it works, but because we are no "
"longer concerned about it.  The sockets interface takes care of this gray "
"area for us:"
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:200
#, no-wrap
msgid "Sockets Covered Protocol Layers"
msgstr ""

#. type: Target for macro image
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:201
#, no-wrap
msgid "slayers.png"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:204
msgid ""
"We only need to understand any protocols that tell us how to _interpret the "
"data_, not how to _receive_ it from another process, nor how to _send_ it to "
"another process."
msgstr ""

#. type: Title ==
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:206
#, no-wrap
msgid "The Sockets Model"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:211
msgid ""
"BSD sockets are built on the basic UNIX(R) model: _Everything is a file._ In "
"our example, then, sockets would let us receive an _HTTP file_, so to "
"speak.  It would then be up to us to extract the _PNG file_ from it."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:214
msgid ""
"Due to the complexity of internetworking, we cannot just use the `open` "
"system call, or the `open()` C function.  Instead, we need to take several "
"steps to \"opening\" a socket."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:217
msgid ""
"Once we do, however, we can start treating the _socket_ the same way we "
"treat any _file descriptor_: We can `read` from it, `write` to it, `pipe` "
"it, and, eventually, `close` it."
msgstr ""

#. type: Title ==
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:219
#, no-wrap
msgid "Essential Socket Functions"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:223
msgid ""
"While FreeBSD offers different functions to work with sockets, we only "
"_need_ four to \"open\" a socket.  And in some cases we only need two."
msgstr ""

#. type: Title ===
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:225
#, no-wrap
msgid "The Client-Server Difference"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:228
msgid ""
"Typically, one of the ends of a socket-based data communication is a "
"_server_, the other is a _client_."
msgstr ""

#. type: Title ====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:230
#, no-wrap
msgid "The Common Elements"
msgstr ""

#. type: Title =====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:233
#, no-wrap
msgid "`socket`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:237
msgid ""
"The one function used by both, clients and servers, is man:socket[2].  It is "
"declared this way:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:241
#, no-wrap
msgid "int socket(int domain, int type, int protocol);\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:246
msgid ""
"The return value is of the same type as that of `open`, an integer.  FreeBSD "
"allocates its value from the same pool as that of file handles.  That is "
"what allows sockets to be treated the same way as files."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:250
msgid ""
"The `domain` argument tells the system what _protocol family_ you want it to "
"use.  Many of them exist, some are vendor specific, others are very common.  "
"They are declared in [.filename]#sys/socket.h#."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:252
msgid "Use `PF_INET` for UDP, TCP and other Internet protocols (IPv4)."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:256
msgid ""
"Five values are defined for the `type` argument, again, in [.filename]#sys/"
"socket.h#.  All of them start with \"`SOCK_`\".  The most common one is "
"`SOCK_STREAM`, which tells the system you are asking for a _reliable stream "
"delivery service_ (which is TCP when used with `PF_INET`)."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:258
msgid ""
"If you asked for `SOCK_DGRAM`, you would be requesting a _connectionless "
"datagram delivery service_ (in our case, UDP)."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:260
msgid ""
"If you wanted to be in charge of the low-level protocols (such as IP), or "
"even network interfaces (e.g., the Ethernet), you would need to specify "
"`SOCK_RAW`."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:263
msgid ""
"Finally, the `protocol` argument depends on the previous two arguments, and "
"is not always meaningful.  In that case, use `0` for its value."
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:265
#, no-wrap
msgid "The Unconnected Socket"
msgstr ""

#. type: delimited block = 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:269
msgid ""
"Nowhere, in the `socket` function have we specified to what other system we "
"should be connected.  Our newly created socket remains _unconnected_."
msgstr ""

#. type: delimited block = 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:272
msgid ""
"This is on purpose: To use a telephone analogy, we have just attached a "
"modem to the phone line.  We have neither told the modem to make a call, nor "
"to answer if the phone rings."
msgstr ""

#. type: Title =====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:275
#, no-wrap
msgid "`sockaddr`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:280
msgid ""
"Various functions of the sockets family expect the address of (or pointer "
"to, to use C terminology) a small area of the memory.  The various C "
"declarations in the [.filename]#sys/socket.h# refer to it as `struct "
"sockaddr`.  This structure is declared in the same file:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:293
#, no-wrap
msgid ""
"/*\n"
" * Structure used by kernel to store most\n"
" * addresses.\n"
" */\n"
"struct sockaddr {\n"
"\tunsigned char\tsa_len;\t\t/* total length */\n"
"\tsa_family_t\tsa_family;\t/* address family */\n"
"\tchar\t\tsa_data[14];\t/* actually longer; address value */\n"
"};\n"
"#define\tSOCK_MAXADDRLEN\t255\t\t/* longest possible addresses */\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:297
msgid ""
"Please note the _vagueness_ with which the `sa_data` field is declared, just "
"as an array of `14` bytes, with the comment hinting there can be more than "
"`14` of them."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:300
msgid ""
"This vagueness is quite deliberate. Sockets is a very powerful interface.  "
"While most people perhaps think of it as nothing more than the Internet "
"interface-and most applications probably use it for that nowadays-sockets "
"can be used for just about _any_ kind of interprocess communications, of "
"which the Internet (or, more precisely, IP) is only one."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:303
msgid ""
"The [.filename]#sys/socket.h# refers to the various types of protocols "
"sockets will handle as _address families_, and lists them right before the "
"definition of `sockaddr`:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:352
#, no-wrap
msgid ""
"/*\n"
" * Address families.\n"
" */\n"
"#define\tAF_UNSPEC\t0\t\t/* unspecified */\n"
"#define\tAF_LOCAL\t1\t\t/* local to host (pipes, portals) */\n"
"#define\tAF_UNIX\t\tAF_LOCAL\t/* backward compatibility */\n"
"#define\tAF_INET\t\t2\t\t/* internetwork: UDP, TCP, etc. */\n"
"#define\tAF_IMPLINK\t3\t\t/* arpanet imp addresses */\n"
"#define\tAF_PUP\t\t4\t\t/* pup protocols: e.g. BSP */\n"
"#define\tAF_CHAOS\t5\t\t/* mit CHAOS protocols */\n"
"#define\tAF_NS\t\t6\t\t/* XEROX NS protocols */\n"
"#define\tAF_ISO\t\t7\t\t/* ISO protocols */\n"
"#define\tAF_OSI\t\tAF_ISO\n"
"#define\tAF_ECMA\t\t8\t\t/* European computer manufacturers */\n"
"#define\tAF_DATAKIT\t9\t\t/* datakit protocols */\n"
"#define\tAF_CCITT\t10\t\t/* CCITT protocols, X.25 etc */\n"
"#define\tAF_SNA\t\t11\t\t/* IBM SNA */\n"
"#define AF_DECnet\t12\t\t/* DECnet */\n"
"#define AF_DLI\t\t13\t\t/* DEC Direct data link interface */\n"
"#define AF_LAT\t\t14\t\t/* LAT */\n"
"#define\tAF_HYLINK\t15\t\t/* NSC Hyperchannel */\n"
"#define\tAF_APPLETALK\t16\t\t/* Apple Talk */\n"
"#define\tAF_ROUTE\t17\t\t/* Internal Routing Protocol */\n"
"#define\tAF_LINK\t\t18\t\t/* Link layer interface */\n"
"#define\tpseudo_AF_XTP\t19\t\t/* eXpress Transfer Protocol (no AF) */\n"
"#define\tAF_COIP\t\t20\t\t/* connection-oriented IP, aka ST II */\n"
"#define\tAF_CNT\t\t21\t\t/* Computer Network Technology */\n"
"#define pseudo_AF_RTIP\t22\t\t/* Help Identify RTIP packets */\n"
"#define\tAF_IPX\t\t23\t\t/* Novell Internet Protocol */\n"
"#define\tAF_SIP\t\t24\t\t/* Simple Internet Protocol */\n"
"#define\tpseudo_AF_PIP\t25\t\t/* Help Identify PIP packets */\n"
"#define\tAF_ISDN\t\t26\t\t/* Integrated Services Digital Network*/\n"
"#define\tAF_E164\t\tAF_ISDN\t\t/* CCITT E.164 recommendation */\n"
"#define\tpseudo_AF_KEY\t27\t\t/* Internal key-management function */\n"
"#define\tAF_INET6\t28\t\t/* IPv6 */\n"
"#define\tAF_NATM\t\t29\t\t/* native ATM access */\n"
"#define\tAF_ATM\t\t30\t\t/* ATM */\n"
"#define pseudo_AF_HDRCMPLT 31\t\t/* Used by BPF to not rewrite headers\n"
"\t\t\t\t\t * in interface output routine\n"
"\t\t\t\t\t */\n"
"#define\tAF_NETGRAPH\t32\t\t/* Netgraph sockets */\n"
"#define\tAF_SLOW\t\t33\t\t/* 802.3ad slow protocol */\n"
"#define\tAF_SCLUSTER\t34\t\t/* Sitara cluster protocol */\n"
"#define\tAF_ARP\t\t35\n"
"#define\tAF_BLUETOOTH\t36\t\t/* Bluetooth sockets */\n"
"#define\tAF_MAX\t\t37\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:356
msgid "The one used for IP is AF_INET.  It is a symbol for the constant `2`."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:358
msgid ""
"It is the _address family_ listed in the `sa_family` field of `sockaddr` "
"that decides how exactly the vaguely named bytes of `sa_data` will be used."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:360
msgid ""
"Specifically, whenever the _address family_ is AF_INET, we can use `struct "
"sockaddr_in` found in [.filename]#netinet/in.h#, wherever `sockaddr` is "
"expected:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:373
#, no-wrap
msgid ""
"/*\n"
" * Socket address, internet style.\n"
" */\n"
"struct sockaddr_in {\n"
"\tuint8_t\t\tsin_len;\n"
"\tsa_family_t\tsin_family;\n"
"\tin_port_t\tsin_port;\n"
"\tstruct\tin_addr sin_addr;\n"
"\tchar\tsin_zero[8];\n"
"};\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:376
msgid "We can visualize its organization this way:"
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:377
#, no-wrap
msgid "sockaddr_in structure"
msgstr ""

#. type: Target for macro image
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:378
#, no-wrap
msgid "sain.png"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:381
msgid ""
"The three important fields are `sin_family`, which is byte 1 of the "
"structure, `sin_port`, a 16-bit value found in bytes 2 and 3, and "
"`sin_addr`, a 32-bit integer representation of the IP address, stored in "
"bytes 4-7."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:387
msgid ""
"Now, let us try to fill it out.  Let us assume we are trying to write a "
"client for the _daytime_ protocol, which simply states that its server will "
"write a text string representing the current date and time to port 13.  We "
"want to use TCP/IP, so we need to specify `AF_INET` in the address family "
"field.  `AF_INET` is defined as `2`.  Let us use the IP address of "
"`132.163.96.1`, which is the time server of US federal government "
"(`time.nist.gov`)."
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:388
#, no-wrap
msgid "Specific example of sockaddr_in"
msgstr ""

#. type: Target for macro image
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:389
#, no-wrap
msgid "sainfill.png"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:392
msgid ""
"By the way the `sin_addr` field is declared as being of the `struct in_addr` "
"type, which is defined in [.filename]#netinet/in.h#:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:401
#, no-wrap
msgid ""
"/*\n"
" * Internet address (a structure for historical reasons)\n"
" */\n"
"struct in_addr {\n"
"\tin_addr_t s_addr;\n"
"};\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:404
msgid "In addition, `in_addr_t` is a 32-bit integer."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:406
msgid ""
"The `132.163.96.1` is just a convenient notation of expressing a 32-bit "
"integer by listing all of its 8-bit bytes, starting with the _most "
"significant_ one."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:410
msgid ""
"So far, we have viewed `sockaddr` as an abstraction.  Our computer does not "
"store `short` integers as a single 16-bit entity, but as a sequence of 2 "
"bytes.  Similarly, it stores 32-bit integers as a sequence of 4 bytes."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:412
msgid "Suppose we coded something like this:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:418
#, no-wrap
msgid ""
"sa.sin_family      = AF_INET;\n"
"sa.sin_port        = 13;\n"
"sa.sin_addr.s_addr = (((((132 << 8) | 163) << 8) | 96) << 8) | 1;\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:421
msgid "What would the result look like?"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:424
msgid ""
"Well, that depends, of course.  On a Pentium(R), or other x86, based "
"computer, it would look like this:"
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:425
#, no-wrap
msgid "sockaddr_in on an Intel system"
msgstr ""

#. type: Target for macro image
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:426
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:472
#, no-wrap
msgid "sainlsb.png"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:429
msgid "On a different system, it might look like this:"
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:430
#, no-wrap
msgid "sockaddr_in on an MSB system"
msgstr ""

#. type: Target for macro image
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:431
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:477
#, no-wrap
msgid "sainmsb.png"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:435
msgid ""
"And on a PDP it might look different yet.  But the above two are the most "
"common ways in use today."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:439
msgid ""
"Ordinarily, wanting to write portable code, programmers pretend that these "
"differences do not exist.  And they get away with it (except when they code "
"in assembly language).  Alas, you cannot get away with it that easily when "
"coding for sockets."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:441
msgid "Why?"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:443
msgid ""
"Because when communicating with another computer, you usually do not know "
"whether it stores data _most significant byte_ (MSB) or _least significant "
"byte_ (LSB) first."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:445
msgid "You might be wondering, _\"So, will sockets not handle it for me?\"_"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:447
msgid "It will not."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:450
msgid ""
"While that answer may surprise you at first, remember that the general "
"sockets interface only understands the `sa_len` and `sa_family` fields of "
"the `sockaddr` structure.  You do not have to worry about the byte order "
"there (of course, on FreeBSD `sa_family` is only 1 byte anyway, but many "
"other UNIX(R) systems do not have `sa_len` and use 2 bytes for `sa_family`, "
"and expect the data in whatever order is native to the computer)."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:453
msgid ""
"But the rest of the data is just `sa_data[14]` as far as sockets goes.  "
"Depending on the _address family_, sockets just forwards that data to its "
"destination."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:458
msgid ""
"Indeed, when we enter a port number, it is because we want the other "
"computer to know what service we are asking for.  And, when we are the "
"server, we read the port number so we know what service the other computer "
"is expecting from us.  Either way, sockets only has to forward the port "
"number as data.  It does not interpret it in any way."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:461
msgid ""
"Similarly, we enter the IP address to tell everyone on the way where to send "
"our data to.  Sockets, again, only forwards it as data."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:463
msgid ""
"That is why, we (the _programmers_, not the _sockets_) have to distinguish "
"between the byte order used by our computer and a conventional byte order to "
"send the data in to the other computer."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:465
msgid ""
"We will call the byte order our computer uses the _host byte order_, or just "
"the _host order_."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:468
msgid ""
"There is a convention of sending the multi-byte data over IP _MSB first_.  "
"This, we will refer to as the _network byte order_, or simply the _network "
"order_."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:470
msgid ""
"Now, if we compiled the above code for an Intel based computer, our _host "
"byte order_ would produce:"
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:471
#, no-wrap
msgid "Host byte order on an Intel system"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:475
msgid "But the _network byte order_ requires that we store the data MSB first:"
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:476
#, no-wrap
msgid "Network byte order"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:480
msgid ""
"Unfortunately, our _host order_ is the exact opposite of the _network order_."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:483
msgid ""
"We have several ways of dealing with it.  One would be to _reverse_ the "
"values in our code:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:489
#, no-wrap
msgid ""
"sa.sin_family      = AF_INET;\n"
"sa.sin_port        = 13 << 8;\n"
"sa.sin_addr.s_addr = (((((1 << 8) | 96) << 8) | 163) << 8) | 132;\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:494
msgid ""
"This will _trick_ our compiler into storing the data in the _network byte "
"order_.  In some cases, this is exactly the way to do it (e.g., when "
"programming in assembly language).  In most cases, however, it can cause a "
"problem."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:498
msgid ""
"Suppose, you wrote a sockets-based program in C.  You know it is going to "
"run on a Pentium(R), so you enter all your constants in reverse and force "
"them to the _network byte order_.  It works well."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:503
msgid ""
"Then, some day, your trusted old Pentium(R) becomes a rusty old Pentium(R).  "
"You replace it with a system whose _host order_ is the same as the _network "
"order_.  You need to recompile all your software.  All of your software "
"continues to perform well, except the one program you wrote."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:507
msgid ""
"You have since forgotten that you had forced all of your constants to the "
"opposite of the _host order_.  You spend some quality time tearing out your "
"hair, calling the names of all gods you ever heard of (and some you made "
"up), hitting your monitor with a nerf bat, and performing all the other "
"traditional ceremonies of trying to figure out why something that has worked "
"so well is suddenly not working at all."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:509
msgid ""
"Eventually, you figure it out, say a couple of swear words, and start "
"rewriting your code."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:512
msgid ""
"Luckily, you are not the first one to face the problem.  Someone else has "
"created the man:htons[3] and man:htonl[3] C functions to convert a `short` "
"and `long` respectively from the _host byte order_ to the _network byte "
"order_, and the man:ntohs[3] and man:ntohl[3] C functions to go the other "
"way."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:515
msgid ""
"On _MSB-first_ systems these functions do nothing.  On _LSB-first_ systems "
"they convert values to the proper order."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:517
msgid ""
"So, regardless of what system your software is compiled on, your data will "
"end up in the correct order if you use these functions."
msgstr ""

#. type: Title ====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:519
#, no-wrap
msgid "Client Functions"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:524
msgid ""
"Typically, the client initiates the connection to the server.  The client "
"knows which server it is about to call: It knows its IP address, and it "
"knows the _port_ the server resides at.  It is akin to you picking up the "
"phone and dialing the number (the _address_), then, after someone answers, "
"asking for the person in charge of wingdings (the _port_)."
msgstr ""

#. type: Title =====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:526
#, no-wrap
msgid "`connect`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:529
msgid ""
"Once a client has created a socket, it needs to connect it to a specific "
"port on a remote system. It uses man:connect[2]:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:533
#, no-wrap
msgid "int connect(int s, const struct sockaddr *name, socklen_t namelen);\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:538
msgid ""
"The `s` argument is the socket, i.e., the value returned by the `socket` "
"function.  The `name` is a pointer to `sockaddr`, the structure we have "
"talked about extensively.  Finally, `namelen` informs the system how many "
"bytes are in our `sockaddr` structure."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:541
msgid ""
"If `connect` is successful, it returns `0`.  Otherwise it returns `-1` and "
"stores the error code in `errno`."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:545
msgid ""
"There are many reasons why `connect` may fail.  For example, with an attempt "
"to an Internet connection, the IP address may not exist, or it may be down, "
"or just too busy, or it may not have a server listening at the specified "
"port.  Or it may outright _refuse_ any request for specific code."
msgstr ""

#. type: Title =====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:547
#, no-wrap
msgid "Our First Client"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:550
msgid ""
"We now know enough to write a very simple client, one that will get current "
"time from `132.163.96.1` and print it to [.filename]#stdout#."
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:564
#, no-wrap
msgid ""
"/*\n"
" * daytime.c\n"
" *\n"
" * Programmed by G. Adam Stanislav\n"
" */\n"
"#include <stdio.h>\n"
"#include <string.h>\n"
"#include <sys/types.h>\n"
"#include <sys/socket.h>\n"
"#include <netinet/in.h>\n"
"#include <unistd.h>\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:569
#, no-wrap
msgid ""
"int main() {\n"
"  int s, bytes;\n"
"  struct sockaddr_in sa;\n"
"  char buffer[BUFSIZ+1];\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:574
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:993
#, no-wrap
msgid ""
"  if ((s = socket(PF_INET, SOCK_STREAM, 0)) < 0) {\n"
"    perror(\"socket\");\n"
"    return 1;\n"
"  }\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:576
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:995
#, no-wrap
msgid "  memset(&sa, '\\0', sizeof(sa));\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:585
#, no-wrap
msgid ""
"  sa.sin_family = AF_INET;\n"
"  sa.sin_port = htons(13);\n"
"  sa.sin_addr.s_addr = htonl((((((132 << 8) | 163) << 8) | 96) << 8) | 1);\n"
"  if (connect(s, (struct sockaddr *)&sa, sizeof sa) < 0) {\n"
"    perror(\"connect\");\n"
"    close(s);\n"
"    return 2;\n"
"  }\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:588
#, no-wrap
msgid ""
"  while ((bytes = read(s, buffer, BUFSIZ)) > 0)\n"
"    write(1, buffer, bytes);\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:592
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1019
#, no-wrap
msgid ""
"  close(s);\n"
"  return 0;\n"
"}\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:595
msgid ""
"Go ahead, enter it in your editor, save it as [.filename]#daytime.c#, then "
"compile and run it:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:600
#, no-wrap
msgid ""
"% cc -O3 -o daytime daytime.c\n"
"% ./daytime\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:603
#, no-wrap
msgid ""
"52079 01-06-19 02:29:25 50 0 1 543.9 UTC(NIST) *\n"
"%\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:607
msgid ""
"In this case, the date was June 19, 2001, the time was 02:29:25 UTC.  "
"Naturally, your results will vary."
msgstr ""

#. type: Title ====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:609
#, no-wrap
msgid "Server Functions"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:615
msgid ""
"The typical server does not initiate the connection.  Instead, it waits for "
"a client to call it and request services.  It does not know when the client "
"will call, nor how many clients will call.  It may be just sitting there, "
"waiting patiently, one moment, The next moment, it can find itself swamped "
"with requests from a number of clients, all calling in at the same time."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:617
msgid "The sockets interface offers three basic functions to handle this."
msgstr ""

#. type: Title =====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:619
#, no-wrap
msgid "`bind`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:622
msgid ""
"Ports are like extensions to a phone line: After you dial a number, you dial "
"the extension to get to a specific person or department."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:626
msgid ""
"There are 65535 IP ports, but a server usually processes requests that come "
"in on only one of them.  It is like telling the phone room operator that we "
"are now at work and available to answer the phone at a specific extension.  "
"We use man:bind[2] to tell sockets which port we want to serve."
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:630
#, no-wrap
msgid "int bind(int s, const struct sockaddr *addr, socklen_t addrlen);\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:635
msgid ""
"Beside specifying the port in `addr`, the server may include its IP "
"address.  However, it can just use the symbolic constant INADDR_ANY to "
"indicate it will serve all requests to the specified port regardless of what "
"its IP address is.  This symbol, along with several similar ones, is "
"declared in [.filename]#netinet/in.h#"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:639
#, no-wrap
msgid "#define\tINADDR_ANY\t\t(u_int32_t)0x00000000\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:644
msgid ""
"Suppose we were writing a server for the _daytime_ protocol over TCP/IP.  "
"Recall that it uses port 13.  Our `sockaddr_in` structure would look like "
"this:"
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:645
#, no-wrap
msgid "Example Server sockaddr_in"
msgstr ""

#. type: Target for macro image
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:646
#, no-wrap
msgid "sainserv.png"
msgstr ""

#. type: Title =====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:649
#, no-wrap
msgid "`listen`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:653
msgid ""
"To continue our office phone analogy, after you have told the phone central "
"operator what extension you will be at, you now walk into your office, and "
"make sure your own phone is plugged in and the ringer is turned on.  Plus, "
"you make sure your call waiting is activated, so you can hear the phone ring "
"even while you are talking to someone."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:655
msgid "The server ensures all of that with the man:listen[2] function."
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:659
#, no-wrap
msgid "int listen(int s, int backlog);\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:663
msgid ""
"In here, the `backlog` variable tells sockets how many incoming requests to "
"accept while you are busy processing the last request.  In other words, it "
"determines the maximum size of the queue of pending connections."
msgstr ""

#. type: Title =====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:665
#, no-wrap
msgid "`accept`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:670
msgid ""
"After you hear the phone ringing, you accept the call by answering the "
"call.  You have now established a connection with your client.  This "
"connection remains active until either you or your client hang up."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:672
msgid "The server accepts the connection by using the man:accept[2] function."
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:676
#, no-wrap
msgid "int accept(int s, struct sockaddr *addr, socklen_t *addrlen);\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:680
msgid ""
"Note that this time `addrlen` is a pointer.  This is necessary because in "
"this case it is the socket that fills out `addr`, the `sockaddr_in` "
"structure."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:684
msgid ""
"The return value is an integer.  Indeed, the `accept` returns a _new "
"socket_.  You will use this new socket to communicate with the client."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:686
msgid ""
"What happens to the old socket? It continues to listen for more requests "
"(remember the `backlog` variable we passed to `listen`?) until we `close` it."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:690
msgid ""
"Now, the new socket is meant only for communications.  It is fully "
"connected.  We cannot pass it to `listen` again, trying to accept additional "
"connections."
msgstr ""

#. type: Title =====
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:692
#, no-wrap
msgid "Our First Server"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:696
msgid ""
"Our first server will be somewhat more complex than our first client was: "
"Not only do we have more sockets functions to use, but we need to write it "
"as a daemon."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:699
msgid ""
"This is best achieved by creating a _child process_ after binding the port.  "
"The main process then exits and returns control to the shell (or whatever "
"program invoked it)."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:701
msgid ""
"The child calls `listen`, then starts an endless loop, which accepts a "
"connection, serves it, and eventually closes its socket."
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:717
#, no-wrap
msgid ""
"/*\n"
" * daytimed - a port 13 server\n"
" *\n"
" * Programmed by G. Adam Stanislav\n"
" * June 19, 2001\n"
" */\n"
"#include <stdio.h>\n"
"#include <string.h>\n"
"#include <time.h>\n"
"#include <unistd.h>\n"
"#include <sys/types.h>\n"
"#include <sys/socket.h>\n"
"#include <netinet/in.h>\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:719
#, no-wrap
msgid "#define BACKLOG 4\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:727
#, no-wrap
msgid ""
"int main() {\n"
"    int s, c;\n"
"    socklen_t b;\n"
"    struct sockaddr_in sa;\n"
"    time_t t;\n"
"    struct tm *tm;\n"
"    FILE *client;\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:732
#, no-wrap
msgid ""
"    if ((s = socket(PF_INET, SOCK_STREAM, 0)) < 0) {\n"
"        perror(\"socket\");\n"
"        return 1;\n"
"    }\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:734
#, no-wrap
msgid "    memset(&sa, '\\0', sizeof(sa));\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:737
#, no-wrap
msgid ""
"    sa.sin_family = AF_INET;\n"
"    sa.sin_port   = htons(13);\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:740
#, no-wrap
msgid ""
"    if (INADDR_ANY)\n"
"        sa.sin_addr.s_addr = htonl(INADDR_ANY);\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:745
#, no-wrap
msgid ""
"    if (bind(s, (struct sockaddr *)&sa, sizeof sa) < 0) {\n"
"        perror(\"bind\");\n"
"        return 2;\n"
"    }\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:756
#, no-wrap
msgid ""
"    switch (fork()) {\n"
"        case -1:\n"
"            perror(\"fork\");\n"
"            return 3;\n"
"        default:\n"
"            close(s);\n"
"            return 0;\n"
"        case 0:\n"
"            break;\n"
"    }\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:758
#, no-wrap
msgid "    listen(s, BACKLOG);\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:761
#, no-wrap
msgid ""
"    for (;;) {\n"
"        b = sizeof sa;\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:766
#, no-wrap
msgid ""
"        if ((c = accept(s, (struct sockaddr *)&sa, &b)) < 0) {\n"
"            perror(\"daytimed accept\");\n"
"            return 4;\n"
"        }\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:771
#, no-wrap
msgid ""
"        if ((client = fdopen(c, \"w\")) == NULL) {\n"
"            perror(\"daytimed fdopen\");\n"
"            return 5;\n"
"        }\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:776
#, no-wrap
msgid ""
"        if ((t = time(NULL)) < 0) {\n"
"            perror(\"daytimed time\");\n"
"            return 6;\n"
"        }\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:785
#, no-wrap
msgid ""
"        tm = gmtime(&t);\n"
"        fprintf(client, \"%.4i-%.2i-%.2iT%.2i:%.2i:%.2iZ\\n\",\n"
"            tm->tm_year + 1900,\n"
"            tm->tm_mon + 1,\n"
"            tm->tm_mday,\n"
"            tm->tm_hour,\n"
"            tm->tm_min,\n"
"            tm->tm_sec);\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:789
#, no-wrap
msgid ""
"        fclose(client);\n"
"    }\n"
"}\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:794
msgid ""
"We start by creating a socket.  Then we fill out the `sockaddr_in` structure "
"in `sa`.  Note the conditional use of INADDR_ANY:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:799
#, no-wrap
msgid ""
"if (INADDR_ANY)\n"
"        sa.sin_addr.s_addr = htonl(INADDR_ANY);\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:806
msgid ""
"Its value is `0`.  Since we have just used `memset` to set zeroes on the "
"entire structure, it would be redundant to set it to `0` again.  But if we "
"port our code to some other system where INADDR_ANY is perhaps not a zero, "
"we need to assign it to `sa.sin_addr.s_addr`.  Most modern C compilers are "
"clever enough to notice that INADDR_ANY is a constant.  As long as it is a "
"zero, they will optimize the entire conditional statement out of the code."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:810
msgid ""
"After we have called `bind` successfully, we are ready to become a _daemon_: "
"We use `fork` to create a child process.  In both, the parent and the child, "
"the `s` variable is our socket.  The parent process will not need it, so it "
"calls `close`, then it returns `0` to inform its own parent it had "
"terminated successfully."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:815
msgid ""
"Meanwhile, the child process continues working in the background.  It calls "
"`listen` and sets its backlog to `4`.  It does not need a large value here "
"because _daytime_ is not a protocol many clients request all the time, and "
"because it can process each request instantly anyway."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:817
msgid ""
"Finally, the daemon starts an endless loop, which performs the following "
"steps:"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:820
msgid ""
"Call `accept`. It waits here until a client contacts it. At that point, it "
"receives a new socket, `c`, which it can use to communicate with this "
"particular client."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:821
msgid ""
"It uses the C function `fdopen` to turn the socket from a low-level _file "
"descriptor_ to a C-style `FILE` pointer. This will allow the use of "
"`fprintf` later on."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:822
msgid ""
"It checks the time, and prints it in the _ISO 8601_ format to the `client` "
"\"file\". It then uses `fclose` to close the file. That will automatically "
"close the socket as well."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:824
msgid "We can _generalize_ this, and use it as a model for many other servers:"
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:825
#, no-wrap
msgid "Sequential Server"
msgstr ""

#. type: Target for macro image
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:826
#, no-wrap
msgid "serv.png"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:832
msgid ""
"This flowchart is good for _sequential servers_, i.e., servers that can "
"serve one client at a time, just as we were able to with our _daytime_ "
"server.  This is only possible whenever there is no real \"conversation\" "
"going on between the client and the server: As soon as the server detects a "
"connection to the client, it sends out some data and closes the connection.  "
"The entire operation may take nanoseconds, and it is finished."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:835
msgid ""
"The advantage of this flowchart is that, except for the brief moment after "
"the parent ``fork``s and before it exits, there is always only one _process_ "
"active: Our server does not take up much memory and other system resources."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:839
msgid ""
"Note that we have added _initialize daemon_ in our flowchart.  We did not "
"need to initialize our own daemon, but this is a good place in the flow of "
"the program to set up any `signal` handlers, open any files we may need, etc."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:843
msgid ""
"Just about everything in the flow chart can be used literally on many "
"different servers.  The _serve_ entry is the exception.  We think of it as a "
"_\"black box\"_, i.e., something you design specifically for your own "
"server, and just \"plug it into the rest.\""
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:849
msgid ""
"Not all protocols are that simple.  Many receive a request from the client, "
"reply to it, then receive another request from the same client.  As a "
"result, they do not know in advance how long they will be serving the "
"client.  Such servers usually start a new process for each client.  While "
"the new process is serving its client, the daemon can continue listening for "
"more connections."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:852
msgid ""
"Now, go ahead, save the above source code as [.filename]#daytimed.c# (it is "
"customary to end the names of daemons with the letter `d`).  After you have "
"compiled it, try running it:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:858
#, no-wrap
msgid ""
"% ./daytimed\n"
"bind: Permission denied\n"
"%\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:862
msgid ""
"What happened here? As you will recall, the _daytime_ protocol uses port "
"13.  But all ports below 1024 are reserved to the superuser (otherwise, "
"anyone could start a daemon pretending to serve a commonly used port, while "
"causing a security breach)."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:864
msgid "Try again, this time as the superuser:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:869
#, no-wrap
msgid ""
"# ./daytimed\n"
"#\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:872
msgid "What... Nothing? Let us try again:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:876
#, no-wrap
msgid "# ./daytimed\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:879
#, no-wrap
msgid ""
"bind: Address already in use\n"
"#\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:884
msgid ""
"Every port can only be bound by one program at a time.  Our first attempt "
"was indeed successful: It started the child daemon and returned quietly.  It "
"is still running and will continue to run until you either kill it, or any "
"of its system calls fail, or you reboot the system."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:887
msgid ""
"Fine, we know it is running in the background.  But is it working? How do we "
"know it is a proper _daytime_ server? Simple:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:891
#, no-wrap
msgid "% telnet localhost 13\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:900
#, no-wrap
msgid ""
"Trying ::1...\n"
"telnet: connect to address ::1: Connection refused\n"
"Trying 127.0.0.1...\n"
"Connected to localhost.\n"
"Escape character is '^]'.\n"
"2001-06-19T21:04:42Z\n"
"Connection closed by foreign host.\n"
"%\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:905
msgid ""
"telnet tried the new IPv6, and failed.  It retried with IPv4 and succeeded.  "
"The daemon works."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:908
msgid ""
"If you have access to another UNIX(R) system via telnet, you can use it to "
"test accessing the server remotely.  My computer does not have a static IP "
"address, so this is what I did:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:912
#, no-wrap
msgid "% who\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:916
#, no-wrap
msgid ""
"whizkid          ttyp0   Jun 19 16:59   (216.127.220.143)\n"
"xxx              ttyp1   Jun 19 16:06   (xx.xx.xx.xx)\n"
"% telnet 216.127.220.143 13\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:923
#, no-wrap
msgid ""
"Trying 216.127.220.143...\n"
"Connected to r47.bfm.org.\n"
"Escape character is '^]'.\n"
"2001-06-19T21:31:11Z\n"
"Connection closed by foreign host.\n"
"%\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:926
msgid "Again, it worked. Will it work using the domain name?"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:930
#, no-wrap
msgid "% telnet r47.bfm.org 13\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:937
#, no-wrap
msgid ""
"Trying 216.127.220.143...\n"
"Connected to r47.bfm.org.\n"
"Escape character is '^]'.\n"
"2001-06-19T21:31:40Z\n"
"Connection closed by foreign host.\n"
"%\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:941
msgid ""
"By the way, telnet prints the _Connection closed by foreign host_ message "
"after our daemon has closed the socket.  This shows us that, indeed, using "
"`fclose(client);` in our code works as advertised."
msgstr ""

#. type: Title ==
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:943
#, no-wrap
msgid "Helper Functions"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:949
msgid ""
"FreeBSD C library contains many helper functions for sockets programming.  "
"For example, in our sample client we hard coded the `time.nist.gov` IP "
"address.  But we do not always know the IP address.  Even if we do, our "
"software is more flexible if it allows the user to enter the IP address, or "
"even the domain name."
msgstr ""

#. type: Title ===
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:951
#, no-wrap
msgid "`gethostbyname`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:954
msgid ""
"While there is no way to pass the domain name directly to any of the sockets "
"functions, the FreeBSD C library comes with the man:gethostbyname[3] and "
"man:gethostbyname2[3] functions, declared in [.filename]#netdb.h#."
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:959
#, no-wrap
msgid ""
"struct hostent * gethostbyname(const char *name);\n"
"struct hostent * gethostbyname2(const char *name, int af);\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:963
msgid ""
"Both return a pointer to the `hostent` structure, with much information "
"about the domain.  For our purposes, the `h_addr_list[0]` field of the "
"structure points at `h_length` bytes of the correct address, already stored "
"in the _network byte order_."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:965
msgid ""
"This allows us to create a much more flexible-and much more useful-version "
"of our daytime program:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:981
#, no-wrap
msgid ""
"/*\n"
" * daytime.c\n"
" *\n"
" * Programmed by G. Adam Stanislav\n"
" * 19 June 2001\n"
" */\n"
"#include <stdio.h>\n"
"#include <string.h>\n"
"#include <unistd.h>\n"
"#include <sys/types.h>\n"
"#include <sys/socket.h>\n"
"#include <netinet/in.h>\n"
"#include <netdb.h>\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:988
#, no-wrap
msgid ""
"int main(int argc, char *argv[]) {\n"
"  int s, bytes;\n"
"  struct sockaddr_in sa;\n"
"  struct hostent *he;\n"
"  char buf[BUFSIZ+1];\n"
"  char *host;\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:998
#, no-wrap
msgid ""
"  sa.sin_family = AF_INET;\n"
"  sa.sin_port = htons(13);\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1000
#, no-wrap
msgid "  host = (argc > 1) ? argv[1] : \"time.nist.gov\";\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1005
#, no-wrap
msgid ""
"  if ((he = gethostbyname(host)) == NULL) {\n"
"    herror(host);\n"
"    return 2;\n"
"  }\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1007
#, no-wrap
msgid "  memcpy(&sa.sin_addr, he->h_addr_list[0], he->h_length);\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1012
#, no-wrap
msgid ""
"  if (connect(s, (struct sockaddr *)&sa, sizeof sa) < 0) {\n"
"    perror(\"connect\");\n"
"    return 3;\n"
"  }\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1015
#, no-wrap
msgid ""
"  while ((bytes = read(s, buf, BUFSIZ)) > 0)\n"
"    write(1, buf, bytes);\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1025
msgid ""
"We now can type a domain name (or an IP address, it works both ways) on the "
"command line, and the program will try to connect to its _daytime_ server.  "
"Otherwise, it will still default to `time.nist.gov`.  However, even in this "
"case we will use `gethostbyname` rather than hard coding `132.163.96.1`.  "
"That way, even if its IP address changes in the future, we will still find "
"it."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1029
msgid ""
"Since it takes virtually no time to get the time from your local server, you "
"could run daytime twice in a row: First to get the time from "
"`time.nist.gov`, the second time from your own system.  You can then compare "
"the results and see how exact your system clock is:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1033
#, no-wrap
msgid "% daytime ; daytime localhost\n"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1037
#, no-wrap
msgid ""
"52080 01-06-20 04:02:33 50 0 0 390.2 UTC(NIST) *\n"
"2001-06-20T04:02:35Z\n"
"%\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1040
msgid "As you can see, my system was two seconds ahead of the NIST time."
msgstr ""

#. type: Title ===
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1042
#, no-wrap
msgid "`getservbyname`"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1046
msgid ""
"Sometimes you may not be sure what port a certain service uses.  The "
"man:getservbyname[3] function, also declared in [.filename]#netdb.h# comes "
"in very handy in those cases:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1050
#, no-wrap
msgid "struct servent * getservbyname(const char *name, const char *proto);\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1053
msgid ""
"The `servent` structure contains the `s_port`, which contains the proper "
"port, already in _network byte order_."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1055
msgid ""
"Had we not known the correct port for the _daytime_ service, we could have "
"found it this way:"
msgstr ""

#. type: delimited block . 4
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1065
#, no-wrap
msgid ""
"struct servent *se;\n"
"  ...\n"
"  if ((se = getservbyname(\"daytime\", \"tcp\")) == NULL {\n"
"    fprintf(stderr, \"Cannot determine which port to use.\\n\");\n"
"    return 7;\n"
"  }\n"
"  sa.sin_port = se->s_port;\n"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1072
msgid ""
"You usually do know the port.  But if you are developing a new protocol, you "
"may be testing it on an unofficial port.  Some day, you will register the "
"protocol and its port (if nowhere else, at least in your [.filename]#/etc/"
"services#, which is where `getservbyname` looks).  Instead of returning an "
"error in the above code, you just use the temporary port number.  Once you "
"have listed the protocol in [.filename]#/etc/services#, your software will "
"find its port without you having to rewrite the code."
msgstr ""

#. type: Title ==
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1074
#, no-wrap
msgid "Concurrent Servers"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1078
msgid ""
"Unlike a sequential server, a _concurrent server_ has to be able to serve "
"more than one client at a time.  For example, a _chat server_ may be serving "
"a specific client for hours-it cannot wait till it stops serving a client "
"before it serves the next one."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1080
msgid "This requires a significant change in our flowchart:"
msgstr ""

#. type: Block title
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1081
#, no-wrap
msgid "Concurrent Server"
msgstr ""

#. type: Target for macro image
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1082
#, no-wrap
msgid "serv2.png"
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1086
msgid ""
"We moved the _serve_ from the _daemon process_ to its own _server process_.  "
"However, because each child process inherits all open files (and a socket is "
"treated just like a file), the new process inherits not only the _\"accepted "
"handle,\"_ i.e., the socket returned by the `accept` call, but also the _top "
"socket_, i.e., the one opened by the top process right at the beginning."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1089
msgid ""
"However, the _server process_ does not need this socket and should `close` "
"it immediately.  Similarly, the _daemon process_ no longer needs the "
"_accepted socket_, and not only should, but _must_ `close` it-otherwise, it "
"will run out of available _file descriptors_ sooner or later."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1092
msgid ""
"After the _server process_ is done serving, it should close the _accepted "
"socket_.  Instead of returning to `accept`, it now exits."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1099
msgid ""
"Under UNIX(R), a process does not really _exit_.  Instead, it _returns_ to "
"its parent.  Typically, a parent process ``wait``s for its child process, "
"and obtains a return value.  However, our _daemon process_ cannot simply "
"stop and wait.  That would defeat the whole purpose of creating additional "
"processes.  But if it never does `wait`, its children will become _zombies_-"
"no longer functional but still roaming around."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1102
msgid ""
"For that reason, the _daemon process_ needs to set _signal handlers_ in its "
"_initialize daemon_ phase.  At least a SIGCHLD signal has to be processed, "
"so the daemon can remove the zombie return values from the system and "
"release the system resources they are taking up."
msgstr ""

#. type: Plain text
#: documentation/content/en/books/developers-handbook/sockets/_index.adoc:1105
msgid ""
"That is why our flowchart now contains a _process signals_ box, which is not "
"connected to any other box.  By the way, many servers also process SIGHUP, "
"and typically interpret as the signal from the superuser that they should "
"reread their configuration files.  This allows us to change settings without "
"having to kill and restart these servers."
msgstr ""