1 @node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top
4 This chapter describes the GNU facilities for interprocess
5 communication using sockets.
8 @cindex interprocess communication, with sockets
9 A @dfn{socket} is a generalized interprocess communication channel.
10 Like a pipe, a socket is represented as a file descriptor. But,
11 unlike pipes, sockets support communication between unrelated
12 processes, and even between processes running on different machines
13 that communicate over a network. Sockets are the primary means of
14 communicating with other machines; @code{telnet}, @code{rlogin},
15 @code{ftp}, @code{talk}, and the other familiar network programs use
18 Not all operating systems support sockets. In the GNU library, the
19 header file @file{sys/socket.h} exists regardless of the operating
20 system, and the socket functions always exist, but if the system does
21 not really support sockets, these functions always fail.
23 @strong{Incomplete:} We do not currently document the facilities for
24 broadcast messages or for configuring Internet interfaces.
27 * Socket Concepts:: Basic concepts you need to know about.
28 * Communication Styles::Stream communication, datagrams, and other styles.
29 * Socket Addresses:: How socket names (``addresses'') work.
30 * File Namespace:: Details about the file namespace.
31 * Internet Namespace:: Details about the Internet namespace.
32 * Misc Namespaces:: Other namespaces not documented fully here.
33 * Open/Close Sockets:: Creating sockets and destroying them.
34 * Connections:: Operations on sockets with connection state.
35 * Datagrams:: Operations on datagram sockets.
36 * Inetd:: Inetd is a daemon that starts servers on request.
37 The most convenient way to write a server
38 is to make it work with Inetd.
39 * Socket Options:: Miscellaneous low-level socket options.
40 * Networks Database:: Accessing the database of network names.
44 @section Socket Concepts
46 @cindex communication style (of a socket)
47 @cindex style of communication (of a socket)
48 When you create a socket, you must specify the style of communication
49 you want to use and the type of protocol that should implement it.
50 The @dfn{communication style} of a socket defines the user-level
51 semantics of sending and receiving data on the socket. Choosing a
52 communication style specifies the answers to questions such as these:
58 @cindex stream (sockets)
59 @strong{What are the units of data transmission?} Some communication
60 styles regard the data as a sequence of bytes, with no larger
61 structure; others group the bytes into records (which are known in
62 this context as @dfn{packets}).
65 @cindex loss of data on sockets
66 @cindex data loss on sockets
67 @strong{Can data be lost during normal operation?} Some communication
68 styles guarantee that all the data sent arrives in the order it was
69 sent (barring system or network crashes); other styles occasionally
70 lose data as a normal part of operation, and may sometimes deliver
71 packets more than once or in the wrong order.
73 Designing a program to use unreliable communication styles usually
74 involves taking precautions to detect lost or misordered packets and
75 to retransmit data as needed.
78 @strong{Is communication entirely with one partner?} Some
79 communication styles are like a telephone call---you make a
80 @dfn{connection} with one remote socket, and then exchange data
81 freely. Other styles are like mailing letters---you specify a
82 destination address for each message you send.
85 @cindex namespace (of socket)
86 @cindex domain (of socket)
87 @cindex socket namespace
89 You must also choose a @dfn{namespace} for naming the socket. A socket
90 name (``address'') is meaningful only in the context of a particular
91 namespace. In fact, even the data type to use for a socket name may
92 depend on the namespace. Namespaces are also called ``domains'', but we
93 avoid that word as it can be confused with other usage of the same
94 term. Each namespace has a symbolic name that starts with @samp{PF_}.
95 A corresponding symbolic name starting with @samp{AF_} designates the
96 address format for that namespace.
98 @cindex network protocol
99 @cindex protocol (of socket)
100 @cindex socket protocol
101 @cindex protocol family
102 Finally you must choose the @dfn{protocol} to carry out the
103 communication. The protocol determines what low-level mechanism is used
104 to transmit and receive data. Each protocol is valid for a particular
105 namespace and communication style; a namespace is sometimes called a
106 @dfn{protocol family} because of this, which is why the namespace names
107 start with @samp{PF_}.
109 The rules of a protocol apply to the data passing between two programs,
110 perhaps on different computers; most of these rules are handled by the
111 operating system, and you need not know about them. What you do need to
112 know about protocols is this:
116 In order to have communication between two sockets, they must specify
117 the @emph{same} protocol.
120 Each protocol is meaningful with particular style/namespace
121 combinations and cannot be used with inappropriate combinations. For
122 example, the TCP protocol fits only the byte stream style of
123 communication and the Internet namespace.
126 For each combination of style and namespace, there is a @dfn{default
127 protocol} which you can request by specifying 0 as the protocol
128 number. And that's what you should normally do---use the default.
131 Throughout the following description at various places
132 variables/parameters to denote sizes are required. And here the trouble
133 starts. In the first implementations the type of these variables was
134 simply @code{int}. This type was on almost all machines of this time 32
135 bits wide and so a de-factor standard required 32 bit variables. This
136 is important since references to variables of this type are passed to
139 But now the POSIX people came and unified the interface with their words
140 "all size values are of type @code{size_t}". But on 64 bit machines
141 @code{size_t} is 64 bits wide and so variable references are not anymore
144 A solution provides the Unix98 specification which finally introduces a
145 type @code{socklen_t}. This type is used in all of the cases that were
146 previously changed to use @code{size_t}. The only requirement of this
147 type is that it is an unsigned type of at least 32 bits. Therefore,
148 implementations which require references to 32 bit variables be passed
149 can be as happy as implementations which use right from the start 64 bit
153 @node Communication Styles
154 @section Communication Styles
156 The GNU library includes support for several different kinds of sockets,
157 each with different characteristics. This section describes the
158 supported socket types. The symbolic constants listed here are
159 defined in @file{sys/socket.h}.
162 @comment sys/socket.h
164 @deftypevr Macro int SOCK_STREAM
165 The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs});
166 it operates over a connection with a particular remote socket, and
167 transmits data reliably as a stream of bytes.
169 Use of this style is covered in detail in @ref{Connections}.
172 @comment sys/socket.h
174 @deftypevr Macro int SOCK_DGRAM
175 The @code{SOCK_DGRAM} style is used for sending
176 individually-addressed packets, unreliably.
177 It is the diametrical opposite of @code{SOCK_STREAM}.
179 Each time you write data to a socket of this kind, that data becomes
180 one packet. Since @code{SOCK_DGRAM} sockets do not have connections,
181 you must specify the recipient address with each packet.
183 The only guarantee that the system makes about your requests to
184 transmit data is that it will try its best to deliver each packet you
185 send. It may succeed with the sixth packet after failing with the
186 fourth and fifth packets; the seventh packet may arrive before the
187 sixth, and may arrive a second time after the sixth.
189 The typical use for @code{SOCK_DGRAM} is in situations where it is
190 acceptable to simply resend a packet if no response is seen in a
191 reasonable amount of time.
193 @xref{Datagrams}, for detailed information about how to use datagram
198 @c This appears to be only for the NS domain, which we aren't
199 @c discussing and probably won't support either.
200 @comment sys/socket.h
202 @deftypevr Macro int SOCK_SEQPACKET
203 This style is like @code{SOCK_STREAM} except that the data is
204 structured into packets.
206 A program that receives data over a @code{SOCK_SEQPACKET} socket
207 should be prepared to read the entire message packet in a single call
208 to @code{read}; if it only reads part of the message, the remainder of
209 the message is simply discarded instead of being available for
210 subsequent calls to @code{read}.
212 Many protocols do not support this communication style.
217 @comment sys/socket.h
219 @deftypevr Macro int SOCK_RDM
220 This style is a reliable version of @code{SOCK_DGRAM}: it sends
221 individually addressed packets, but guarantees that each packet sent
222 arrives exactly once.
224 @strong{Warning:} It is not clear this is actually supported
225 by any operating system.
229 @comment sys/socket.h
231 @deftypevr Macro int SOCK_RAW
232 This style provides access to low-level network protocols and
233 interfaces. Ordinary user programs usually have no need to use this
237 @node Socket Addresses
238 @section Socket Addresses
240 @cindex address of socket
241 @cindex name of socket
242 @cindex binding a socket address
243 @cindex socket address (name) binding
244 The name of a socket is normally called an @dfn{address}. The
245 functions and symbols for dealing with socket addresses were named
246 inconsistently, sometimes using the term ``name'' and sometimes using
247 ``address''. You can regard these terms as synonymous where sockets
250 A socket newly created with the @code{socket} function has no
251 address. Other processes can find it for communication only if you
252 give it an address. We call this @dfn{binding} the address to the
253 socket, and the way to do it is with the @code{bind} function.
255 You need be concerned with the address of a socket if other processes
256 are to find it and start communicating with it. You can specify an
257 address for other sockets, but this is usually pointless; the first time
258 you send data from a socket, or use it to initiate a connection, the
259 system assigns an address automatically if you have not specified one.
261 Occasionally a client needs to specify an address because the server
262 discriminates based on addresses; for example, the rsh and rlogin
263 protocols look at the client's socket address and don't bypass password
264 checking unless it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
266 The details of socket addresses vary depending on what namespace you are
267 using. @xref{File Namespace}, or @ref{Internet Namespace}, for specific
270 Regardless of the namespace, you use the same functions @code{bind} and
271 @code{getsockname} to set and examine a socket's address. These
272 functions use a phony data type, @code{struct sockaddr *}, to accept the
273 address. In practice, the address lives in a structure of some other
274 data type appropriate to the address format you are using, but you cast
275 its address to @code{struct sockaddr *} when you pass it to
279 * Address Formats:: About @code{struct sockaddr}.
280 * Setting Address:: Binding an address to a socket.
281 * Reading Address:: Reading the address of a socket.
284 @node Address Formats
285 @subsection Address Formats
287 The functions @code{bind} and @code{getsockname} use the generic data
288 type @code{struct sockaddr *} to represent a pointer to a socket
289 address. You can't use this data type effectively to interpret an
290 address or construct one; for that, you must use the proper data type
291 for the socket's namespace.
293 Thus, the usual practice is to construct an address in the proper
294 namespace-specific type, then cast a pointer to @code{struct sockaddr *}
295 when you call @code{bind} or @code{getsockname}.
297 The one piece of information that you can get from the @code{struct
298 sockaddr} data type is the @dfn{address format} designator which tells
299 you which data type to use to understand the address fully.
302 The symbols in this section are defined in the header file
305 @comment sys/socket.h
307 @deftp {Date Type} {struct sockaddr}
308 The @code{struct sockaddr} type itself has the following members:
311 @item short int sa_family
312 This is the code for the address format of this address. It
313 identifies the format of the data which follows.
315 @item char sa_data[14]
316 This is the actual socket address data, which is format-dependent. Its
317 length also depends on the format, and may well be more than 14. The
318 length 14 of @code{sa_data} is essentially arbitrary.
322 Each address format has a symbolic name which starts with @samp{AF_}.
323 Each of them corresponds to a @samp{PF_} symbol which designates the
324 corresponding namespace. Here is a list of address format names:
327 @comment sys/socket.h
331 This designates the address format that goes with the file namespace.
332 (@code{PF_FILE} is the name of that namespace.) @xref{File Namespace
333 Details}, for information about this address format.
335 @comment sys/socket.h
339 This is a synonym for @code{AF_FILE}, for compatibility.
340 (@code{PF_UNIX} is likewise a synonym for @code{PF_FILE}.)
342 @comment sys/socket.h
346 This designates the address format that goes with the Internet
347 namespace. (@code{PF_INET} is the name of that namespace.)
348 @xref{Internet Address Formats}.
350 @comment sys/socket.h
351 @comment IPv6 Basic API
353 This is similar to @code{AF_INET}, but refers to the IPv6 protocol.
354 (@code{PF_INET6} is the name of the corresponding namespace.)
356 @comment sys/socket.h
360 This designates no particular address format. It is used only in rare
361 cases, such as to clear out the default destination address of a
362 ``connected'' datagram socket. @xref{Sending Datagrams}.
364 The corresponding namespace designator symbol @code{PF_UNSPEC} exists
365 for completeness, but there is no reason to use it in a program.
368 @file{sys/socket.h} defines symbols starting with @samp{AF_} for many
369 different kinds of networks, all or most of which are not actually
370 implemented. We will document those that really work, as we receive
371 information about how to use them.
373 @node Setting Address
374 @subsection Setting the Address of a Socket
377 Use the @code{bind} function to assign an address to a socket. The
378 prototype for @code{bind} is in the header file @file{sys/socket.h}.
379 For examples of use, see @ref{File Namespace}, or see @ref{Inet Example}.
381 @comment sys/socket.h
383 @deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
384 The @code{bind} function assigns an address to the socket
385 @var{socket}. The @var{addr} and @var{length} arguments specify the
386 address; the detailed format of the address depends on the namespace.
387 The first part of the address is always the format designator, which
388 specifies a namespace, and says that the address is in the format for
391 The return value is @code{0} on success and @code{-1} on failure. The
392 following @code{errno} error conditions are defined for this function:
396 The @var{socket} argument is not a valid file descriptor.
399 The descriptor @var{socket} is not a socket.
402 The specified address is not available on this machine.
405 Some other socket is already using the specified address.
408 The socket @var{socket} already has an address.
411 You do not have permission to access the requested address. (In the
412 Internet domain, only the super-user is allowed to specify a port number
413 in the range 0 through @code{IPPORT_RESERVED} minus one; see
417 Additional conditions may be possible depending on the particular namespace
421 @node Reading Address
422 @subsection Reading the Address of a Socket
425 Use the function @code{getsockname} to examine the address of an
426 Internet socket. The prototype for this function is in the header file
429 @comment sys/socket.h
431 @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
432 The @code{getsockname} function returns information about the
433 address of the socket @var{socket} in the locations specified by the
434 @var{addr} and @var{length-ptr} arguments. Note that the
435 @var{length-ptr} is a pointer; you should initialize it to be the
436 allocation size of @var{addr}, and on return it contains the actual
437 size of the address data.
439 The format of the address data depends on the socket namespace. The
440 length of the information is usually fixed for a given namespace, so
441 normally you can know exactly how much space is needed and can provide
442 that much. The usual practice is to allocate a place for the value
443 using the proper data type for the socket's namespace, then cast its
444 address to @code{struct sockaddr *} to pass it to @code{getsockname}.
446 The return value is @code{0} on success and @code{-1} on error. The
447 following @code{errno} error conditions are defined for this function:
451 The @var{socket} argument is not a valid file descriptor.
454 The descriptor @var{socket} is not a socket.
457 There are not enough internal buffers available for the operation.
461 You can't read the address of a socket in the file namespace. This is
462 consistent with the rest of the system; in general, there's no way to
463 find a file's name from a descriptor for that file.
466 @section The File Namespace
467 @cindex file namespace, for sockets
469 This section describes the details of the file namespace, whose
470 symbolic name (required when you create a socket) is @code{PF_FILE}.
473 * Concepts: File Namespace Concepts. What you need to understand.
474 * Details: File Namespace Details. Address format, symbolic names, etc.
475 * Example: File Socket Example. Example of creating a socket.
478 @node File Namespace Concepts
479 @subsection File Namespace Concepts
481 In the file namespace, socket addresses are file names. You can specify
482 any file name you want as the address of the socket, but you must have
483 write permission on the directory containing it. In order to connect to
484 a socket, you must have read permission for it. It's common to put
485 these files in the @file{/tmp} directory.
487 One peculiarity of the file namespace is that the name is only used when
488 opening the connection; once that is over with, the address is not
489 meaningful and may not exist.
491 Another peculiarity is that you cannot connect to such a socket from
492 another machine--not even if the other machine shares the file system
493 which contains the name of the socket. You can see the socket in a
494 directory listing, but connecting to it never succeeds. Some programs
495 take advantage of this, such as by asking the client to send its own
496 process ID, and using the process IDs to distinguish between clients.
497 However, we recommend you not use this method in protocols you design,
498 as we might someday permit connections from other machines that mount
499 the same file systems. Instead, send each new client an identifying
500 number if you want it to have one.
502 After you close a socket in the file namespace, you should delete the
503 file name from the file system. Use @code{unlink} or @code{remove} to
504 do this; see @ref{Deleting Files}.
506 The file namespace supports just one protocol for any communication
507 style; it is protocol number @code{0}.
509 @node File Namespace Details
510 @subsection Details of File Namespace
513 To create a socket in the file namespace, use the constant
514 @code{PF_FILE} as the @var{namespace} argument to @code{socket} or
515 @code{socketpair}. This constant is defined in @file{sys/socket.h}.
517 @comment sys/socket.h
519 @deftypevr Macro int PF_FILE
520 This designates the file namespace, in which socket addresses are file
521 names, and its associated family of protocols.
524 @comment sys/socket.h
526 @deftypevr Macro int PF_UNIX
527 This is a synonym for @code{PF_FILE}, for compatibility's sake.
530 The structure for specifying socket names in the file namespace is
531 defined in the header file @file{sys/un.h}:
536 @deftp {Data Type} {struct sockaddr_un}
537 This structure is used to specify file namespace socket addresses. It has
538 the following members:
541 @item short int sun_family
542 This identifies the address family or format of the socket address.
543 You should store the value @code{AF_FILE} to designate the file
544 namespace. @xref{Socket Addresses}.
546 @item char sun_path[108]
547 This is the file name to use.
549 @strong{Incomplete:} Why is 108 a magic number? RMS suggests making
550 this a zero-length array and tweaking the example following to use
551 @code{alloca} to allocate an appropriate amount of storage based on
552 the length of the filename.
556 You should compute the @var{length} parameter for a socket address in
557 the file namespace as the sum of the size of the @code{sun_family}
558 component and the string length (@emph{not} the allocation size!) of
559 the file name string.
561 @node File Socket Example
562 @subsection Example of File-Namespace Sockets
564 Here is an example showing how to create and name a socket in the file
568 @include mkfsock.c.texi
571 @node Internet Namespace
572 @section The Internet Namespace
573 @cindex Internet namespace, for sockets
575 This section describes the details the protocols and socket naming
576 conventions used in the Internet namespace.
578 To create a socket in the Internet namespace, use the symbolic name
579 @code{PF_INET} of this namespace as the @var{namespace} argument to
580 @code{socket} or @code{socketpair}. This macro is defined in
584 @comment sys/socket.h
586 @deftypevr Macro int PF_INET
587 This designates the Internet namespace and associated family of
591 A socket address for the Internet namespace includes the following components:
595 The address of the machine you want to connect to. Internet addresses
596 can be specified in several ways; these are discussed in @ref{Internet
597 Address Formats}, @ref{Host Addresses}, and @ref{Host Names}.
600 A port number for that machine. @xref{Ports}.
603 You must ensure that the address and port number are represented in a
604 canonical format called @dfn{network byte order}. @xref{Byte Order},
605 for information about this.
608 * Internet Address Formats:: How socket addresses are specified in the
610 * Host Addresses:: All about host addresses of internet host.
611 * Protocols Database:: Referring to protocols by name.
612 * Ports:: Internet port numbers.
613 * Services Database:: Ports may have symbolic names.
614 * Byte Order:: Different hosts may use different byte
615 ordering conventions; you need to
616 canonicalize host address and port number.
617 * Inet Example:: Putting it all together.
620 @node Internet Address Formats
621 @subsection Internet Socket Address Formats
623 In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6
624 (@code{AF_INET6}), a socket address consists of a host address
625 and a port on that host. In addition, the protocol you choose serves
626 effectively as a part of the address because local port numbers are
627 meaningful only within a particular protocol.
629 The data types for representing socket addresses in the Internet namespace
630 are defined in the header file @file{netinet/in.h}.
633 @comment netinet/in.h
635 @deftp {Data Type} {struct sockaddr_in}
636 This is the data type used to represent socket addresses in the
637 Internet namespace. It has the following members:
640 @item short int sin_family
641 This identifies the address family or format of the socket address.
642 You should store the value of @code{AF_INET} in this member.
643 @xref{Socket Addresses}.
645 @item struct in_addr sin_addr
646 This is the Internet address of the host machine. @xref{Host
647 Addresses}, and @ref{Host Names}, for how to get a value to store
650 @item unsigned short int sin_port
651 This is the port number. @xref{Ports}.
655 When you call @code{bind} or @code{getsockname}, you should specify
656 @code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
657 you are using an Internet namespace socket address.
659 @deftp {Data Type} {struct sockaddr_in6}
660 This is the data type used to represent socket addresses in the IPv6
661 namespace. It has the following members:
664 @item short int sin6_family
665 This identifies the address family or format of the socket address.
666 You should store the value of @code{AF_INET6} in this member.
667 @xref{Socket Addresses}.
669 @item struct in6_addr sin6_addr
670 This is the IPv6 address of the host machine. @xref{Host
671 Addresses}, and @ref{Host Names}, for how to get a value to store
674 @item uint32_t sin6_flowinfo
675 This is a currently unimplemented field.
677 @item uint16_t sin6_port
678 This is the port number. @xref{Ports}.
684 @subsection Host Addresses
686 Each computer on the Internet has one or more @dfn{Internet addresses},
687 numbers which identify that computer among all those on the Internet.
688 Users typically write IPv4 numeric host addresses as sequences of four
689 numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6
690 numeric host addresses as sequences of up to eight numbers separated by
691 colons, as in @samp{5f03:1200:836f:c100::1}.
693 Each computer also has one or more @dfn{host names}, which are strings
694 of words separated by periods, as in @samp{churchy.gnu.ai.mit.edu}.
696 Programs that let the user specify a host typically accept both numeric
697 addresses and host names. But the program needs a numeric address to
698 open a connection; to use a host name, you must convert it to the
699 numeric address it stands for.
702 * Abstract Host Addresses:: What a host number consists of.
703 * Data type: Host Address Data Type. Data type for a host number.
704 * Functions: Host Address Functions. Functions to operate on them.
705 * Names: Host Names. Translating host names to host numbers.
708 @node Abstract Host Addresses
709 @subsubsection Internet Host Addresses
710 @cindex host address, Internet
711 @cindex Internet host address
714 Each computer on the Internet has one or more Internet addresses,
715 numbers which identify that computer among all those on the Internet.
718 @c I think this whole section could possibly be removed. It is slightly
719 @c misleading these days.
721 @cindex network number
722 @cindex local network address number
723 An Internet host address is a number containing four bytes of data.
724 These are divided into two parts, a @dfn{network number} and a
725 @dfn{local network address number} within that network. The network
726 number consists of the first one, two or three bytes; the rest of the
727 bytes are the local address.
729 Network numbers are registered with the Network Information Center
730 (NIC), and are divided into three classes---A, B, and C. The local
731 network address numbers of individual machines are registered with the
732 administrator of the particular network.
734 Class A networks have single-byte numbers in the range 0 to 127. There
735 are only a small number of Class A networks, but they can each support a
736 very large number of hosts. Medium-sized Class B networks have two-byte
737 network numbers, with the first byte in the range 128 to 191. Class C
738 networks are the smallest; they have three-byte network numbers, with
739 the first byte in the range 192-255. Thus, the first 1, 2, or 3 bytes
740 of an Internet address specifies a network. The remaining bytes of the
741 Internet address specify the address within that network.
743 The Class A network 0 is reserved for broadcast to all networks. In
744 addition, the host number 0 within each network is reserved for broadcast
745 to all hosts in that network.
747 The Class A network 127 is reserved for loopback; you can always use
748 the Internet address @samp{127.0.0.1} to refer to the host machine.
750 Since a single machine can be a member of multiple networks, it can
751 have multiple Internet host addresses. However, there is never
752 supposed to be more than one machine with the same host address.
754 @c !!! this section could document the IN_CLASS* macros in <netinet/in.h>.
756 @cindex standard dot notation, for Internet addresses
757 @cindex dot notation, for Internet addresses
758 There are four forms of the @dfn{standard numbers-and-dots notation}
759 for Internet addresses:
762 @item @var{a}.@var{b}.@var{c}.@var{d}
763 This specifies all four bytes of the address individually.
765 @item @var{a}.@var{b}.@var{c}
766 The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
767 This is useful for specifying host addresses in a Class B network with
768 network address number @code{@var{a}.@var{b}}.
770 @item @var{a}.@var{b}
771 The last part of the address, @var{c}, is interpreted as a 3-byte quantity.
772 This is useful for specifying host addresses in a Class A network with
773 network address number @var{a}.
776 If only one part is given, this corresponds directly to the host address
780 Within each part of the address, the usual C conventions for specifying
781 the radix apply. In other words, a leading @samp{0x} or @samp{0X} implies
782 hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
785 @node Host Address Data Type
786 @subsubsection Host Address Data Type
788 Internet host addresses are represented in some contexts as integers
789 (type @code{unsigned long int}). In other contexts, the integer is
790 packaged inside a structure of type @code{struct in_addr}. It would
791 be better if the usage were made consistent, but it is not hard to extract
792 the integer from the structure or put the integer into a structure.
794 The following basic definitions for Internet addresses appear in the
795 header file@*@file{netinet/in.h}:
798 @comment netinet/in.h
800 @deftp {Data Type} {struct in_addr}
801 This data type is used in certain contexts to contain an Internet host
802 address. It has just one field, named @code{s_addr}, which records the
803 host address number as an @code{unsigned long int}.
806 @comment netinet/in.h
808 @deftypevr Macro {unsigned int} INADDR_LOOPBACK
809 You can use this constant to stand for ``the address of this machine,''
810 instead of finding its actual address. It is the Internet address
811 @samp{127.0.0.1}, which is usually called @samp{localhost}. This
812 special constant saves you the trouble of looking up the address of your
813 own machine. Also, the system usually implements @code{INADDR_LOOPBACK}
814 specially, avoiding any network traffic for the case of one machine
818 @comment netinet/in.h
820 @deftypevr Macro {unsigned int} INADDR_ANY
821 You can use this constant to stand for ``any incoming address,'' when
822 binding to an address. @xref{Setting Address}. This is the usual
823 address to give in the @code{sin_addr} member of @w{@code{struct
824 sockaddr_in}} when you want to accept Internet connections.
827 @comment netinet/in.h
829 @deftypevr Macro {unsigned int} INADDR_BROADCAST
830 This constant is the address you use to send a broadcast message.
831 @c !!! broadcast needs further documented
834 @comment netinet/in.h
836 @deftypevr Macro {unsigned int} INADDR_NONE
837 This constant is returned by some functions to indicate an error.
840 @comment netinet/in.h
841 @comment IPv6 basic API
842 @deftp {Data Type} {struct in6_addr}
843 This data type is used to store an IPv6 address. It stores 128 bits of
844 data, which can be accessed (via a union) in a variety of ways.
847 @comment netinet/in.h
848 @comment IPv6 basic API
849 @deftypevr Constant {struct in6_addr} in6addr_loopback.
850 This constant is the IPv6 address @samp{::1}, the loopback address. See
851 above for a description of what this means. The macro
852 @code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialise your
853 own variables to this value.
856 @comment netinet/in.h
857 @comment IPv6 basic API
858 @deftypevr Constant {struct in6_addr} in6addr_any
859 This constant is the IPv6 address @samp{::}, the unspecified address. See
860 above for a description of what this means. The macro
861 @code{IN6ADDR_ANY_INIT} is provided to allow you to initialise your
862 own variables to this value.
865 @node Host Address Functions
866 @subsubsection Host Address Functions
870 These additional functions for manipulating Internet addresses are
871 declared in@*@file{arpa/inet.h}. They represent Internet addresses in
872 network byte order; they represent network numbers and
873 local-address-within-network numbers in host byte order.
874 @xref{Byte Order}, for an explanation of network and host byte order.
878 @deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr})
879 This function converts the Internet host address @var{name}
880 from the standard numbers-and-dots notation into binary data and stores
881 it in the @code{struct in_addr} that @var{addr} points to.
882 @code{inet_aton} returns nonzero if the address is valid, zero if not.
887 @deftypefun {unsigned long int} inet_addr (const char *@var{name})
888 This function converts the Internet host address @var{name} from the
889 standard numbers-and-dots notation into binary data. If the input is
890 not valid, @code{inet_addr} returns @code{INADDR_NONE}. This is an
891 obsolete interface to @code{inet_aton}, described immediately above; it
892 is obsolete because @code{INADDR_NONE} is a valid address
893 (255.255.255.255), and @code{inet_aton} provides a cleaner way to
894 indicate error return.
899 @deftypefun {unsigned long int} inet_network (const char *@var{name})
900 This function extracts the network number from the address @var{name},
901 given in the standard numbers-and-dots notation. The returned address is
902 in host order. If the input is not valid, @code{inet_network} returns
908 @deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
909 This function converts the Internet host address @var{addr} to a
910 string in the standard numbers-and-dots notation. The return value is
911 a pointer into a statically-allocated buffer. Subsequent calls will
912 overwrite the same buffer, so you should copy the string if you need
915 In multi-threaded programs each thread has an own statically-allocated
916 buffer. But still subsequent calls of @code{inet_ntoa} in the same
917 thread will overwrite the result of the last call.
922 @deftypefun {struct in_addr} inet_makeaddr (int @var{net}, int @var{local})
923 This function makes an Internet host address by combining the network
924 number @var{net} with the local-address-within-network number
930 @deftypefun int inet_lnaof (struct in_addr @var{addr})
931 This function returns the local-address-within-network part of the
932 Internet host address @var{addr}.
937 @deftypefun int inet_netof (struct in_addr @var{addr})
938 This function returns the network number part of the Internet host
943 @comment IPv6 basic API
944 @deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf})
945 This function converts an Internet address (either IPv4 or IPv6) from
946 presentation (textual) to network (binary) format. @var{af} should be
947 either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of
948 address being converted. @var{cp} is a pointer to the input string, and
949 @var{buf} is a pointer to a buffer for the result. It is the caller's
950 responsibility to make sure the buffer is large enough.
954 @comment IPv6 basic API
955 @deftypefun {char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, size_t @var{len})
956 This function converts an Internet address (either IPv4 or IPv6) from
957 network (binary) to presentation (textual) form. @var{af} should be
958 either @code{AF_INET} or @code{AF_INET6}, as appropriate. @var{cp} is a
959 pointer to the address to be converted. @var{buf} should be a pointer
960 to a buffer to hold the result, and @var{len} is the length of this
961 buffer. The return value from the function will be this buffer address.
965 @subsubsection Host Names
966 @cindex hosts database
967 @cindex converting host name to address
968 @cindex converting host address to name
970 Besides the standard numbers-and-dots notation for Internet addresses,
971 you can also refer to a host by a symbolic name. The advantage of a
972 symbolic name is that it is usually easier to remember. For example,
973 the machine with Internet address @samp{128.52.46.32} is also known as
974 @samp{churchy.gnu.ai.mit.edu}; and other machines in the @samp{gnu.ai.mit.edu}
975 domain can refer to it simply as @samp{churchy}.
979 Internally, the system uses a database to keep track of the mapping
980 between host names and host numbers. This database is usually either
981 the file @file{/etc/hosts} or an equivalent provided by a name server.
982 The functions and other symbols for accessing this database are declared
983 in @file{netdb.h}. They are BSD features, defined unconditionally if
984 you include @file{netdb.h}.
988 @deftp {Data Type} {struct hostent}
989 This data type is used to represent an entry in the hosts database. It
990 has the following members:
994 This is the ``official'' name of the host.
996 @item char **h_aliases
997 These are alternative names for the host, represented as a null-terminated
1000 @item int h_addrtype
1001 This is the host address type; in practice, its value is always either
1002 @code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6
1003 hosts. In principle other kinds of addresses could be represented in
1004 the data base as well as Internet addresses; if this were done, you
1005 might find a value in this field other than @code{AF_INET} or
1006 @code{AF_INET6}. @xref{Socket Addresses}.
1009 This is the length, in bytes, of each address.
1011 @item char **h_addr_list
1012 This is the vector of addresses for the host. (Recall that the host
1013 might be connected to multiple networks and have different addresses on
1014 each one.) The vector is terminated by a null pointer.
1017 This is a synonym for @code{h_addr_list[0]}; in other words, it is the
1022 As far as the host database is concerned, each address is just a block
1023 of memory @code{h_length} bytes long. But in other contexts there is an
1024 implicit assumption that you can convert this to a @code{struct in_addr} or
1025 an @code{unsigned long int}. Host addresses in a @code{struct hostent}
1026 structure are always given in network byte order; see @ref{Byte Order}.
1028 You can use @code{gethostbyname}, @code{gethostbyname2} or
1029 @code{gethostbyaddr} to search the hosts database for information about
1030 a particular host. The information is returned in a
1031 statically-allocated structure; you must copy the information if you
1032 need to save it across calls. You can also use @code{getaddrinfo} and
1033 @code{getnameinfo} to obtain this information.
1037 @deftypefun {struct hostent *} gethostbyname (const char *@var{name})
1038 The @code{gethostbyname} function returns information about the host
1039 named @var{name}. If the lookup fails, it returns a null pointer.
1043 @comment IPv6 Basic API
1044 @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
1045 The @code{gethostbyname2} function is like @code{gethostbyname}, but
1046 allows the caller to specify the desired address family (e.g.@:
1047 @code{AF_INET} or @code{AF_INET6}) for the result.
1052 @deftypefun {struct hostent *} gethostbyaddr (const char *@var{addr}, int @var{length}, int @var{format})
1053 The @code{gethostbyaddr} function returns information about the host
1054 with Internet address @var{addr}. The @var{length} argument is the
1055 size (in bytes) of the address at @var{addr}. @var{format} specifies
1056 the address format; for an Internet address, specify a value of
1059 If the lookup fails, @code{gethostbyaddr} returns a null pointer.
1063 If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
1064 fails, you can find out the reason by looking at the value of the
1065 variable @code{h_errno}. (It would be cleaner design for these
1066 functions to set @code{errno}, but use of @code{h_errno} is compatible
1067 with other systems.) Before using @code{h_errno}, you must declare it
1074 Here are the error codes that you may find in @code{h_errno}:
1079 @item HOST_NOT_FOUND
1080 @vindex HOST_NOT_FOUND
1081 No such host is known in the data base.
1087 This condition happens when the name server could not be contacted. If
1088 you try again later, you may succeed then.
1094 A non-recoverable error occurred.
1100 The host database contains an entry for the name, but it doesn't have an
1101 associated Internet address.
1104 You can also scan the entire hosts database one entry at a time using
1105 @code{sethostent}, @code{gethostent}, and @code{endhostent}. Be careful
1106 in using these functions, because they are not reentrant.
1110 @deftypefun void sethostent (int @var{stayopen})
1111 This function opens the hosts database to begin scanning it. You can
1112 then call @code{gethostent} to read the entries.
1114 @c There was a rumor that this flag has different meaning if using the DNS,
1115 @c but it appears this description is accurate in that case also.
1116 If the @var{stayopen} argument is nonzero, this sets a flag so that
1117 subsequent calls to @code{gethostbyname} or @code{gethostbyaddr} will
1118 not close the database (as they usually would). This makes for more
1119 efficiency if you call those functions several times, by avoiding
1120 reopening the database for each call.
1125 @deftypefun {struct hostent *} gethostent ()
1126 This function returns the next entry in the hosts database. It
1127 returns a null pointer if there are no more entries.
1132 @deftypefun void endhostent ()
1133 This function closes the hosts database.
1137 @subsection Internet Ports
1140 A socket address in the Internet namespace consists of a machine's
1141 Internet address plus a @dfn{port number} which distinguishes the
1142 sockets on a given machine (for a given protocol). Port numbers range
1145 Port numbers less than @code{IPPORT_RESERVED} are reserved for standard
1146 servers, such as @code{finger} and @code{telnet}. There is a database
1147 that keeps track of these, and you can use the @code{getservbyname}
1148 function to map a service name onto a port number; see @ref{Services
1151 If you write a server that is not one of the standard ones defined in
1152 the database, you must choose a port number for it. Use a number
1153 greater than @code{IPPORT_USERRESERVED}; such numbers are reserved for
1154 servers and won't ever be generated automatically by the system.
1155 Avoiding conflicts with servers being run by other users is up to you.
1157 When you use a socket without specifying its address, the system
1158 generates a port number for it. This number is between
1159 @code{IPPORT_RESERVED} and @code{IPPORT_USERRESERVED}.
1161 On the Internet, it is actually legitimate to have two different
1162 sockets with the same port number, as long as they never both try to
1163 communicate with the same socket address (host address plus port
1164 number). You shouldn't duplicate a port number except in special
1165 circumstances where a higher-level protocol requires it. Normally,
1166 the system won't let you do it; @code{bind} normally insists on
1167 distinct port numbers. To reuse a port number, you must set the
1168 socket option @code{SO_REUSEADDR}. @xref{Socket-Level Options}.
1170 @pindex netinet/in.h
1171 These macros are defined in the header file @file{netinet/in.h}.
1173 @comment netinet/in.h
1175 @deftypevr Macro int IPPORT_RESERVED
1176 Port numbers less than @code{IPPORT_RESERVED} are reserved for
1180 @comment netinet/in.h
1182 @deftypevr Macro int IPPORT_USERRESERVED
1183 Port numbers greater than or equal to @code{IPPORT_USERRESERVED} are
1184 reserved for explicit use; they will never be allocated automatically.
1187 @node Services Database
1188 @subsection The Services Database
1189 @cindex services database
1190 @cindex converting service name to port number
1191 @cindex converting port number to service name
1193 @pindex /etc/services
1194 The database that keeps track of ``well-known'' services is usually
1195 either the file @file{/etc/services} or an equivalent from a name server.
1196 You can use these utilities, declared in @file{netdb.h}, to access
1197 the services database.
1202 @deftp {Data Type} {struct servent}
1203 This data type holds information about entries from the services database.
1204 It has the following members:
1208 This is the ``official'' name of the service.
1210 @item char **s_aliases
1211 These are alternate names for the service, represented as an array of
1212 strings. A null pointer terminates the array.
1215 This is the port number for the service. Port numbers are given in
1216 network byte order; see @ref{Byte Order}.
1219 This is the name of the protocol to use with this service.
1220 @xref{Protocols Database}.
1224 To get information about a particular service, use the
1225 @code{getservbyname} or @code{getservbyport} functions. The information
1226 is returned in a statically-allocated structure; you must copy the
1227 information if you need to save it across calls.
1231 @deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto})
1232 The @code{getservbyname} function returns information about the
1233 service named @var{name} using protocol @var{proto}. If it can't find
1234 such a service, it returns a null pointer.
1236 This function is useful for servers as well as for clients; servers
1237 use it to determine which port they should listen on (@pxref{Listening}).
1242 @deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto})
1243 The @code{getservbyport} function returns information about the
1244 service at port @var{port} using protocol @var{proto}. If it can't
1245 find such a service, it returns a null pointer.
1249 You can also scan the services database using @code{setservent},
1250 @code{getservent}, and @code{endservent}. Be careful in using these
1251 functions, because they are not reentrant.
1255 @deftypefun void setservent (int @var{stayopen})
1256 This function opens the services database to begin scanning it.
1258 If the @var{stayopen} argument is nonzero, this sets a flag so that
1259 subsequent calls to @code{getservbyname} or @code{getservbyport} will
1260 not close the database (as they usually would). This makes for more
1261 efficiency if you call those functions several times, by avoiding
1262 reopening the database for each call.
1267 @deftypefun {struct servent *} getservent (void)
1268 This function returns the next entry in the services database. If
1269 there are no more entries, it returns a null pointer.
1274 @deftypefun void endservent (void)
1275 This function closes the services database.
1279 @subsection Byte Order Conversion
1280 @cindex byte order conversion, for socket
1281 @cindex converting byte order
1284 @cindex little-endian
1285 Different kinds of computers use different conventions for the
1286 ordering of bytes within a word. Some computers put the most
1287 significant byte within a word first (this is called ``big-endian''
1288 order), and others put it last (``little-endian'' order).
1290 @cindex network byte order
1291 So that machines with different byte order conventions can
1292 communicate, the Internet protocols specify a canonical byte order
1293 convention for data transmitted over the network. This is known
1294 as the @dfn{network byte order}.
1296 When establishing an Internet socket connection, you must make sure that
1297 the data in the @code{sin_port} and @code{sin_addr} members of the
1298 @code{sockaddr_in} structure are represented in the network byte order.
1299 If you are encoding integer data in the messages sent through the
1300 socket, you should convert this to network byte order too. If you don't
1301 do this, your program may fail when running on or talking to other kinds
1304 If you use @code{getservbyname} and @code{gethostbyname} or
1305 @code{inet_addr} to get the port number and host address, the values are
1306 already in the network byte order, and you can copy them directly into
1307 the @code{sockaddr_in} structure.
1309 Otherwise, you have to convert the values explicitly. Use
1310 @code{htons} and @code{ntohs} to convert values for the @code{sin_port}
1311 member. Use @code{htonl} and @code{ntohl} to convert values for the
1312 @code{sin_addr} member. (Remember, @code{struct in_addr} is equivalent
1313 to @code{unsigned long int}.) These functions are declared in
1314 @file{netinet/in.h}.
1315 @pindex netinet/in.h
1317 @comment netinet/in.h
1319 @deftypefun {unsigned short int} htons (unsigned short int @var{hostshort})
1320 This function converts the @code{short} integer @var{hostshort} from
1321 host byte order to network byte order.
1324 @comment netinet/in.h
1326 @deftypefun {unsigned short int} ntohs (unsigned short int @var{netshort})
1327 This function converts the @code{short} integer @var{netshort} from
1328 network byte order to host byte order.
1331 @comment netinet/in.h
1333 @deftypefun {unsigned long int} htonl (unsigned long int @var{hostlong})
1334 This function converts the @code{long} integer @var{hostlong} from
1335 host byte order to network byte order.
1338 @comment netinet/in.h
1340 @deftypefun {unsigned long int} ntohl (unsigned long int @var{netlong})
1341 This function converts the @code{long} integer @var{netlong} from
1342 network byte order to host byte order.
1345 @node Protocols Database
1346 @subsection Protocols Database
1347 @cindex protocols database
1349 The communications protocol used with a socket controls low-level
1350 details of how data is exchanged. For example, the protocol implements
1351 things like checksums to detect errors in transmissions, and routing
1352 instructions for messages. Normal user programs have little reason to
1353 mess with these details directly.
1355 @cindex TCP (Internet protocol)
1356 The default communications protocol for the Internet namespace depends on
1357 the communication style. For stream communication, the default is TCP
1358 (``transmission control protocol''). For datagram communication, the
1359 default is UDP (``user datagram protocol''). For reliable datagram
1360 communication, the default is RDP (``reliable datagram protocol'').
1361 You should nearly always use the default.
1363 @pindex /etc/protocols
1364 Internet protocols are generally specified by a name instead of a
1365 number. The network protocols that a host knows about are stored in a
1366 database. This is usually either derived from the file
1367 @file{/etc/protocols}, or it may be an equivalent provided by a name
1368 server. You look up the protocol number associated with a named
1369 protocol in the database using the @code{getprotobyname} function.
1371 Here are detailed descriptions of the utilities for accessing the
1372 protocols database. These are declared in @file{netdb.h}.
1377 @deftp {Data Type} {struct protoent}
1378 This data type is used to represent entries in the network protocols
1379 database. It has the following members:
1383 This is the official name of the protocol.
1385 @item char **p_aliases
1386 These are alternate names for the protocol, specified as an array of
1387 strings. The last element of the array is a null pointer.
1390 This is the protocol number (in host byte order); use this member as the
1391 @var{protocol} argument to @code{socket}.
1395 You can use @code{getprotobyname} and @code{getprotobynumber} to search
1396 the protocols database for a specific protocol. The information is
1397 returned in a statically-allocated structure; you must copy the
1398 information if you need to save it across calls.
1402 @deftypefun {struct protoent *} getprotobyname (const char *@var{name})
1403 The @code{getprotobyname} function returns information about the
1404 network protocol named @var{name}. If there is no such protocol, it
1405 returns a null pointer.
1410 @deftypefun {struct protoent *} getprotobynumber (int @var{protocol})
1411 The @code{getprotobynumber} function returns information about the
1412 network protocol with number @var{protocol}. If there is no such
1413 protocol, it returns a null pointer.
1416 You can also scan the whole protocols database one protocol at a time by
1417 using @code{setprotoent}, @code{getprotoent}, and @code{endprotoent}.
1418 Be careful in using these functions, because they are not reentrant.
1422 @deftypefun void setprotoent (int @var{stayopen})
1423 This function opens the protocols database to begin scanning it.
1425 If the @var{stayopen} argument is nonzero, this sets a flag so that
1426 subsequent calls to @code{getprotobyname} or @code{getprotobynumber} will
1427 not close the database (as they usually would). This makes for more
1428 efficiency if you call those functions several times, by avoiding
1429 reopening the database for each call.
1434 @deftypefun {struct protoent *} getprotoent (void)
1435 This function returns the next entry in the protocols database. It
1436 returns a null pointer if there are no more entries.
1441 @deftypefun void endprotoent (void)
1442 This function closes the protocols database.
1446 @subsection Internet Socket Example
1448 Here is an example showing how to create and name a socket in the
1449 Internet namespace. The newly created socket exists on the machine that
1450 the program is running on. Rather than finding and using the machine's
1451 Internet address, this example specifies @code{INADDR_ANY} as the host
1452 address; the system replaces that with the machine's actual address.
1455 @include mkisock.c.texi
1458 Here is another example, showing how you can fill in a @code{sockaddr_in}
1459 structure, given a host name string and a port number:
1462 @include isockad.c.texi
1465 @node Misc Namespaces
1466 @section Other Namespaces
1473 Certain other namespaces and associated protocol families are supported
1474 but not documented yet because they are not often used. @code{PF_NS}
1475 refers to the Xerox Network Software protocols. @code{PF_ISO} stands
1476 for Open Systems Interconnect. @code{PF_CCITT} refers to protocols from
1477 CCITT. @file{socket.h} defines these symbols and others naming protocols
1478 not actually implemented.
1480 @code{PF_IMPLINK} is used for communicating between hosts and Internet
1481 Message Processors. For information on this, and on @code{PF_ROUTE}, an
1482 occasionally-used local area routing protocol, see the GNU Hurd Manual
1483 (to appear in the future).
1485 @node Open/Close Sockets
1486 @section Opening and Closing Sockets
1488 This section describes the actual library functions for opening and
1489 closing sockets. The same functions work for all namespaces and
1493 * Creating a Socket:: How to open a socket.
1494 * Closing a Socket:: How to close a socket.
1495 * Socket Pairs:: These are created like pipes.
1498 @node Creating a Socket
1499 @subsection Creating a Socket
1500 @cindex creating a socket
1501 @cindex socket, creating
1502 @cindex opening a socket
1504 The primitive for creating a socket is the @code{socket} function,
1505 declared in @file{sys/socket.h}.
1506 @pindex sys/socket.h
1508 @comment sys/socket.h
1510 @deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol})
1511 This function creates a socket and specifies communication style
1512 @var{style}, which should be one of the socket styles listed in
1513 @ref{Communication Styles}. The @var{namespace} argument specifies
1514 the namespace; it must be @code{PF_FILE} (@pxref{File Namespace}) or
1515 @code{PF_INET} (@pxref{Internet Namespace}). @var{protocol}
1516 designates the specific protocol (@pxref{Socket Concepts}); zero is
1517 usually right for @var{protocol}.
1519 The return value from @code{socket} is the file descriptor for the new
1520 socket, or @code{-1} in case of error. The following @code{errno} error
1521 conditions are defined for this function:
1524 @item EPROTONOSUPPORT
1525 The @var{protocol} or @var{style} is not supported by the
1526 @var{namespace} specified.
1529 The process already has too many file descriptors open.
1532 The system already has too many file descriptors open.
1535 The process does not have privilege to create a socket of the specified
1536 @var{style} or @var{protocol}.
1539 The system ran out of internal buffer space.
1542 The file descriptor returned by the @code{socket} function supports both
1543 read and write operations. But, like pipes, sockets do not support file
1544 positioning operations.
1547 For examples of how to call the @code{socket} function,
1548 see @ref{File Namespace}, or @ref{Inet Example}.
1551 @node Closing a Socket
1552 @subsection Closing a Socket
1553 @cindex socket, closing
1554 @cindex closing a socket
1555 @cindex shutting down a socket
1556 @cindex socket shutdown
1558 When you are finished using a socket, you can simply close its
1559 file descriptor with @code{close}; see @ref{Opening and Closing Files}.
1560 If there is still data waiting to be transmitted over the connection,
1561 normally @code{close} tries to complete this transmission. You
1562 can control this behavior using the @code{SO_LINGER} socket option to
1563 specify a timeout period; see @ref{Socket Options}.
1565 @pindex sys/socket.h
1566 You can also shut down only reception or only transmission on a
1567 connection by calling @code{shutdown}, which is declared in
1568 @file{sys/socket.h}.
1570 @comment sys/socket.h
1572 @deftypefun int shutdown (int @var{socket}, int @var{how})
1573 The @code{shutdown} function shuts down the connection of socket
1574 @var{socket}. The argument @var{how} specifies what action to
1579 Stop receiving data for this socket. If further data arrives,
1583 Stop trying to transmit data from this socket. Discard any data
1584 waiting to be sent. Stop looking for acknowledgement of data already
1585 sent; don't retransmit it if it is lost.
1588 Stop both reception and transmission.
1591 The return value is @code{0} on success and @code{-1} on failure. The
1592 following @code{errno} error conditions are defined for this function:
1596 @var{socket} is not a valid file descriptor.
1599 @var{socket} is not a socket.
1602 @var{socket} is not connected.
1607 @subsection Socket Pairs
1608 @cindex creating a socket pair
1610 @cindex opening a socket pair
1612 @pindex sys/socket.h
1613 A @dfn{socket pair} consists of a pair of connected (but unnamed)
1614 sockets. It is very similar to a pipe and is used in much the same
1615 way. Socket pairs are created with the @code{socketpair} function,
1616 declared in @file{sys/socket.h}. A socket pair is much like a pipe; the
1617 main difference is that the socket pair is bidirectional, whereas the
1618 pipe has one input-only end and one output-only end (@pxref{Pipes and
1621 @comment sys/socket.h
1623 @deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]})
1624 This function creates a socket pair, returning the file descriptors in
1625 @code{@var{filedes}[0]} and @code{@var{filedes}[1]}. The socket pair
1626 is a full-duplex communications channel, so that both reading and writing
1627 may be performed at either end.
1629 The @var{namespace}, @var{style}, and @var{protocol} arguments are
1630 interpreted as for the @code{socket} function. @var{style} should be
1631 one of the communication styles listed in @ref{Communication Styles}.
1632 The @var{namespace} argument specifies the namespace, which must be
1633 @code{AF_FILE} (@pxref{File Namespace}); @var{protocol} specifies the
1634 communications protocol, but zero is the only meaningful value.
1636 If @var{style} specifies a connectionless communication style, then
1637 the two sockets you get are not @emph{connected}, strictly speaking,
1638 but each of them knows the other as the default destination address,
1639 so they can send packets to each other.
1641 The @code{socketpair} function returns @code{0} on success and @code{-1}
1642 on failure. The following @code{errno} error conditions are defined
1647 The process has too many file descriptors open.
1650 The specified namespace is not supported.
1652 @item EPROTONOSUPPORT
1653 The specified protocol is not supported.
1656 The specified protocol does not support the creation of socket pairs.
1661 @section Using Sockets with Connections
1666 The most common communication styles involve making a connection to a
1667 particular other socket, and then exchanging data with that socket
1668 over and over. Making a connection is asymmetric; one side (the
1669 @dfn{client}) acts to request a connection, while the other side (the
1670 @dfn{server}) makes a socket and waits for the connection request.
1675 @ref{Connecting}, describes what the client program must do to
1676 initiate a connection with a server.
1679 @ref{Listening}, and @ref{Accepting Connections}, describe what the
1680 server program must do to wait for and act upon connection requests
1684 @ref{Transferring Data}, describes how data is transferred through the
1690 * Connecting:: What the client program must do.
1691 * Listening:: How a server program waits for requests.
1692 * Accepting Connections:: What the server does when it gets a request.
1693 * Who is Connected:: Getting the address of the
1694 other side of a connection.
1695 * Transferring Data:: How to send and receive data.
1696 * Byte Stream Example:: An example program: a client for communicating
1697 over a byte stream socket in the Internet namespace.
1698 * Server Example:: A corresponding server program.
1699 * Out-of-Band Data:: This is an advanced feature.
1703 @subsection Making a Connection
1704 @cindex connecting a socket
1705 @cindex socket, connecting
1706 @cindex socket, initiating a connection
1707 @cindex socket, client actions
1709 In making a connection, the client makes a connection while the server
1710 waits for and accepts the connection. Here we discuss what the client
1711 program must do, using the @code{connect} function, which is declared in
1712 @file{sys/socket.h}.
1714 @comment sys/socket.h
1716 @deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
1717 The @code{connect} function initiates a connection from the socket
1718 with file descriptor @var{socket} to the socket whose address is
1719 specified by the @var{addr} and @var{length} arguments. (This socket
1720 is typically on another machine, and it must be already set up as a
1721 server.) @xref{Socket Addresses}, for information about how these
1722 arguments are interpreted.
1724 Normally, @code{connect} waits until the server responds to the request
1725 before it returns. You can set nonblocking mode on the socket
1726 @var{socket} to make @code{connect} return immediately without waiting
1727 for the response. @xref{File Status Flags}, for information about
1729 @c !!! how do you tell when it has finished connecting? I suspect the
1730 @c way you do it is select for writing.
1732 The normal return value from @code{connect} is @code{0}. If an error
1733 occurs, @code{connect} returns @code{-1}. The following @code{errno}
1734 error conditions are defined for this function:
1738 The socket @var{socket} is not a valid file descriptor.
1741 File descriptor @var{socket} is not a socket.
1744 The specified address is not available on the remote machine.
1747 The namespace of the @var{addr} is not supported by this socket.
1750 The socket @var{socket} is already connected.
1753 The attempt to establish the connection timed out.
1756 The server has actively refused to establish the connection.
1759 The network of the given @var{addr} isn't reachable from this host.
1762 The socket address of the given @var{addr} is already in use.
1765 The socket @var{socket} is non-blocking and the connection could not be
1766 established immediately. You can determine when the connection is
1767 completely established with @code{select}; @pxref{Waiting for I/O}.
1768 Another @code{connect} call on the same socket, before the connection is
1769 completely established, will fail with @code{EALREADY}.
1772 The socket @var{socket} is non-blocking and already has a pending
1773 connection in progress (see @code{EINPROGRESS} above).
1776 This function is defined as a cancelation point in multi-threaded
1777 programs. So one has to be prepared for this and make sure that
1778 possibly allocated resources (like memory, files descriptors,
1779 semaphores or whatever) are freed even if the thread is cancel.
1780 @c @xref{pthread_cleanup_push}, for a method how to do this.
1784 @subsection Listening for Connections
1785 @cindex listening (sockets)
1786 @cindex sockets, server actions
1787 @cindex sockets, listening
1789 Now let us consider what the server process must do to accept
1790 connections on a socket. First it must use the @code{listen} function
1791 to enable connection requests on the socket, and then accept each
1792 incoming connection with a call to @code{accept} (@pxref{Accepting
1793 Connections}). Once connection requests are enabled on a server socket,
1794 the @code{select} function reports when the socket has a connection
1795 ready to be accepted (@pxref{Waiting for I/O}).
1797 The @code{listen} function is not allowed for sockets using
1798 connectionless communication styles.
1800 You can write a network server that does not even start running until a
1801 connection to it is requested. @xref{Inetd Servers}.
1803 In the Internet namespace, there are no special protection mechanisms
1804 for controlling access to connect to a port; any process on any machine
1805 can make a connection to your server. If you want to restrict access to
1806 your server, make it examine the addresses associated with connection
1807 requests or implement some other handshaking or identification
1810 In the File namespace, the ordinary file protection bits control who has
1811 access to connect to the socket.
1813 @comment sys/socket.h
1815 @deftypefun int listen (int @var{socket}, unsigned int @var{n})
1816 The @code{listen} function enables the socket @var{socket} to accept
1817 connections, thus making it a server socket.
1819 The argument @var{n} specifies the length of the queue for pending
1820 connections. When the queue fills, new clients attempting to connect
1821 fail with @code{ECONNREFUSED} until the server calls @code{accept} to
1822 accept a connection from the queue.
1824 The @code{listen} function returns @code{0} on success and @code{-1}
1825 on failure. The following @code{errno} error conditions are defined
1830 The argument @var{socket} is not a valid file descriptor.
1833 The argument @var{socket} is not a socket.
1836 The socket @var{socket} does not support this operation.
1840 @node Accepting Connections
1841 @subsection Accepting Connections
1842 @cindex sockets, accepting connections
1843 @cindex accepting connections
1845 When a server receives a connection request, it can complete the
1846 connection by accepting the request. Use the function @code{accept}
1849 A socket that has been established as a server can accept connection
1850 requests from multiple clients. The server's original socket
1851 @emph{does not become part} of the connection; instead, @code{accept}
1852 makes a new socket which participates in the connection.
1853 @code{accept} returns the descriptor for this socket. The server's
1854 original socket remains available for listening for further connection
1857 The number of pending connection requests on a server socket is finite.
1858 If connection requests arrive from clients faster than the server can
1859 act upon them, the queue can fill up and additional requests are refused
1860 with a @code{ECONNREFUSED} error. You can specify the maximum length of
1861 this queue as an argument to the @code{listen} function, although the
1862 system may also impose its own internal limit on the length of this
1865 @comment sys/socket.h
1867 @deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
1868 This function is used to accept a connection request on the server
1869 socket @var{socket}.
1871 The @code{accept} function waits if there are no connections pending,
1872 unless the socket @var{socket} has nonblocking mode set. (You can use
1873 @code{select} to wait for a pending connection, with a nonblocking
1874 socket.) @xref{File Status Flags}, for information about nonblocking
1877 The @var{addr} and @var{length-ptr} arguments are used to return
1878 information about the name of the client socket that initiated the
1879 connection. @xref{Socket Addresses}, for information about the format
1882 Accepting a connection does not make @var{socket} part of the
1883 connection. Instead, it creates a new socket which becomes
1884 connected. The normal return value of @code{accept} is the file
1885 descriptor for the new socket.
1887 After @code{accept}, the original socket @var{socket} remains open and
1888 unconnected, and continues listening until you close it. You can
1889 accept further connections with @var{socket} by calling @code{accept}
1892 If an error occurs, @code{accept} returns @code{-1}. The following
1893 @code{errno} error conditions are defined for this function:
1897 The @var{socket} argument is not a valid file descriptor.
1900 The descriptor @var{socket} argument is not a socket.
1903 The descriptor @var{socket} does not support this operation.
1906 @var{socket} has nonblocking mode set, and there are no pending
1907 connections immediately available.
1910 This function is defined as a cancelation point in multi-threaded
1911 programs. So one has to be prepared for this and make sure that
1912 possibly allocated resources (like memory, files descriptors,
1913 semaphores or whatever) are freed even if the thread is cancel.
1914 @c @xref{pthread_cleanup_push}, for a method how to do this.
1917 The @code{accept} function is not allowed for sockets using
1918 connectionless communication styles.
1920 @node Who is Connected
1921 @subsection Who is Connected to Me?
1923 @comment sys/socket.h
1925 @deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, size_t *@var{length-ptr})
1926 The @code{getpeername} function returns the address of the socket that
1927 @var{socket} is connected to; it stores the address in the memory space
1928 specified by @var{addr} and @var{length-ptr}. It stores the length of
1929 the address in @code{*@var{length-ptr}}.
1931 @xref{Socket Addresses}, for information about the format of the
1932 address. In some operating systems, @code{getpeername} works only for
1933 sockets in the Internet domain.
1935 The return value is @code{0} on success and @code{-1} on error. The
1936 following @code{errno} error conditions are defined for this function:
1940 The argument @var{socket} is not a valid file descriptor.
1943 The descriptor @var{socket} is not a socket.
1946 The socket @var{socket} is not connected.
1949 There are not enough internal buffers available.
1954 @node Transferring Data
1955 @subsection Transferring Data
1956 @cindex reading from a socket
1957 @cindex writing to a socket
1959 Once a socket has been connected to a peer, you can use the ordinary
1960 @code{read} and @code{write} operations (@pxref{I/O Primitives}) to
1961 transfer data. A socket is a two-way communications channel, so read
1962 and write operations can be performed at either end.
1964 There are also some I/O modes that are specific to socket operations.
1965 In order to specify these modes, you must use the @code{recv} and
1966 @code{send} functions instead of the more generic @code{read} and
1967 @code{write} functions. The @code{recv} and @code{send} functions take
1968 an additional argument which you can use to specify various flags to
1969 control the special I/O modes. For example, you can specify the
1970 @code{MSG_OOB} flag to read or write out-of-band data, the
1971 @code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag
1972 to control inclusion of routing information on output.
1975 * Sending Data:: Sending data with @code{send}.
1976 * Receiving Data:: Reading data with @code{recv}.
1977 * Socket Data Options:: Using @code{send} and @code{recv}.
1981 @subsubsection Sending Data
1983 @pindex sys/socket.h
1984 The @code{send} function is declared in the header file
1985 @file{sys/socket.h}. If your @var{flags} argument is zero, you can just
1986 as well use @code{write} instead of @code{send}; see @ref{I/O
1987 Primitives}. If the socket was connected but the connection has broken,
1988 you get a @code{SIGPIPE} signal for any use of @code{send} or
1989 @code{write} (@pxref{Miscellaneous Signals}).
1991 @comment sys/socket.h
1993 @deftypefun int send (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags})
1994 The @code{send} function is like @code{write}, but with the additional
1995 flags @var{flags}. The possible values of @var{flags} are described
1996 in @ref{Socket Data Options}.
1998 This function returns the number of bytes transmitted, or @code{-1} on
1999 failure. If the socket is nonblocking, then @code{send} (like
2000 @code{write}) can return after sending just part of the data.
2001 @xref{File Status Flags}, for information about nonblocking mode.
2003 Note, however, that a successful return value merely indicates that
2004 the message has been sent without error, not necessarily that it has
2005 been received without error.
2007 The following @code{errno} error conditions are defined for this function:
2011 The @var{socket} argument is not a valid file descriptor.
2014 The operation was interrupted by a signal before any data was sent.
2015 @xref{Interrupted Primitives}.
2018 The descriptor @var{socket} is not a socket.
2021 The socket type requires that the message be sent atomically, but the
2022 message is too large for this to be possible.
2025 Nonblocking mode has been set on the socket, and the write operation
2026 would block. (Normally @code{send} blocks until the operation can be
2030 There is not enough internal buffer space available.
2033 You never connected this socket.
2036 This socket was connected but the connection is now broken. In this
2037 case, @code{send} generates a @code{SIGPIPE} signal first; if that
2038 signal is ignored or blocked, or if its handler returns, then
2039 @code{send} fails with @code{EPIPE}.
2042 This function is defined as a cancelation point in multi-threaded
2043 programs. So one has to be prepared for this and make sure that
2044 possibly allocated resources (like memory, files descriptors,
2045 semaphores or whatever) are freed even if the thread is cancel.
2046 @c @xref{pthread_cleanup_push}, for a method how to do this.
2049 @node Receiving Data
2050 @subsubsection Receiving Data
2052 @pindex sys/socket.h
2053 The @code{recv} function is declared in the header file
2054 @file{sys/socket.h}. If your @var{flags} argument is zero, you can
2055 just as well use @code{read} instead of @code{recv}; see @ref{I/O
2058 @comment sys/socket.h
2060 @deftypefun int recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags})
2061 The @code{recv} function is like @code{read}, but with the additional
2062 flags @var{flags}. The possible values of @var{flags} are described
2063 In @ref{Socket Data Options}.
2065 If nonblocking mode is set for @var{socket}, and no data is available to
2066 be read, @code{recv} fails immediately rather than waiting. @xref{File
2067 Status Flags}, for information about nonblocking mode.
2069 This function returns the number of bytes received, or @code{-1} on failure.
2070 The following @code{errno} error conditions are defined for this function:
2074 The @var{socket} argument is not a valid file descriptor.
2077 The descriptor @var{socket} is not a socket.
2080 Nonblocking mode has been set on the socket, and the read operation
2081 would block. (Normally, @code{recv} blocks until there is input
2082 available to be read.)
2085 The operation was interrupted by a signal before any data was read.
2086 @xref{Interrupted Primitives}.
2089 You never connected this socket.
2092 This function is defined as a cancelation point in multi-threaded
2093 programs. So one has to be prepared for this and make sure that
2094 possibly allocated resources (like memory, files descriptors,
2095 semaphores or whatever) are freed even if the thread is cancel.
2096 @c @xref{pthread_cleanup_push}, for a method how to do this.
2099 @node Socket Data Options
2100 @subsubsection Socket Data Options
2102 @pindex sys/socket.h
2103 The @var{flags} argument to @code{send} and @code{recv} is a bit
2104 mask. You can bitwise-OR the values of the following macros together
2105 to obtain a value for this argument. All are defined in the header
2106 file @file{sys/socket.h}.
2108 @comment sys/socket.h
2110 @deftypevr Macro int MSG_OOB
2111 Send or receive out-of-band data. @xref{Out-of-Band Data}.
2114 @comment sys/socket.h
2116 @deftypevr Macro int MSG_PEEK
2117 Look at the data but don't remove it from the input queue. This is
2118 only meaningful with input functions such as @code{recv}, not with
2122 @comment sys/socket.h
2124 @deftypevr Macro int MSG_DONTROUTE
2125 Don't include routing information in the message. This is only
2126 meaningful with output operations, and is usually only of interest for
2127 diagnostic or routing programs. We don't try to explain it here.
2130 @node Byte Stream Example
2131 @subsection Byte Stream Socket Example
2133 Here is an example client program that makes a connection for a byte
2134 stream socket in the Internet namespace. It doesn't do anything
2135 particularly interesting once it has connected to the server; it just
2136 sends a text string to the server and exits.
2139 @include inetcli.c.texi
2142 @node Server Example
2143 @subsection Byte Stream Connection Server Example
2145 The server end is much more complicated. Since we want to allow
2146 multiple clients to be connected to the server at the same time, it
2147 would be incorrect to wait for input from a single client by simply
2148 calling @code{read} or @code{recv}. Instead, the right thing to do is
2149 to use @code{select} (@pxref{Waiting for I/O}) to wait for input on
2150 all of the open sockets. This also allows the server to deal with
2151 additional connection requests.
2153 This particular server doesn't do anything interesting once it has
2154 gotten a message from a client. It does close the socket for that
2155 client when it detects an end-of-file condition (resulting from the
2156 client shutting down its end of the connection).
2158 This program uses @code{make_socket} and @code{init_sockaddr} to set
2159 up the socket address; see @ref{Inet Example}.
2162 @include inetsrv.c.texi
2165 @node Out-of-Band Data
2166 @subsection Out-of-Band Data
2168 @cindex out-of-band data
2169 @cindex high-priority data
2170 Streams with connections permit @dfn{out-of-band} data that is
2171 delivered with higher priority than ordinary data. Typically the
2172 reason for sending out-of-band data is to send notice of an
2173 exceptional condition. The way to send out-of-band data is using
2174 @code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending
2177 Out-of-band data is received with higher priority because the
2178 receiving process need not read it in sequence; to read the next
2179 available out-of-band data, use @code{recv} with the @code{MSG_OOB}
2180 flag (@pxref{Receiving Data}). Ordinary read operations do not read
2181 out-of-band data; they read only the ordinary data.
2183 @cindex urgent socket condition
2184 When a socket finds that out-of-band data is on its way, it sends a
2185 @code{SIGURG} signal to the owner process or process group of the
2186 socket. You can specify the owner using the @code{F_SETOWN} command
2187 to the @code{fcntl} function; see @ref{Interrupt Input}. You must
2188 also establish a handler for this signal, as described in @ref{Signal
2189 Handling}, in order to take appropriate action such as reading the
2192 Alternatively, you can test for pending out-of-band data, or wait
2193 until there is out-of-band data, using the @code{select} function; it
2194 can wait for an exceptional condition on the socket. @xref{Waiting
2195 for I/O}, for more information about @code{select}.
2197 Notification of out-of-band data (whether with @code{SIGURG} or with
2198 @code{select}) indicates that out-of-band data is on the way; the data
2199 may not actually arrive until later. If you try to read the
2200 out-of-band data before it arrives, @code{recv} fails with an
2201 @code{EWOULDBLOCK} error.
2203 Sending out-of-band data automatically places a ``mark'' in the stream
2204 of ordinary data, showing where in the sequence the out-of-band data
2205 ``would have been''. This is useful when the meaning of out-of-band
2206 data is ``cancel everything sent so far''. Here is how you can test,
2207 in the receiving process, whether any ordinary data was sent before
2211 success = ioctl (socket, SIOCATMARK, &result);
2214 Here's a function to discard any ordinary data preceding the
2219 discard_until_mark (int socket)
2223 /* @r{This is not an arbitrary limit; any size will do.} */
2225 int result, success;
2227 /* @r{If we have reached the mark, return.} */
2228 success = ioctl (socket, SIOCATMARK, &result);
2234 /* @r{Otherwise, read a bunch of ordinary data and discard it.}
2235 @r{This is guaranteed not to read past the mark}
2236 @r{if it starts before the mark.} */
2237 success = read (socket, buffer, sizeof buffer);
2244 If you don't want to discard the ordinary data preceding the mark, you
2245 may need to read some of it anyway, to make room in internal system
2246 buffers for the out-of-band data. If you try to read out-of-band data
2247 and get an @code{EWOULDBLOCK} error, try reading some ordinary data
2248 (saving it so that you can use it when you want it) and see if that
2249 makes room. Here is an example:
2256 struct buffer *next;
2259 /* @r{Read the out-of-band data from SOCKET and return it}
2260 @r{as a `struct buffer', which records the address of the data}
2263 @r{It may be necessary to read some ordinary data}
2264 @r{in order to make room for the out-of-band data.}
2265 @r{If so, the ordinary data is saved as a chain of buffers}
2266 @r{found in the `next' field of the value.} */
2269 read_oob (int socket)
2271 struct buffer *tail = 0;
2272 struct buffer *list = 0;
2276 /* @r{This is an arbitrary limit.}
2277 @r{Does anyone know how to do this without a limit?} */
2278 char *buffer = (char *) xmalloc (1024);
2279 struct buffer *link;
2283 /* @r{Try again to read the out-of-band data.} */
2284 success = recv (socket, buffer, sizeof buffer, MSG_OOB);
2287 /* @r{We got it, so return it.} */
2289 = (struct buffer *) xmalloc (sizeof (struct buffer));
2290 link->buffer = buffer;
2291 link->size = success;
2296 /* @r{If we fail, see if we are at the mark.} */
2297 success = ioctl (socket, SIOCATMARK, &result);
2302 /* @r{At the mark; skipping past more ordinary data cannot help.}
2303 @r{So just wait a while.} */
2308 /* @r{Otherwise, read a bunch of ordinary data and save it.}
2309 @r{This is guaranteed not to read past the mark}
2310 @r{if it starts before the mark.} */
2311 success = read (socket, buffer, sizeof buffer);
2315 /* @r{Save this data in the buffer list.} */
2318 = (struct buffer *) xmalloc (sizeof (struct buffer));
2319 link->buffer = buffer;
2320 link->size = success;
2322 /* @r{Add the new link to the end of the list.} */
2334 @section Datagram Socket Operations
2336 @cindex datagram socket
2337 This section describes how to use communication styles that don't use
2338 connections (styles @code{SOCK_DGRAM} and @code{SOCK_RDM}). Using
2339 these styles, you group data into packets and each packet is an
2340 independent communication. You specify the destination for each
2341 packet individually.
2343 Datagram packets are like letters: you send each one independently,
2344 with its own destination address, and they may arrive in the wrong
2345 order or not at all.
2347 The @code{listen} and @code{accept} functions are not allowed for
2348 sockets using connectionless communication styles.
2351 * Sending Datagrams:: Sending packets on a datagram socket.
2352 * Receiving Datagrams:: Receiving packets on a datagram socket.
2353 * Datagram Example:: An example program: packets sent over a
2354 datagram socket in the file namespace.
2355 * Example Receiver:: Another program, that receives those packets.
2358 @node Sending Datagrams
2359 @subsection Sending Datagrams
2360 @cindex sending a datagram
2361 @cindex transmitting datagrams
2362 @cindex datagrams, transmitting
2364 @pindex sys/socket.h
2365 The normal way of sending data on a datagram socket is by using the
2366 @code{sendto} function, declared in @file{sys/socket.h}.
2368 You can call @code{connect} on a datagram socket, but this only
2369 specifies a default destination for further data transmission on the
2370 socket. When a socket has a default destination, then you can use
2371 @code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O
2372 Primitives}) to send a packet there. You can cancel the default
2373 destination by calling @code{connect} using an address format of
2374 @code{AF_UNSPEC} in the @var{addr} argument. @xref{Connecting}, for
2375 more information about the @code{connect} function.
2377 @comment sys/socket.h
2379 @deftypefun int sendto (int @var{socket}, void *@var{buffer}. size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length})
2380 The @code{sendto} function transmits the data in the @var{buffer}
2381 through the socket @var{socket} to the destination address specified
2382 by the @var{addr} and @var{length} arguments. The @var{size} argument
2383 specifies the number of bytes to be transmitted.
2385 The @var{flags} are interpreted the same way as for @code{send}; see
2386 @ref{Socket Data Options}.
2388 The return value and error conditions are also the same as for
2389 @code{send}, but you cannot rely on the system to detect errors and
2390 report them; the most common error is that the packet is lost or there
2391 is no one at the specified address to receive it, and the operating
2392 system on your machine usually does not know this.
2394 It is also possible for one call to @code{sendto} to report an error
2395 due to a problem related to a previous call.
2397 This function is defined as a cancelation point in multi-threaded
2398 programs. So one has to be prepared for this and make sure that
2399 possibly allocated resources (like memory, files descriptors,
2400 semaphores or whatever) are freed even if the thread is cancel.
2401 @c @xref{pthread_cleanup_push}, for a method how to do this.
2404 @node Receiving Datagrams
2405 @subsection Receiving Datagrams
2406 @cindex receiving datagrams
2408 The @code{recvfrom} function reads a packet from a datagram socket and
2409 also tells you where it was sent from. This function is declared in
2410 @file{sys/socket.h}.
2412 @comment sys/socket.h
2414 @deftypefun int recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
2415 The @code{recvfrom} function reads one packet from the socket
2416 @var{socket} into the buffer @var{buffer}. The @var{size} argument
2417 specifies the maximum number of bytes to be read.
2419 If the packet is longer than @var{size} bytes, then you get the first
2420 @var{size} bytes of the packet, and the rest of the packet is lost.
2421 There's no way to read the rest of the packet. Thus, when you use a
2422 packet protocol, you must always know how long a packet to expect.
2424 The @var{addr} and @var{length-ptr} arguments are used to return the
2425 address where the packet came from. @xref{Socket Addresses}. For a
2426 socket in the file domain, the address information won't be meaningful,
2427 since you can't read the address of such a socket (@pxref{File
2428 Namespace}). You can specify a null pointer as the @var{addr} argument
2429 if you are not interested in this information.
2431 The @var{flags} are interpreted the same way as for @code{recv}
2432 (@pxref{Socket Data Options}). The return value and error conditions
2433 are also the same as for @code{recv}.
2435 This function is defined as a cancelation point in multi-threaded
2436 programs. So one has to be prepared for this and make sure that
2437 possibly allocated resources (like memory, files descriptors,
2438 semaphores or whatever) are freed even if the thread is cancel.
2439 @c @xref{pthread_cleanup_push}, for a method how to do this.
2442 You can use plain @code{recv} (@pxref{Receiving Data}) instead of
2443 @code{recvfrom} if you know don't need to find out who sent the packet
2444 (either because you know where it should come from or because you
2445 treat all possible senders alike). Even @code{read} can be used if
2446 you don't want to specify @var{flags} (@pxref{I/O Primitives}).
2449 @c sendmsg and recvmsg are like readv and writev in that they
2450 @c use a series of buffers. It's not clear this is worth
2451 @c supporting or that we support them.
2452 @c !!! they can do more; it is hairy
2454 @comment sys/socket.h
2456 @deftp {Data Type} {struct msghdr}
2459 @comment sys/socket.h
2461 @deftypefun int sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags})
2463 This function is defined as a cancelation point in multi-threaded
2464 programs. So one has to be prepared for this and make sure that
2465 possibly allocated resources (like memory, files descriptors,
2466 semaphores or whatever) are freed even if the thread is cancel.
2467 @c @xref{pthread_cleanup_push}, for a method how to do this.
2470 @comment sys/socket.h
2472 @deftypefun int recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
2474 This function is defined as a cancelation point in multi-threaded
2475 programs. So one has to be prepared for this and make sure that
2476 possibly allocated resources (like memory, files descriptors,
2477 semaphores or whatever) are freed even if the thread is cancel.
2478 @c @xref{pthread_cleanup_push}, for a method how to do this.
2482 @node Datagram Example
2483 @subsection Datagram Socket Example
2485 Here is a set of example programs that send messages over a datagram
2486 stream in the file namespace. Both the client and server programs use the
2487 @code{make_named_socket} function that was presented in @ref{File
2488 Namespace}, to create and name their sockets.
2490 First, here is the server program. It sits in a loop waiting for
2491 messages to arrive, bouncing each message back to the sender.
2492 Obviously, this isn't a particularly useful program, but it does show
2493 the general ideas involved.
2496 @include filesrv.c.texi
2499 @node Example Receiver
2500 @subsection Example of Reading Datagrams
2502 Here is the client program corresponding to the server above.
2504 It sends a datagram to the server and then waits for a reply. Notice
2505 that the socket for the client (as well as for the server) in this
2506 example has to be given a name. This is so that the server can direct
2507 a message back to the client. Since the socket has no associated
2508 connection state, the only way the server can do this is by
2509 referencing the name of the client.
2512 @include filecli.c.texi
2515 Keep in mind that datagram socket communications are unreliable. In
2516 this example, the client program waits indefinitely if the message
2517 never reaches the server or if the server's response never comes
2518 back. It's up to the user running the program to kill it and restart
2519 it, if desired. A more automatic solution could be to use
2520 @code{select} (@pxref{Waiting for I/O}) to establish a timeout period
2521 for the reply, and in case of timeout either resend the message or
2522 shut down the socket and exit.
2525 @section The @code{inetd} Daemon
2527 We've explained above how to write a server program that does its own
2528 listening. Such a server must already be running in order for anyone
2531 Another way to provide service for an Internet port is to let the daemon
2532 program @code{inetd} do the listening. @code{inetd} is a program that
2533 runs all the time and waits (using @code{select}) for messages on a
2534 specified set of ports. When it receives a message, it accepts the
2535 connection (if the socket style calls for connections) and then forks a
2536 child process to run the corresponding server program. You specify the
2537 ports and their programs in the file @file{/etc/inetd.conf}.
2541 * Configuring Inetd::
2545 @subsection @code{inetd} Servers
2547 Writing a server program to be run by @code{inetd} is very simple. Each time
2548 someone requests a connection to the appropriate port, a new server
2549 process starts. The connection already exists at this time; the
2550 socket is available as the standard input descriptor and as the
2551 standard output descriptor (descriptors 0 and 1) in the server
2552 process. So the server program can begin reading and writing data
2553 right away. Often the program needs only the ordinary I/O facilities;
2554 in fact, a general-purpose filter program that knows nothing about
2555 sockets can work as a byte stream server run by @code{inetd}.
2557 You can also use @code{inetd} for servers that use connectionless
2558 communication styles. For these servers, @code{inetd} does not try to accept
2559 a connection, since no connection is possible. It just starts the
2560 server program, which can read the incoming datagram packet from
2561 descriptor 0. The server program can handle one request and then
2562 exit, or you can choose to write it to keep reading more requests
2563 until no more arrive, and then exit. You must specify which of these
2564 two techniques the server uses, when you configure @code{inetd}.
2566 @node Configuring Inetd
2567 @subsection Configuring @code{inetd}
2569 The file @file{/etc/inetd.conf} tells @code{inetd} which ports to listen to
2570 and what server programs to run for them. Normally each entry in the
2571 file is one line, but you can split it onto multiple lines provided
2572 all but the first line of the entry start with whitespace. Lines that
2573 start with @samp{#} are comments.
2575 Here are two standard entries in @file{/etc/inetd.conf}:
2578 ftp stream tcp nowait root /libexec/ftpd ftpd
2579 talk dgram udp wait root /libexec/talkd talkd
2582 An entry has this format:
2585 @var{service} @var{style} @var{protocol} @var{wait} @var{username} @var{program} @var{arguments}
2588 The @var{service} field says which service this program provides. It
2589 should be the name of a service defined in @file{/etc/services}.
2590 @code{inetd} uses @var{service} to decide which port to listen on for
2593 The fields @var{style} and @var{protocol} specify the communication
2594 style and the protocol to use for the listening socket. The style
2595 should be the name of a communication style, converted to lower case
2596 and with @samp{SOCK_} deleted---for example, @samp{stream} or
2597 @samp{dgram}. @var{protocol} should be one of the protocols listed in
2598 @file{/etc/protocols}. The typical protocol names are @samp{tcp} for
2599 byte stream connections and @samp{udp} for unreliable datagrams.
2601 The @var{wait} field should be either @samp{wait} or @samp{nowait}.
2602 Use @samp{wait} if @var{style} is a connectionless style and the
2603 server, once started, handles multiple requests, as many as come in.
2604 Use @samp{nowait} if @code{inetd} should start a new process for each message
2605 or request that comes in. If @var{style} uses connections, then
2606 @var{wait} @strong{must} be @samp{nowait}.
2608 @var{user} is the user name that the server should run as. @code{inetd} runs
2609 as root, so it can set the user ID of its children arbitrarily. It's
2610 best to avoid using @samp{root} for @var{user} if you can; but some
2611 servers, such as Telnet and FTP, read a username and password
2612 themselves. These servers need to be root initially so they can log
2613 in as commanded by the data coming over the network.
2615 @var{program} together with @var{arguments} specifies the command to
2616 run to start the server. @var{program} should be an absolute file
2617 name specifying the executable file to run. @var{arguments} consists
2618 of any number of whitespace-separated words, which become the
2619 command-line arguments of @var{program}. The first word in
2620 @var{arguments} is argument zero, which should by convention be the
2621 program name itself (sans directories).
2623 If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the
2624 file and obey its new contents by sending the @code{inetd} process the
2625 @code{SIGHUP} signal. You'll have to use @code{ps} to determine the
2626 process ID of the @code{inetd} process, as it is not fixed.
2628 @c !!! could document /etc/inetd.sec
2630 @node Socket Options
2631 @section Socket Options
2632 @cindex socket options
2634 This section describes how to read or set various options that modify
2635 the behavior of sockets and their underlying communications protocols.
2637 @cindex level, for socket options
2638 @cindex socket option level
2639 When you are manipulating a socket option, you must specify which
2640 @dfn{level} the option pertains to. This describes whether the option
2641 applies to the socket interface, or to a lower-level communications
2645 * Socket Option Functions:: The basic functions for setting and getting
2647 * Socket-Level Options:: Details of the options at the socket level.
2650 @node Socket Option Functions
2651 @subsection Socket Option Functions
2653 @pindex sys/socket.h
2654 Here are the functions for examining and modifying socket options.
2655 They are declared in @file{sys/socket.h}.
2657 @comment sys/socket.h
2659 @deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr})
2660 The @code{getsockopt} function gets information about the value of
2661 option @var{optname} at level @var{level} for socket @var{socket}.
2663 The option value is stored in a buffer that @var{optval} points to.
2664 Before the call, you should supply in @code{*@var{optlen-ptr}} the
2665 size of this buffer; on return, it contains the number of bytes of
2666 information actually stored in the buffer.
2668 Most options interpret the @var{optval} buffer as a single @code{int}
2671 The actual return value of @code{getsockopt} is @code{0} on success
2672 and @code{-1} on failure. The following @code{errno} error conditions
2677 The @var{socket} argument is not a valid file descriptor.
2680 The descriptor @var{socket} is not a socket.
2683 The @var{optname} doesn't make sense for the given @var{level}.
2687 @comment sys/socket.h
2689 @deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t @var{optlen})
2690 This function is used to set the socket option @var{optname} at level
2691 @var{level} for socket @var{socket}. The value of the option is passed
2692 in the buffer @var{optval}, which has size @var{optlen}.
2697 The return value and error codes for @code{setsockopt} are the same as
2698 for @code{getsockopt}.
2701 The return value and error codes for @code{setsockopt} are the same as
2702 for @code{getsockopt}.
2707 @node Socket-Level Options
2708 @subsection Socket-Level Options
2710 @comment sys/socket.h
2712 @deftypevr Constant int SOL_SOCKET
2713 Use this constant as the @var{level} argument to @code{getsockopt} or
2714 @code{setsockopt} to manipulate the socket-level options described in
2718 @pindex sys/socket.h
2720 Here is a table of socket-level option names; all are defined in the
2721 header file@*@file{sys/socket.h}.
2724 @comment sys/socket.h
2727 @c Extra blank line here makes the table look better.
2729 This option toggles recording of debugging information in the underlying
2730 protocol modules. The value has type @code{int}; a nonzero value means
2732 @c !!! should say how this is used
2733 @c Ok, anyone who knows, please explain.
2735 @comment sys/socket.h
2738 This option controls whether @code{bind} (@pxref{Setting Address})
2739 should permit reuse of local addresses for this socket. If you enable
2740 this option, you can actually have two sockets with the same Internet
2741 port number; but the system won't allow you to use the two
2742 identically-named sockets in a way that would confuse the Internet. The
2743 reason for this option is that some higher-level Internet protocols,
2744 including FTP, require you to keep reusing the same socket number.
2746 The value has type @code{int}; a nonzero value means ``yes''.
2748 @comment sys/socket.h
2751 This option controls whether the underlying protocol should
2752 periodically transmit messages on a connected socket. If the peer
2753 fails to respond to these messages, the connection is considered
2754 broken. The value has type @code{int}; a nonzero value means
2757 @comment sys/socket.h
2760 This option controls whether outgoing messages bypass the normal
2761 message routing facilities. If set, messages are sent directly to the
2762 network interface instead. The value has type @code{int}; a nonzero
2763 value means ``yes''.
2765 @comment sys/socket.h
2768 This option specifies what should happen when the socket of a type
2769 that promises reliable delivery still has untransmitted messages when
2770 it is closed; see @ref{Closing a Socket}. The value has type
2771 @code{struct linger}.
2773 @comment sys/socket.h
2775 @deftp {Data Type} {struct linger}
2776 This structure type has the following members:
2780 This field is interpreted as a boolean. If nonzero, @code{close}
2781 blocks until the data is transmitted or the timeout period has expired.
2784 This specifies the timeout period, in seconds.
2788 @comment sys/socket.h
2791 This option controls whether datagrams may be broadcast from the socket.
2792 The value has type @code{int}; a nonzero value means ``yes''.
2794 @comment sys/socket.h
2797 If this option is set, out-of-band data received on the socket is
2798 placed in the normal input queue. This permits it to be read using
2799 @code{read} or @code{recv} without specifying the @code{MSG_OOB}
2800 flag. @xref{Out-of-Band Data}. The value has type @code{int}; a
2801 nonzero value means ``yes''.
2803 @comment sys/socket.h
2806 This option gets or sets the size of the output buffer. The value is a
2807 @code{size_t}, which is the size in bytes.
2809 @comment sys/socket.h
2812 This option gets or sets the size of the input buffer. The value is a
2813 @code{size_t}, which is the size in bytes.
2815 @comment sys/socket.h
2818 @comment sys/socket.h
2821 This option can be used with @code{getsockopt} only. It is used to
2822 get the socket's communication style. @code{SO_TYPE} is the
2823 historical name, and @code{SO_STYLE} is the preferred name in GNU.
2824 The value has type @code{int} and its value designates a communication
2825 style; see @ref{Communication Styles}.
2827 @comment sys/socket.h
2830 @c Extra blank line here makes the table look better.
2832 This option can be used with @code{getsockopt} only. It is used to reset
2833 the error status of the socket. The value is an @code{int}, which represents
2834 the previous error status.
2835 @c !!! what is "socket error status"? this is never defined.
2838 @node Networks Database
2839 @section Networks Database
2840 @cindex networks database
2841 @cindex converting network number to network name
2842 @cindex converting network name to network number
2844 @pindex /etc/networks
2846 Many systems come with a database that records a list of networks known
2847 to the system developer. This is usually kept either in the file
2848 @file{/etc/networks} or in an equivalent from a name server. This data
2849 base is useful for routing programs such as @code{route}, but it is not
2850 useful for programs that simply communicate over the network. We
2851 provide functions to access this data base, which are declared in
2856 @deftp {Data Type} {struct netent}
2857 This data type is used to represent information about entries in the
2858 networks database. It has the following members:
2862 This is the ``official'' name of the network.
2864 @item char **n_aliases
2865 These are alternative names for the network, represented as a vector
2866 of strings. A null pointer terminates the array.
2868 @item int n_addrtype
2869 This is the type of the network number; this is always equal to
2870 @code{AF_INET} for Internet networks.
2872 @item unsigned long int n_net
2873 This is the network number. Network numbers are returned in host
2874 byte order; see @ref{Byte Order}.
2878 Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search
2879 the networks database for information about a specific network. The
2880 information is returned in a statically-allocated structure; you must
2881 copy the information if you need to save it.
2885 @deftypefun {struct netent *} getnetbyname (const char *@var{name})
2886 The @code{getnetbyname} function returns information about the network
2887 named @var{name}. It returns a null pointer if there is no such
2893 @deftypefun {struct netent *} getnetbyaddr (long @var{net}, int @var{type})
2894 The @code{getnetbyaddr} function returns information about the network
2895 of type @var{type} with number @var{net}. You should specify a value of
2896 @code{AF_INET} for the @var{type} argument for Internet networks.
2898 @code{getnetbyaddr} returns a null pointer if there is no such
2902 You can also scan the networks database using @code{setnetent},
2903 @code{getnetent}, and @code{endnetent}. Be careful in using these
2904 functions, because they are not reentrant.
2908 @deftypefun void setnetent (int @var{stayopen})
2909 This function opens and rewinds the networks database.
2911 If the @var{stayopen} argument is nonzero, this sets a flag so that
2912 subsequent calls to @code{getnetbyname} or @code{getnetbyaddr} will
2913 not close the database (as they usually would). This makes for more
2914 efficiency if you call those functions several times, by avoiding
2915 reopening the database for each call.
2920 @deftypefun {struct netent *} getnetent (void)
2921 This function returns the next entry in the networks database. It
2922 returns a null pointer if there are no more entries.
2927 @deftypefun void endnetent (void)
2928 This function closes the networks database.