1 @node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top
2 @c %MENU% A more complicated IPC mechanism, with networking support
5 This chapter describes the GNU facilities for interprocess
6 communication using sockets.
9 @cindex interprocess communication, with sockets
10 A @dfn{socket} is a generalized interprocess communication channel.
11 Like a pipe, a socket is represented as a file descriptor. Unlike pipes
12 sockets support communication between unrelated processes, and even
13 between processes running on different machines that communicate over a
14 network. Sockets are the primary means of communicating with other
15 machines; @code{telnet}, @code{rlogin}, @code{ftp}, @code{talk} and the
16 other familiar network programs use sockets.
18 Not all operating systems support sockets. In @theglibc{}, 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. The
25 reentrant functions and some newer functions that are related to IPv6
26 aren't documented either so far.
29 * Socket Concepts:: Basic concepts you need to know about.
30 * Communication Styles::Stream communication, datagrams and other styles.
31 * Socket Addresses:: How socket names (``addresses'') work.
32 * Interface Naming:: Identifying specific network interfaces.
33 * Local Namespace:: Details about the local namespace.
34 * Internet Namespace:: Details about the Internet namespace.
35 * Misc Namespaces:: Other namespaces not documented fully here.
36 * Open/Close Sockets:: Creating sockets and destroying them.
37 * Connections:: Operations on sockets with connection state.
38 * Datagrams:: Operations on datagram sockets.
39 * Inetd:: Inetd is a daemon that starts servers on request.
40 The most convenient way to write a server
41 is to make it work with Inetd.
42 * Socket Options:: Miscellaneous low-level socket options.
43 * Networks Database:: Accessing the database of network names.
44 * Other Socket APIs:: Other socket-related functions.
48 @section Socket Concepts
50 @cindex communication style (of a socket)
51 @cindex style of communication (of a socket)
52 When you create a socket, you must specify the style of communication
53 you want to use and the type of protocol that should implement it.
54 The @dfn{communication style} of a socket defines the user-level
55 semantics of sending and receiving data on the socket. Choosing a
56 communication style specifies the answers to questions such as these:
62 @cindex stream (sockets)
63 @strong{What are the units of data transmission?} Some communication
64 styles regard the data as a sequence of bytes with no larger
65 structure; others group the bytes into records (which are known in
66 this context as @dfn{packets}).
69 @cindex loss of data on sockets
70 @cindex data loss on sockets
71 @strong{Can data be lost during normal operation?} Some communication
72 styles guarantee that all the data sent arrives in the order it was
73 sent (barring system or network crashes); other styles occasionally
74 lose data as a normal part of operation, and may sometimes deliver
75 packets more than once or in the wrong order.
77 Designing a program to use unreliable communication styles usually
78 involves taking precautions to detect lost or misordered packets and
79 to retransmit data as needed.
82 @strong{Is communication entirely with one partner?} Some
83 communication styles are like a telephone call---you make a
84 @dfn{connection} with one remote socket and then exchange data
85 freely. Other styles are like mailing letters---you specify a
86 destination address for each message you send.
89 @cindex namespace (of socket)
90 @cindex domain (of socket)
91 @cindex socket namespace
93 You must also choose a @dfn{namespace} for naming the socket. A socket
94 name (``address'') is meaningful only in the context of a particular
95 namespace. In fact, even the data type to use for a socket name may
96 depend on the namespace. Namespaces are also called ``domains'', but we
97 avoid that word as it can be confused with other usage of the same
98 term. Each namespace has a symbolic name that starts with @samp{PF_}.
99 A corresponding symbolic name starting with @samp{AF_} designates the
100 address format for that namespace.
102 @cindex network protocol
103 @cindex protocol (of socket)
104 @cindex socket protocol
105 @cindex protocol family
106 Finally you must choose the @dfn{protocol} to carry out the
107 communication. The protocol determines what low-level mechanism is used
108 to transmit and receive data. Each protocol is valid for a particular
109 namespace and communication style; a namespace is sometimes called a
110 @dfn{protocol family} because of this, which is why the namespace names
111 start with @samp{PF_}.
113 The rules of a protocol apply to the data passing between two programs,
114 perhaps on different computers; most of these rules are handled by the
115 operating system and you need not know about them. What you do need to
116 know about protocols is this:
120 In order to have communication between two sockets, they must specify
121 the @emph{same} protocol.
124 Each protocol is meaningful with particular style/namespace
125 combinations and cannot be used with inappropriate combinations. For
126 example, the TCP protocol fits only the byte stream style of
127 communication and the Internet namespace.
130 For each combination of style and namespace there is a @dfn{default
131 protocol}, which you can request by specifying 0 as the protocol
132 number. And that's what you should normally do---use the default.
135 Throughout the following description at various places
136 variables/parameters to denote sizes are required. And here the trouble
137 starts. In the first implementations the type of these variables was
138 simply @code{int}. On most machines at that time an @code{int} was 32
139 bits wide, which created a @emph{de facto} standard requiring 32-bit
140 variables. This is important since references to variables of this type
141 are passed to the kernel.
143 Then the POSIX people came and unified the interface with the words "all
144 size values are of type @code{size_t}". On 64-bit machines
145 @code{size_t} is 64 bits wide, so pointers to variables were no longer
148 The Unix98 specification provides a solution by introducing a type
149 @code{socklen_t}. This type is used in all of the cases that POSIX
150 changed to use @code{size_t}. The only requirement of this type is that
151 it be an unsigned type of at least 32 bits. Therefore, implementations
152 which require that references to 32-bit variables be passed can be as
153 happy as implementations which use 64-bit values.
156 @node Communication Styles
157 @section Communication Styles
159 @Theglibc{} includes support for several different kinds of sockets,
160 each with different characteristics. This section describes the
161 supported socket types. The symbolic constants listed here are
162 defined in @file{sys/socket.h}.
165 @deftypevr Macro int SOCK_STREAM
166 @standards{BSD, sys/socket.h}
167 The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}).
168 It operates over a connection with a particular remote socket and
169 transmits data reliably as a stream of bytes.
171 Use of this style is covered in detail in @ref{Connections}.
174 @deftypevr Macro int SOCK_DGRAM
175 @standards{BSD, sys/socket.h}
176 The @code{SOCK_DGRAM} style is used for sending
177 individually-addressed packets unreliably.
178 It is the diametrical opposite of @code{SOCK_STREAM}.
180 Each time you write data to a socket of this kind, that data becomes
181 one packet. Since @code{SOCK_DGRAM} sockets do not have connections,
182 you must specify the recipient address with each packet.
184 The only guarantee that the system makes about your requests to
185 transmit data is that it will try its best to deliver each packet you
186 send. It may succeed with the sixth packet after failing with the
187 fourth and fifth packets; the seventh packet may arrive before the
188 sixth, and may arrive a second time after the sixth.
190 The typical use for @code{SOCK_DGRAM} is in situations where it is
191 acceptable to simply re-send a packet if no response is seen in a
192 reasonable amount of time.
194 @xref{Datagrams}, for detailed information about how to use datagram
199 @c This appears to be only for the NS domain, which we aren't
200 @c discussing and probably won't support either.
201 @deftypevr Macro int SOCK_SEQPACKET
202 @standards{BSD, sys/socket.h}
203 This style is like @code{SOCK_STREAM} except that the data are
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 @deftypevr Macro int SOCK_RDM
218 @standards{BSD, sys/socket.h}
219 This style is a reliable version of @code{SOCK_DGRAM}: it sends
220 individually addressed packets, but guarantees that each packet sent
221 arrives exactly once.
223 @strong{Warning:} It is not clear this is actually supported
224 by any operating system.
228 @deftypevr Macro int SOCK_RAW
229 @standards{BSD, sys/socket.h}
230 This style provides access to low-level network protocols and
231 interfaces. Ordinary user programs usually have no need to use this
235 @node Socket Addresses
236 @section Socket Addresses
238 @cindex address of socket
239 @cindex name of socket
240 @cindex binding a socket address
241 @cindex socket address (name) binding
242 The name of a socket is normally called an @dfn{address}. The
243 functions and symbols for dealing with socket addresses were named
244 inconsistently, sometimes using the term ``name'' and sometimes using
245 ``address''. You can regard these terms as synonymous where sockets
248 A socket newly created with the @code{socket} function has no
249 address. Other processes can find it for communication only if you
250 give it an address. We call this @dfn{binding} the address to the
251 socket, and the way to do it is with the @code{bind} function.
253 You need only be concerned with the address of a socket if other processes
254 are to find it and start communicating with it. You can specify an
255 address for other sockets, but this is usually pointless; the first time
256 you send data from a socket, or use it to initiate a connection, the
257 system assigns an address automatically if you have not specified one.
259 Occasionally a client needs to specify an address because the server
260 discriminates based on address; for example, the rsh and rlogin
261 protocols look at the client's socket address and only bypass passphrase
262 checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
264 The details of socket addresses vary depending on what namespace you are
265 using. @xref{Local Namespace}, or @ref{Internet Namespace}, for specific
268 Regardless of the namespace, you use the same functions @code{bind} and
269 @code{getsockname} to set and examine a socket's address. These
270 functions use a phony data type, @code{struct sockaddr *}, to accept the
271 address. In practice, the address lives in a structure of some other
272 data type appropriate to the address format you are using, but you cast
273 its address to @code{struct sockaddr *} when you pass it to
277 * Address Formats:: About @code{struct sockaddr}.
278 * Setting Address:: Binding an address to a socket.
279 * Reading Address:: Reading the address of a socket.
282 @node Address Formats
283 @subsection Address Formats
285 The functions @code{bind} and @code{getsockname} use the generic data
286 type @code{struct sockaddr *} to represent a pointer to a socket
287 address. You can't use this data type effectively to interpret an
288 address or construct one; for that, you must use the proper data type
289 for the socket's namespace.
291 Thus, the usual practice is to construct an address of the proper
292 namespace-specific type, then cast a pointer to @code{struct sockaddr *}
293 when you call @code{bind} or @code{getsockname}.
295 The one piece of information that you can get from the @code{struct
296 sockaddr} data type is the @dfn{address format designator}. This tells
297 you which data type to use to understand the address fully.
300 The symbols in this section are defined in the header file
303 @deftp {Data Type} {struct sockaddr}
304 @standards{BSD, sys/socket.h}
305 The @code{struct sockaddr} type itself has the following members:
308 @item short int sa_family
309 This is the code for the address format of this address. It
310 identifies the format of the data which follows.
312 @item char sa_data[14]
313 This is the actual socket address data, which is format-dependent. Its
314 length also depends on the format, and may well be more than 14. The
315 length 14 of @code{sa_data} is essentially arbitrary.
319 Each address format has a symbolic name which starts with @samp{AF_}.
320 Each of them corresponds to a @samp{PF_} symbol which designates the
321 corresponding namespace. Here is a list of address format names:
325 @standards{POSIX, sys/socket.h}
326 This designates the address format that goes with the local namespace.
327 (@code{PF_LOCAL} is the name of that namespace.) @xref{Local Namespace
328 Details}, for information about this address format.
331 @standards{BSD, sys/socket.h}
332 @standards{Unix98, sys/socket.h}
333 This is a synonym for @code{AF_LOCAL}. Although @code{AF_LOCAL} is
334 mandated by POSIX.1g, @code{AF_UNIX} is portable to more systems.
335 @code{AF_UNIX} was the traditional name stemming from BSD, so even most
336 POSIX systems support it. It is also the name of choice in the Unix98
337 specification. (The same is true for @code{PF_UNIX}
338 vs. @code{PF_LOCAL}).
341 @standards{GNU, sys/socket.h}
342 This is another synonym for @code{AF_LOCAL}, for compatibility.
343 (@code{PF_FILE} is likewise a synonym for @code{PF_LOCAL}.)
346 @standards{BSD, sys/socket.h}
347 This designates the address format that goes with the Internet
348 namespace. (@code{PF_INET} is the name of that namespace.)
349 @xref{Internet Address Formats}.
352 @standards{IPv6 Basic API, sys/socket.h}
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.)
357 @standards{BSD, sys/socket.h}
358 This designates no particular address format. It is used only in rare
359 cases, such as to clear out the default destination address of a
360 ``connected'' datagram socket. @xref{Sending Datagrams}.
362 The corresponding namespace designator symbol @code{PF_UNSPEC} exists
363 for completeness, but there is no reason to use it in a program.
366 @file{sys/socket.h} defines symbols starting with @samp{AF_} for many
367 different kinds of networks, most or all of which are not actually
368 implemented. We will document those that really work as we receive
369 information about how to use them.
371 @node Setting Address
372 @subsection Setting the Address of a Socket
375 Use the @code{bind} function to assign an address to a socket. The
376 prototype for @code{bind} is in the header file @file{sys/socket.h}.
377 For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}.
379 @deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
380 @standards{BSD, sys/socket.h}
381 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
382 @c Direct syscall, except on Hurd.
383 The @code{bind} function assigns an address to the socket
384 @var{socket}. The @var{addr} and @var{length} arguments specify the
385 address; the detailed format of the address depends on the namespace.
386 The first part of the address is always the format designator, which
387 specifies a namespace, and says that the address is in the format of
390 The return value is @code{0} on success and @code{-1} on failure. The
391 following @code{errno} error conditions are defined for this function:
395 The @var{socket} argument is not a valid file descriptor.
398 The descriptor @var{socket} is not a socket.
401 The specified address is not available on this machine.
404 Some other socket is already using the specified address.
407 The socket @var{socket} already has an address.
410 You do not have permission to access the requested address. (In the
411 Internet domain, only the super-user is allowed to specify a port number
412 in the range 0 through @code{IPPORT_RESERVED} minus one; see
416 Additional conditions may be possible depending on the particular namespace
420 @node Reading Address
421 @subsection Reading the Address of a Socket
424 Use the function @code{getsockname} to examine the address of an
425 Internet socket. The prototype for this function is in the header file
428 @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
429 @standards{BSD, sys/socket.h}
430 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsmem{/hurd}}}
431 @c Direct syscall, except on Hurd, where it seems like it might leak
433 The @code{getsockname} function returns information about the
434 address of the socket @var{socket} in the locations specified by the
435 @var{addr} and @var{length-ptr} arguments. Note that the
436 @var{length-ptr} is a pointer; you should initialize it to be the
437 allocation size of @var{addr}, and on return it contains the actual
438 size of the address data.
440 The format of the address data depends on the socket namespace. The
441 length of the information is usually fixed for a given namespace, so
442 normally you can know exactly how much space is needed and can provide
443 that much. The usual practice is to allocate a place for the value
444 using the proper data type for the socket's namespace, then cast its
445 address to @code{struct sockaddr *} to pass it to @code{getsockname}.
447 The return value is @code{0} on success and @code{-1} on error. The
448 following @code{errno} error conditions are defined for this function:
452 The @var{socket} argument is not a valid file descriptor.
455 The descriptor @var{socket} is not a socket.
458 There are not enough internal buffers available for the operation.
462 You can't read the address of a socket in the file namespace. This is
463 consistent with the rest of the system; in general, there's no way to
464 find a file's name from a descriptor for that file.
466 @node Interface Naming
467 @section Interface Naming
469 Each network interface has a name. This usually consists of a few
470 letters that relate to the type of interface, which may be followed by a
471 number if there is more than one interface of that type. Examples
472 might be @code{lo} (the loopback interface) and @code{eth0} (the first
475 Although such names are convenient for humans, it would be clumsy to
476 have to use them whenever a program needs to refer to an interface. In
477 such situations an interface is referred to by its @dfn{index}, which is
478 an arbitrarily-assigned small positive integer.
480 The following functions, constants and data types are declared in the
481 header file @file{net/if.h}.
483 @deftypevr Constant size_t IFNAMSIZ
484 @standards{???, net/if.h}
485 This constant defines the maximum buffer size needed to hold an
486 interface name, including its terminating zero byte.
489 @deftypefun {unsigned int} if_nametoindex (const char *@var{ifname})
490 @standards{IPv6 basic API, net/if.h}
491 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
492 @c It opens a socket to use ioctl on the fd to get the index.
493 @c opensock may call socket and access multiple times until it finds a
494 @c socket family that works. The Linux implementation has a potential
495 @c concurrency issue WRT last_type and last_family not being updated
496 @c atomically, but it is harmless; the generic implementation, OTOH,
497 @c takes a lock, which makes all callers AS- and AC-Unsafe.
498 @c opensock @asulock @aculock @acsfd
499 This function yields the interface index corresponding to a particular
500 name. If no interface exists with the name given, it returns 0.
503 @deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname})
504 @standards{IPv6 basic API, net/if.h}
505 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
506 @c It opens a socket with opensock to use ioctl on the fd to get the
507 @c name from the index.
508 This function maps an interface index to its corresponding name. The
509 returned name is placed in the buffer pointed to by @code{ifname}, which
510 must be at least @code{IFNAMSIZ} bytes in length. If the index was
511 invalid, the function's return value is a null pointer, otherwise it is
515 @deftp {Data Type} {struct if_nameindex}
516 @standards{IPv6 basic API, net/if.h}
517 This data type is used to hold the information about a single
518 interface. It has the following members:
521 @item unsigned int if_index;
522 This is the interface index.
525 This is the null-terminated index name.
530 @deftypefun {struct if_nameindex *} if_nameindex (void)
531 @standards{IPv6 basic API, net/if.h}
532 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@aculock{/hurd} @acsfd{} @acsmem{}}}
533 @c if_nameindex @ascuheap @asulock/hurd @aculock/hurd @acsfd @acsmem
535 @c netlink_open @acsfd @acsmem/hurd
539 @c netlink_close dup @acsfd
540 @c getsockname dup @acsmem/hurd
541 @c netlink_request @ascuheap @acsmem
542 @c getpagesize dup ok
543 @c malloc dup @ascuheap @acsmem
544 @c netlink_sendreq ok
549 @c free dup @ascuheap @acsmem
550 @c netlink_free_handle @ascuheap @acsmem
551 @c free dup @ascuheap @acsmem
552 @c netlink_close @acsfd
554 @c malloc dup @asuheap @acsmem
555 @c strndup @ascuheap @acsmem
556 @c if_freenameindex @ascuheap @acsmem
558 @c opensock dup @asulock @aculock @acsfd
559 @c hurd_socket_server ok
560 @c pfinet_siocgifconf ok
561 @c malloc @ascuheap @acsmem
562 @c strdup @ascuheap @acsmem
564 @c free @ascuheap @acsmem
565 This function returns an array of @code{if_nameindex} structures, one
566 for every interface that is present. The end of the list is indicated
567 by a structure with an interface of 0 and a null name pointer. If an
568 error occurs, this function returns a null pointer.
570 The returned structure must be freed with @code{if_freenameindex} after
574 @deftypefun void if_freenameindex (struct if_nameindex *@var{ptr})
575 @standards{IPv6 basic API, net/if.h}
576 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
577 @c if_freenameindex @ascuheap @acsmem
578 @c free dup @ascuheap @acsmem
579 This function frees the structure returned by an earlier call to
583 @node Local Namespace
584 @section The Local Namespace
585 @cindex local namespace, for sockets
587 This section describes the details of the local namespace, whose
588 symbolic name (required when you create a socket) is @code{PF_LOCAL}.
589 The local namespace is also known as ``Unix domain sockets''. Another
590 name is file namespace since socket addresses are normally implemented
594 * Concepts: Local Namespace Concepts. What you need to understand.
595 * Details: Local Namespace Details. Address format, symbolic names, etc.
596 * Example: Local Socket Example. Example of creating a socket.
599 @node Local Namespace Concepts
600 @subsection Local Namespace Concepts
602 In the local namespace socket addresses are file names. You can specify
603 any file name you want as the address of the socket, but you must have
604 write permission on the directory containing it.
605 @c XXX The following was said to be wrong.
606 @c In order to connect to a socket you must have read permission for it.
607 It's common to put these files in the @file{/tmp} directory.
609 One peculiarity of the local namespace is that the name is only used
610 when opening the connection; once open the address is not meaningful and
613 Another peculiarity is that you cannot connect to such a socket from
614 another machine--not even if the other machine shares the file system
615 which contains the name of the socket. You can see the socket in a
616 directory listing, but connecting to it never succeeds. Some programs
617 take advantage of this, such as by asking the client to send its own
618 process ID, and using the process IDs to distinguish between clients.
619 However, we recommend you not use this method in protocols you design,
620 as we might someday permit connections from other machines that mount
621 the same file systems. Instead, send each new client an identifying
622 number if you want it to have one.
624 After you close a socket in the local namespace, you should delete the
625 file name from the file system. Use @code{unlink} or @code{remove} to
626 do this; see @ref{Deleting Files}.
628 The local namespace supports just one protocol for any communication
629 style; it is protocol number @code{0}.
631 @node Local Namespace Details
632 @subsection Details of Local Namespace
635 To create a socket in the local namespace, use the constant
636 @code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or
637 @code{socketpair}. This constant is defined in @file{sys/socket.h}.
639 @deftypevr Macro int PF_LOCAL
640 @standards{POSIX, sys/socket.h}
641 This designates the local namespace, in which socket addresses are local
642 names, and its associated family of protocols. @code{PF_LOCAL} is the
643 macro used by POSIX.1g.
646 @deftypevr Macro int PF_UNIX
647 @standards{BSD, sys/socket.h}
648 This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
651 @deftypevr Macro int PF_FILE
652 @standards{GNU, sys/socket.h}
653 This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
656 The structure for specifying socket names in the local namespace is
657 defined in the header file @file{sys/un.h}:
660 @deftp {Data Type} {struct sockaddr_un}
661 @standards{BSD, sys/un.h}
662 This structure is used to specify local namespace socket addresses. It has
663 the following members:
666 @item short int sun_family
667 This identifies the address family or format of the socket address.
668 You should store the value @code{AF_LOCAL} to designate the local
669 namespace. @xref{Socket Addresses}.
671 @item char sun_path[108]
672 This is the file name to use.
674 @strong{Incomplete:} Why is 108 a magic number? RMS suggests making
675 this a zero-length array and tweaking the following example to use
676 @code{alloca} to allocate an appropriate amount of storage based on
677 the length of the filename.
681 You should compute the @var{length} parameter for a socket address in
682 the local namespace as the sum of the size of the @code{sun_family}
683 component and the string length (@emph{not} the allocation size!) of
684 the file name string. This can be done using the macro @code{SUN_LEN}:
686 @deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr})
687 @standards{BSD, sys/un.h}
688 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
689 This macro computes the length of the socket address in the local namespace.
692 @node Local Socket Example
693 @subsection Example of Local-Namespace Sockets
695 Here is an example showing how to create and name a socket in the local
699 @include mkfsock.c.texi
702 @node Internet Namespace
703 @section The Internet Namespace
704 @cindex Internet namespace, for sockets
706 This section describes the details of the protocols and socket naming
707 conventions used in the Internet namespace.
709 Originally the Internet namespace used only IP version 4 (IPv4). With
710 the growing number of hosts on the Internet, a new protocol with a
711 larger address space was necessary: IP version 6 (IPv6). IPv6
712 introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
713 features, and will eventually replace IPv4.
715 To create a socket in the IPv4 Internet namespace, use the symbolic name
716 @code{PF_INET} of this namespace as the @var{namespace} argument to
717 @code{socket} or @code{socketpair}. For IPv6 addresses you need the
718 macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}.
721 @deftypevr Macro int PF_INET
722 @standards{BSD, sys/socket.h}
723 This designates the IPv4 Internet namespace and associated family of
727 @deftypevr Macro int PF_INET6
728 @standards{X/Open, sys/socket.h}
729 This designates the IPv6 Internet namespace and associated family of
733 A socket address for the Internet namespace includes the following components:
737 The address of the machine you want to connect to. Internet addresses
738 can be specified in several ways; these are discussed in @ref{Internet
739 Address Formats}, @ref{Host Addresses} and @ref{Host Names}.
742 A port number for that machine. @xref{Ports}.
745 You must ensure that the address and port number are represented in a
746 canonical format called @dfn{network byte order}. @xref{Byte Order},
747 for information about this.
750 * Internet Address Formats:: How socket addresses are specified in the
752 * Host Addresses:: All about host addresses of Internet host.
753 * Ports:: Internet port numbers.
754 * Services Database:: Ports may have symbolic names.
755 * Byte Order:: Different hosts may use different byte
756 ordering conventions; you need to
757 canonicalize host address and port number.
758 * Protocols Database:: Referring to protocols by name.
759 * Inet Example:: Putting it all together.
762 @node Internet Address Formats
763 @subsection Internet Socket Address Formats
765 In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6
766 (@code{AF_INET6}), a socket address consists of a host address
767 and a port on that host. In addition, the protocol you choose serves
768 effectively as a part of the address because local port numbers are
769 meaningful only within a particular protocol.
771 The data types for representing socket addresses in the Internet namespace
772 are defined in the header file @file{netinet/in.h}.
775 @deftp {Data Type} {struct sockaddr_in}
776 @standards{BSD, netinet/in.h}
777 This is the data type used to represent socket addresses in the
778 Internet namespace. It has the following members:
781 @item sa_family_t sin_family
782 This identifies the address family or format of the socket address.
783 You should store the value @code{AF_INET} in this member. The address
784 family is stored in host byte order. @xref{Socket Addresses}.
786 @item struct in_addr sin_addr
787 This is the IPv4 address. @xref{Host Addresses}, and @ref{Host
788 Names}, for how to get a value to store here. The IPv4 address is
789 stored in network byte order.
791 @item unsigned short int sin_port
792 This is the port number. @xref{Ports}. The port number is stored in
797 When you call @code{bind} or @code{getsockname}, you should specify
798 @code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
799 you are using an IPv4 Internet namespace socket address.
801 @deftp {Data Type} {struct sockaddr_in6}
802 This is the data type used to represent socket addresses in the IPv6
803 namespace. It has the following members:
806 @item sa_family_t sin6_family
807 This identifies the address family or format of the socket address.
808 You should store the value of @code{AF_INET6} in this member.
809 @xref{Socket Addresses}. The address family is stored in host byte
812 @item struct in6_addr sin6_addr
813 This is the IPv6 address of the host machine. @xref{Host
814 Addresses}, and @ref{Host Names}, for how to get a value to store
815 here. The address is stored in network byte order.
817 @item uint32_t sin6_flowinfo
819 @cindex IPv6 flow label
820 @cindex traffic class
821 @cindex IPv6 traffic class
822 This combines the IPv6 traffic class and flow label values, as found
823 in the IPv6 header. This field is stored in network byte order. Only
824 the 28 lower bits (of the number in network byte order) are used; the
825 remaining bits must be zero. The lower 20 bits are the flow label, and
826 bits 20 to 27 are the the traffic class. Typically, this field is
829 @item uint32_t sin6_scope_id
831 @cindex IPv6 scope ID
832 For link-local addresses, this identifies the interface on which this
833 address is valid. The scope ID is stored in host byte order.
834 Typically, this field is zero.
836 @item uint16_t sin6_port
837 This is the port number. @xref{Ports}. The port number is stored in
844 @subsection Host Addresses
846 Each computer on the Internet has one or more @dfn{Internet addresses},
847 numbers which identify that computer among all those on the Internet.
848 Users typically write IPv4 numeric host addresses as sequences of four
849 numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6
850 numeric host addresses as sequences of up to eight numbers separated by
851 colons, as in @samp{5f03:1200:836f:c100::1}.
853 Each computer also has one or more @dfn{host names}, which are strings
854 of words separated by periods, as in @samp{www.gnu.org}.
856 Programs that let the user specify a host typically accept both numeric
857 addresses and host names. To open a connection a program needs a
858 numeric address, and so must convert a host name to the numeric address
862 * Abstract Host Addresses:: What a host number consists of.
863 * Data type: Host Address Data Type. Data type for a host number.
864 * Functions: Host Address Functions. Functions to operate on them.
865 * Names: Host Names. Translating host names to host numbers.
868 @node Abstract Host Addresses
869 @subsubsection Internet Host Addresses
870 @cindex host address, Internet
871 @cindex Internet host address
874 Each computer on the Internet has one or more Internet addresses,
875 numbers which identify that computer among all those on the Internet.
878 @cindex network number
879 @cindex local network address number
880 An IPv4 Internet host address is a number containing four bytes of data.
881 Historically these are divided into two parts, a @dfn{network number} and a
882 @dfn{local network address number} within that network. In the
883 mid-1990s classless addresses were introduced which changed this
884 behavior. Since some functions implicitly expect the old definitions,
885 we first describe the class-based network and will then describe
886 classless addresses. IPv6 uses only classless addresses and therefore
887 the following paragraphs don't apply.
889 The class-based IPv4 network number consists of the first one, two or
890 three bytes; the rest of the bytes are the local address.
892 IPv4 network numbers are registered with the Network Information Center
893 (NIC), and are divided into three classes---A, B and C. The local
894 network address numbers of individual machines are registered with the
895 administrator of the particular network.
897 Class A networks have single-byte numbers in the range 0 to 127. There
898 are only a small number of Class A networks, but they can each support a
899 very large number of hosts. Medium-sized Class B networks have two-byte
900 network numbers, with the first byte in the range 128 to 191. Class C
901 networks are the smallest; they have three-byte network numbers, with
902 the first byte in the range 192-255. Thus, the first 1, 2, or 3 bytes
903 of an Internet address specify a network. The remaining bytes of the
904 Internet address specify the address within that network.
906 The Class A network 0 is reserved for broadcast to all networks. In
907 addition, the host number 0 within each network is reserved for broadcast
908 to all hosts in that network. These uses are obsolete now but for
909 compatibility reasons you shouldn't use network 0 and host number 0.
911 The Class A network 127 is reserved for loopback; you can always use
912 the Internet address @samp{127.0.0.1} to refer to the host machine.
914 Since a single machine can be a member of multiple networks, it can
915 have multiple Internet host addresses. However, there is never
916 supposed to be more than one machine with the same host address.
918 @c !!! this section could document the IN_CLASS* macros in <netinet/in.h>.
919 @c No, it shouldn't since they're obsolete.
921 @cindex standard dot notation, for Internet addresses
922 @cindex dot notation, for Internet addresses
923 There are four forms of the @dfn{standard numbers-and-dots notation}
924 for Internet addresses:
927 @item @var{a}.@var{b}.@var{c}.@var{d}
928 This specifies all four bytes of the address individually and is the
929 commonly used representation.
931 @item @var{a}.@var{b}.@var{c}
932 The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
933 This is useful for specifying host addresses in a Class B network with
934 network address number @code{@var{a}.@var{b}}.
936 @item @var{a}.@var{b}
937 The last part of the address, @var{b}, is interpreted as a 3-byte quantity.
938 This is useful for specifying host addresses in a Class A network with
939 network address number @var{a}.
942 If only one part is given, this corresponds directly to the host address
946 Within each part of the address, the usual C conventions for specifying
947 the radix apply. In other words, a leading @samp{0x} or @samp{0X} implies
948 hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
951 @subsubheading Classless Addresses
953 IPv4 addresses (and IPv6 addresses also) are now considered classless;
954 the distinction between classes A, B and C can be ignored. Instead an
955 IPv4 host address consists of a 32-bit address and a 32-bit mask. The
956 mask contains set bits for the network part and cleared bits for the
957 host part. The network part is contiguous from the left, with the
958 remaining bits representing the host. As a consequence, the netmask can
959 simply be specified as the number of set bits. Classes A, B and C are
960 just special cases of this general rule. For example, class A addresses
961 have a netmask of @samp{255.0.0.0} or a prefix length of 8.
963 Classless IPv4 network addresses are written in numbers-and-dots
964 notation with the prefix length appended and a slash as separator. For
965 example the class A network 10 is written as @samp{10.0.0.0/8}.
967 @subsubheading IPv6 Addresses
969 IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data. A host
970 address is usually written as eight 16-bit hexadecimal numbers that are
971 separated by colons. Two colons are used to abbreviate strings of
972 consecutive zeros. For example, the IPv6 loopback address
973 @samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}.
975 @node Host Address Data Type
976 @subsubsection Host Address Data Type
978 IPv4 Internet host addresses are represented in some contexts as integers
979 (type @code{uint32_t}). In other contexts, the integer is
980 packaged inside a structure of type @code{struct in_addr}. It would
981 be better if the usage were made consistent, but it is not hard to extract
982 the integer from the structure or put the integer into a structure.
984 You will find older code that uses @code{unsigned long int} for
985 IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct
986 in_addr}. Historically @code{unsigned long int} was a 32-bit number but
987 with 64-bit machines this has changed. Using @code{unsigned long int}
988 might break the code if it is used on machines where this type doesn't
989 have 32 bits. @code{uint32_t} is specified by Unix98 and guaranteed to have
992 IPv6 Internet host addresses have 128 bits and are packaged inside a
993 structure of type @code{struct in6_addr}.
995 The following basic definitions for Internet addresses are declared in
996 the header file @file{netinet/in.h}:
999 @deftp {Data Type} {struct in_addr}
1000 @standards{BSD, netinet/in.h}
1001 This data type is used in certain contexts to contain an IPv4 Internet
1002 host address. It has just one field, named @code{s_addr}, which records
1003 the host address number as an @code{uint32_t}.
1006 @deftypevr Macro {uint32_t} INADDR_LOOPBACK
1007 @standards{BSD, netinet/in.h}
1008 You can use this constant to stand for ``the address of this machine,''
1009 instead of finding its actual address. It is the IPv4 Internet address
1010 @samp{127.0.0.1}, which is usually called @samp{localhost}. This
1011 special constant saves you the trouble of looking up the address of your
1012 own machine. Also, the system usually implements @code{INADDR_LOOPBACK}
1013 specially, avoiding any network traffic for the case of one machine
1017 @deftypevr Macro {uint32_t} INADDR_ANY
1018 @standards{BSD, netinet/in.h}
1019 You can use this constant to stand for ``any incoming address'' when
1020 binding to an address. @xref{Setting Address}. This is the usual
1021 address to give in the @code{sin_addr} member of @w{@code{struct
1022 sockaddr_in}} when you want to accept Internet connections.
1025 @deftypevr Macro {uint32_t} INADDR_BROADCAST
1026 @standards{BSD, netinet/in.h}
1027 This constant is the address you use to send a broadcast message.
1028 @c !!! broadcast needs further documented
1031 @deftypevr Macro {uint32_t} INADDR_NONE
1032 @standards{BSD, netinet/in.h}
1033 This constant is returned by some functions to indicate an error.
1036 @deftp {Data Type} {struct in6_addr}
1037 @standards{IPv6 basic API, netinet/in.h}
1038 This data type is used to store an IPv6 address. It stores 128 bits of
1039 data, which can be accessed (via a union) in a variety of ways.
1042 @deftypevr Constant {struct in6_addr} in6addr_loopback
1043 @standards{IPv6 basic API, netinet/in.h}
1044 This constant is the IPv6 address @samp{::1}, the loopback address. See
1045 above for a description of what this means. The macro
1046 @code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your
1047 own variables to this value.
1050 @deftypevr Constant {struct in6_addr} in6addr_any
1051 @standards{IPv6 basic API, netinet/in.h}
1052 This constant is the IPv6 address @samp{::}, the unspecified address. See
1053 above for a description of what this means. The macro
1054 @code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your
1055 own variables to this value.
1058 @node Host Address Functions
1059 @subsubsection Host Address Functions
1063 These additional functions for manipulating Internet addresses are
1064 declared in the header file @file{arpa/inet.h}. They represent Internet
1065 addresses in network byte order, and network numbers and
1066 local-address-within-network numbers in host byte order. @xref{Byte
1067 Order}, for an explanation of network and host byte order.
1069 @deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr})
1070 @standards{BSD, arpa/inet.h}
1071 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1072 @c inet_aton @mtslocale
1073 @c isdigit dup @mtslocale
1074 @c strtoul dup @mtslocale
1075 @c isascii dup @mtslocale
1076 @c isspace dup @mtslocale
1078 This function converts the IPv4 Internet host address @var{name}
1079 from the standard numbers-and-dots notation into binary data and stores
1080 it in the @code{struct in_addr} that @var{addr} points to.
1081 @code{inet_aton} returns nonzero if the address is valid, zero if not.
1084 @deftypefun {uint32_t} inet_addr (const char *@var{name})
1085 @standards{BSD, arpa/inet.h}
1086 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1087 @c inet_addr @mtslocale
1088 @c inet_aton dup @mtslocale
1089 This function converts the IPv4 Internet host address @var{name} from the
1090 standard numbers-and-dots notation into binary data. If the input is
1091 not valid, @code{inet_addr} returns @code{INADDR_NONE}. This is an
1092 obsolete interface to @code{inet_aton}, described immediately above. It
1093 is obsolete because @code{INADDR_NONE} is a valid address
1094 (255.255.255.255), and @code{inet_aton} provides a cleaner way to
1095 indicate error return.
1098 @deftypefun {uint32_t} inet_network (const char *@var{name})
1099 @standards{BSD, arpa/inet.h}
1100 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1101 @c inet_network @mtslocale
1102 @c isdigit dup @mtslocale
1103 @c isxdigit dup @mtslocale
1104 @c tolower dup @mtslocale
1105 @c isspace dup @mtslocale
1106 This function extracts the network number from the address @var{name},
1107 given in the standard numbers-and-dots notation. The returned address is
1108 in host order. If the input is not valid, @code{inet_network} returns
1111 The function works only with traditional IPv4 class A, B and C network
1112 types. It doesn't work with classless addresses and shouldn't be used
1116 @deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
1117 @standards{BSD, arpa/inet.h}
1118 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asurace{}}@acsafe{}}
1119 @c inet_ntoa @mtslocale @asurace
1120 @c writes to a thread-local static buffer
1121 @c snprintf @mtslocale [no @ascuheap or @acsmem]
1122 This function converts the IPv4 Internet host address @var{addr} to a
1123 string in the standard numbers-and-dots notation. The return value is
1124 a pointer into a statically-allocated buffer. Subsequent calls will
1125 overwrite the same buffer, so you should copy the string if you need
1128 In multi-threaded programs each thread has its own statically-allocated
1129 buffer. But still subsequent calls of @code{inet_ntoa} in the same
1130 thread will overwrite the result of the last call.
1132 Instead of @code{inet_ntoa} the newer function @code{inet_ntop} which is
1133 described below should be used since it handles both IPv4 and IPv6
1137 @deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local})
1138 @standards{BSD, arpa/inet.h}
1139 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1142 This function makes an IPv4 Internet host address by combining the network
1143 number @var{net} with the local-address-within-network number
1147 @deftypefun uint32_t inet_lnaof (struct in_addr @var{addr})
1148 @standards{BSD, arpa/inet.h}
1149 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1154 This function returns the local-address-within-network part of the
1155 Internet host address @var{addr}.
1157 The function works only with traditional IPv4 class A, B and C network
1158 types. It doesn't work with classless addresses and shouldn't be used
1162 @deftypefun uint32_t inet_netof (struct in_addr @var{addr})
1163 @standards{BSD, arpa/inet.h}
1164 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1169 This function returns the network number part of the Internet host
1172 The function works only with traditional IPv4 class A, B and C network
1173 types. It doesn't work with classless addresses and shouldn't be used
1177 @deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf})
1178 @standards{IPv6 basic API, arpa/inet.h}
1179 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1180 @c inet_pton @mtslocale
1183 @c inet_pton6 @mtslocale
1185 @c tolower dup @mtslocale
1187 @c inet_pton4 dup ok
1189 This function converts an Internet address (either IPv4 or IPv6) from
1190 presentation (textual) to network (binary) format. @var{af} should be
1191 either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of
1192 address being converted. @var{cp} is a pointer to the input string, and
1193 @var{buf} is a pointer to a buffer for the result. It is the caller's
1194 responsibility to make sure the buffer is large enough.
1197 @deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len})
1198 @standards{IPv6 basic API, arpa/inet.h}
1199 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1200 @c inet_ntop @mtslocale
1201 @c inet_ntop4 @mtslocale
1202 @c sprintf dup @mtslocale [no @ascuheap or @acsmem]
1204 @c inet_ntop6 @mtslocale
1206 @c inet_ntop4 dup @mtslocale
1207 @c sprintf dup @mtslocale [no @ascuheap or @acsmem]
1209 This function converts an Internet address (either IPv4 or IPv6) from
1210 network (binary) to presentation (textual) form. @var{af} should be
1211 either @code{AF_INET} or @code{AF_INET6}, as appropriate. @var{cp} is a
1212 pointer to the address to be converted. @var{buf} should be a pointer
1213 to a buffer to hold the result, and @var{len} is the length of this
1214 buffer. The return value from the function will be this buffer address.
1218 @subsubsection Host Names
1219 @cindex hosts database
1220 @cindex converting host name to address
1221 @cindex converting host address to name
1223 Besides the standard numbers-and-dots notation for Internet addresses,
1224 you can also refer to a host by a symbolic name. The advantage of a
1225 symbolic name is that it is usually easier to remember. For example,
1226 the machine with Internet address @samp{158.121.106.19} is also known as
1227 @samp{alpha.gnu.org}; and other machines in the @samp{gnu.org}
1228 domain can refer to it simply as @samp{alpha}.
1232 Internally, the system uses a database to keep track of the mapping
1233 between host names and host numbers. This database is usually either
1234 the file @file{/etc/hosts} or an equivalent provided by a name server.
1235 The functions and other symbols for accessing this database are declared
1236 in @file{netdb.h}. They are BSD features, defined unconditionally if
1237 you include @file{netdb.h}.
1239 @deftp {Data Type} {struct hostent}
1240 @standards{BSD, netdb.h}
1241 This data type is used to represent an entry in the hosts database. It
1242 has the following members:
1246 This is the ``official'' name of the host.
1248 @item char **h_aliases
1249 These are alternative names for the host, represented as a null-terminated
1252 @item int h_addrtype
1253 This is the host address type; in practice, its value is always either
1254 @code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6
1255 hosts. In principle other kinds of addresses could be represented in
1256 the database as well as Internet addresses; if this were done, you
1257 might find a value in this field other than @code{AF_INET} or
1258 @code{AF_INET6}. @xref{Socket Addresses}.
1261 This is the length, in bytes, of each address.
1263 @item char **h_addr_list
1264 This is the vector of addresses for the host. (Recall that the host
1265 might be connected to multiple networks and have different addresses on
1266 each one.) The vector is terminated by a null pointer.
1269 This is a synonym for @code{h_addr_list[0]}; in other words, it is the
1274 As far as the host database is concerned, each address is just a block
1275 of memory @code{h_length} bytes long. But in other contexts there is an
1276 implicit assumption that you can convert IPv4 addresses to a
1277 @code{struct in_addr} or an @code{uint32_t}. Host addresses in
1278 a @code{struct hostent} structure are always given in network byte
1279 order; see @ref{Byte Order}.
1281 You can use @code{gethostbyname}, @code{gethostbyname2} or
1282 @code{gethostbyaddr} to search the hosts database for information about
1283 a particular host. The information is returned in a
1284 statically-allocated structure; you must copy the information if you
1285 need to save it across calls. You can also use @code{getaddrinfo} and
1286 @code{getnameinfo} to obtain this information.
1288 @deftypefun {struct hostent *} gethostbyname (const char *@var{name})
1289 @standards{BSD, netdb.h}
1290 @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1291 @c gethostbyname @mtasurace:hostbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1292 @c libc_lock_lock dup @asulock @aculock
1293 @c malloc dup @ascuheap @acsmem
1294 @c nss_hostname_digits_dots @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1295 @c res_maybe_init(!preinit) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1296 @c res_iclose @acsuheap @acsmem @acsfd
1297 @c close_not_cancel_no_status dup @acsfd
1298 @c free dup @acsuheap @acsmem
1299 @c res_vinit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1302 @c getenv dup @mtsenv
1304 @c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
1305 @c fsetlocking dup ok [no concurrent uses]
1306 @c fgets_unlocked dup ok [no concurrent uses]
1311 @c inet_aton dup @mtslocale
1313 @c inet_pton dup @mtslocale
1314 @c malloc dup @ascuheap @acsmem
1315 @c IN6_IS_ADDR_LINKLOCAL ok
1317 @c IN6_IS_ADDR_MC_LINKLOCAL ok
1318 @c if_nametoindex dup @asulock @aculock @acsfd
1319 @c strtoul dup @mtslocale
1322 @c isascii dup @mtslocale
1323 @c isspace dup @mtslocale
1329 @c res_setoptions @mtslocale
1331 @c atoi dup @mtslocale
1332 @c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
1333 @c inet_makeaddr dup ok
1334 @c gethostname dup ok
1337 @c res_ninit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1338 @c res_vinit dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1339 @c isdigit dup @mtslocale
1340 @c isxdigit dup @mtslocale
1342 @c realloc dup @ascuheap @acsmem
1343 @c free dup @ascuheap @acsmem
1345 @c inet_aton dup @mtslocale
1346 @c inet_pton dup @mtslocale
1350 @c gethostbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1351 @c realloc dup @ascuheap @acsmem
1352 @c free dup @ascuheap @acsmem
1353 @c libc_lock_unlock dup @aculock
1355 The @code{gethostbyname} function returns information about the host
1356 named @var{name}. If the lookup fails, it returns a null pointer.
1359 @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
1360 @standards{IPv6 Basic API, netdb.h}
1361 @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname2} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1362 @c gethostbyname2 @mtasurace:hostbyname2 @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1363 @c libc_lock_lock dup @asulock @aculock
1364 @c malloc dup @ascuheap @acsmem
1365 @c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1366 @c gethostbyname2_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1367 @c realloc dup @ascuheap @acsmem
1368 @c free dup @ascuheap @acsmem
1369 @c libc_lock_unlock dup @aculock
1370 @c set_h_errno dup ok
1371 The @code{gethostbyname2} function is like @code{gethostbyname}, but
1372 allows the caller to specify the desired address family (e.g.@:
1373 @code{AF_INET} or @code{AF_INET6}) of the result.
1376 @deftypefun {struct hostent *} gethostbyaddr (const void *@var{addr}, socklen_t @var{length}, int @var{format})
1377 @standards{BSD, netdb.h}
1378 @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyaddr} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1379 @c gethostbyaddr @mtasurace:hostbyaddr @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1380 @c libc_lock_lock dup @asulock @aculock
1381 @c malloc dup @ascuheap @acsmem
1382 @c gethostbyaddr_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1383 @c realloc dup @ascuheap @acsmem
1384 @c free dup @ascuheap @acsmem
1385 @c libc_lock_unlock dup @aculock
1386 @c set_h_errno dup ok
1387 The @code{gethostbyaddr} function returns information about the host
1388 with Internet address @var{addr}. The parameter @var{addr} is not
1389 really a pointer to char - it can be a pointer to an IPv4 or an IPv6
1390 address. The @var{length} argument is the size (in bytes) of the address
1391 at @var{addr}. @var{format} specifies the address format; for an IPv4
1392 Internet address, specify a value of @code{AF_INET}; for an IPv6
1393 Internet address, use @code{AF_INET6}.
1395 If the lookup fails, @code{gethostbyaddr} returns a null pointer.
1399 If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
1400 fails, you can find out the reason by looking at the value of the
1401 variable @code{h_errno}. (It would be cleaner design for these
1402 functions to set @code{errno}, but use of @code{h_errno} is compatible
1403 with other systems.)
1405 Here are the error codes that you may find in @code{h_errno}:
1408 @item HOST_NOT_FOUND
1409 @standards{BSD, netdb.h}
1410 No such host is known in the database.
1413 @standards{BSD, netdb.h}
1414 This condition happens when the name server could not be contacted. If
1415 you try again later, you may succeed then.
1418 @standards{BSD, netdb.h}
1419 A non-recoverable error occurred.
1422 @standards{BSD, netdb.h}
1423 The host database contains an entry for the name, but it doesn't have an
1424 associated Internet address.
1427 The lookup functions above all have one thing in common: they are not
1428 reentrant and therefore unusable in multi-threaded applications.
1429 Therefore provides @theglibc{} a new set of functions which can be
1430 used in this context.
1432 @deftypefun int gethostbyname_r (const char *restrict @var{name}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop})
1433 @standards{GNU, netdb.h}
1434 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1435 @c gethostbyname_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1436 @c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1437 @c nscd_gethostbyname_r @mtsenv @ascuheap @acsfd @acsmem
1438 @c nscd_gethst_r @mtsenv @ascuheap @acsfd @acsmem
1439 @c getenv dup @mtsenv
1440 @c nscd_get_map_ref dup @ascuheap @acsfd @acsmem
1441 @c nscd_cache_search dup ok
1443 @c nscd_open_socket dup @acsfd
1446 @c close_not_cancel_no_status dup @acsfd
1447 @c nscd_drop_map_ref dup @ascuheap @acsmem
1448 @c nscd_unmap dup @ascuheap @acsmem
1449 @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1450 @c res_hconf_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called]
1451 @c res_hconf.c:do_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1453 @c getenv dup @mtsenv
1454 @c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
1455 @c fsetlocking dup ok [no concurrent uses]
1456 @c fgets_unlocked dup ok [no concurrent uses]
1458 @c res_hconf.c:parse_line @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1459 @c skip_ws dup @mtslocale
1460 @c skip_string dup @mtslocale
1461 @c strncasecmp dup @mtslocale
1463 @c asprintf dup @mtslocale @ascuheap @acsmem
1464 @c fxprintf dup @asucorrupt @aculock @acucorrupt
1465 @c free dup @ascuheap @acsmem
1466 @c arg_trimdomain_list dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1467 @c arg_spoof dup @mtslocale
1468 @c arg_bool dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1469 @c isspace dup @mtslocale
1470 @c fclose dup @ascuheap @asulock @acsmem @acsfd @aculock
1471 @c arg_spoof @mtslocale
1472 @c skip_string @mtslocale
1473 @c isspace dup @mtslocale
1474 @c strncasecmp dup @mtslocale
1475 @c arg_bool @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1476 @c strncasecmp dup @mtslocale
1477 @c asprintf dup @mtslocale @ascuheap @acsmem
1478 @c fxprintf dup @asucorrupt @aculock @acucorrupt
1479 @c free dup @ascuheap @acsmem
1480 @c arg_trimdomain_list @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1481 @c skip_string dup @mtslocale
1482 @c asprintf dup @mtslocale @ascuheap @acsmem
1483 @c fxprintf dup @asucorrupt @aculock @acucorrupt
1484 @c free dup @ascuheap @acsmem
1485 @c strndup dup @ascuheap @acsmem
1486 @c skip_ws @mtslocale
1487 @c isspace dup @mtslocale
1488 @c nss_hosts_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1489 @c nss_database_lookup dup @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock
1490 @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1491 @c *fct.l -> _nss_*_gethostbyname_r @ascuplugin
1492 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1493 @c res_hconf_reorder_addrs @asulock @ascuheap @aculock @acsmem @acsfd
1494 @c socket dup @acsfd
1495 @c libc_lock_lock dup @asulock @aculock
1496 @c ifreq @ascuheap @acsmem
1497 @c malloc dup @ascuheap @acsmem
1498 @c if_nextreq dup ok
1500 @c realloc dup @ascuheap @acsmem
1501 @c if_freereq dup @acsmem
1502 @c libc_lock_unlock dup @aculock
1504 The @code{gethostbyname_r} function returns information about the host
1505 named @var{name}. The caller must pass a pointer to an object of type
1506 @code{struct hostent} in the @var{result_buf} parameter. In addition
1507 the function may need extra buffer space and the caller must pass a
1508 pointer and the size of the buffer in the @var{buf} and @var{buflen}
1511 A pointer to the buffer, in which the result is stored, is available in
1512 @code{*@var{result}} after the function call successfully returned. The
1513 buffer passed as the @var{buf} parameter can be freed only once the caller
1514 has finished with the result hostent struct, or has copied it including all
1515 the other memory that it points to. If an error occurs or if no entry is
1516 found, the pointer @code{*@var{result}} is a null pointer. Success is
1517 signalled by a zero return value. If the function failed the return value
1518 is an error number. In addition to the errors defined for
1519 @code{gethostbyname} it can also be @code{ERANGE}. In this case the call
1520 should be repeated with a larger buffer. Additional error information is
1521 not stored in the global variable @code{h_errno} but instead in the object
1522 pointed to by @var{h_errnop}.
1524 Here's a small example:
1527 gethostname (char *host)
1529 struct hostent *hostbuf, *hp;
1535 hostbuf = malloc (sizeof (struct hostent));
1537 tmphstbuf = malloc (hstbuflen);
1539 while ((res = gethostbyname_r (host, hostbuf, tmphstbuf, hstbuflen,
1540 &hp, &herr)) == ERANGE)
1542 /* Enlarge the buffer. */
1543 tmphstbuf = reallocarray (tmphstbuf, hstbuflen, 2);
1548 /* Check for errors. */
1549 if (res || hp == NULL)
1556 @deftypefun int gethostbyname2_r (const char *@var{name}, int @var{af}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop})
1557 @standards{GNU, netdb.h}
1558 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1559 @c gethostbyname2_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1560 @c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1561 @c nscd_gethostbyname2_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
1562 @c nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
1563 @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1564 @c res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called]
1565 @c nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1566 @c *fct.l -> _nss_*_gethostbyname2_r @ascuplugin
1567 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1568 @c res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd
1569 The @code{gethostbyname2_r} function is like @code{gethostbyname_r}, but
1570 allows the caller to specify the desired address family (e.g.@:
1571 @code{AF_INET} or @code{AF_INET6}) for the result.
1574 @deftypefun int gethostbyaddr_r (const void *@var{addr}, socklen_t @var{length}, int @var{format}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop})
1575 @standards{GNU, netdb.h}
1576 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1577 @c gethostbyaddr_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1579 @c nscd_gethostbyaddr_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
1580 @c nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
1581 @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1582 @c res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called]
1583 @c nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1584 @c *fct.l -> _nss_*_gethostbyaddr_r @ascuplugin
1585 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1586 @c res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd
1587 @c res_hconf_trim_domains @mtslocale
1588 @c res_hconf_trim_domain @mtslocale
1590 @c strcasecmp dup @mtslocale
1591 The @code{gethostbyaddr_r} function returns information about the host
1592 with Internet address @var{addr}. The parameter @var{addr} is not
1593 really a pointer to char - it can be a pointer to an IPv4 or an IPv6
1594 address. The @var{length} argument is the size (in bytes) of the address
1595 at @var{addr}. @var{format} specifies the address format; for an IPv4
1596 Internet address, specify a value of @code{AF_INET}; for an IPv6
1597 Internet address, use @code{AF_INET6}.
1599 Similar to the @code{gethostbyname_r} function, the caller must provide
1600 buffers for the result and memory used internally. In case of success
1601 the function returns zero. Otherwise the value is an error number where
1602 @code{ERANGE} has the special meaning that the caller-provided buffer is
1606 You can also scan the entire hosts database one entry at a time using
1607 @code{sethostent}, @code{gethostent} and @code{endhostent}. Be careful
1608 when using these functions because they are not reentrant.
1610 @deftypefun void sethostent (int @var{stayopen})
1611 @standards{BSD, netdb.h}
1612 @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1613 @c sethostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1614 @c libc_lock_lock dup @asulock @aculock
1615 @c nss_setent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1616 @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1617 @c set_h_errno dup ok
1618 @c setup(nss_hosts_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1619 @c *lookup_fct = nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1620 @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1621 @c *fct.f @mtasurace:hostent @ascuplugin
1622 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1623 @c libc_lock_unlock dup @aculock
1624 This function opens the hosts database to begin scanning it. You can
1625 then call @code{gethostent} to read the entries.
1627 @c There was a rumor that this flag has different meaning if using the DNS,
1628 @c but it appears this description is accurate in that case also.
1629 If the @var{stayopen} argument is nonzero, this sets a flag so that
1630 subsequent calls to @code{gethostbyname} or @code{gethostbyaddr} will
1631 not close the database (as they usually would). This makes for more
1632 efficiency if you call those functions several times, by avoiding
1633 reopening the database for each call.
1636 @deftypefun {struct hostent *} gethostent (void)
1637 @standards{BSD, netdb.h}
1638 @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtasurace{:hostentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1639 @c gethostent @mtasurace:hostent @mtasurace:hostentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1640 @c libc_lock_lock dup @asulock @aculock
1641 @c nss_getent(gethostent_r) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1642 @c malloc dup @ascuheap @acsmem
1643 @c *func = gethostent_r dup @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1644 @c realloc dup @ascuheap @acsmem
1645 @c free dup @ascuheap @acsmem
1646 @c libc_lock_unlock dup @aculock
1648 @c gethostent_r @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1649 @c libc_lock_lock dup @asulock @aculock
1650 @c nss_getent_r(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1651 @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1652 @c setup(nss_hosts_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1653 @c *fct.f @mtasurace:hostent @ascuplugin
1654 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1655 @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1656 @c *sfct.f @mtasurace:hostent @ascuplugin
1657 @c libc_lock_unlock dup @aculock
1659 This function returns the next entry in the hosts database. It
1660 returns a null pointer if there are no more entries.
1663 @deftypefun void endhostent (void)
1664 @standards{BSD, netdb.h}
1665 @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1666 @c endhostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1667 @c libc_lock_lock @asulock @aculock
1668 @c nss_endent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1669 @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1670 @c setup(nss_passwd_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1671 @c *fct.f @mtasurace:hostent @ascuplugin
1672 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1673 @c libc_lock_unlock @aculock
1674 This function closes the hosts database.
1678 @subsection Internet Ports
1681 A socket address in the Internet namespace consists of a machine's
1682 Internet address plus a @dfn{port number} which distinguishes the
1683 sockets on a given machine (for a given protocol). Port numbers range
1686 Port numbers less than @code{IPPORT_RESERVED} are reserved for standard
1687 servers, such as @code{finger} and @code{telnet}. There is a database
1688 that keeps track of these, and you can use the @code{getservbyname}
1689 function to map a service name onto a port number; see @ref{Services
1692 If you write a server that is not one of the standard ones defined in
1693 the database, you must choose a port number for it. Use a number
1694 greater than @code{IPPORT_USERRESERVED}; such numbers are reserved for
1695 servers and won't ever be generated automatically by the system.
1696 Avoiding conflicts with servers being run by other users is up to you.
1698 When you use a socket without specifying its address, the system
1699 generates a port number for it. This number is between
1700 @code{IPPORT_RESERVED} and @code{IPPORT_USERRESERVED}.
1702 On the Internet, it is actually legitimate to have two different
1703 sockets with the same port number, as long as they never both try to
1704 communicate with the same socket address (host address plus port
1705 number). You shouldn't duplicate a port number except in special
1706 circumstances where a higher-level protocol requires it. Normally,
1707 the system won't let you do it; @code{bind} normally insists on
1708 distinct port numbers. To reuse a port number, you must set the
1709 socket option @code{SO_REUSEADDR}. @xref{Socket-Level Options}.
1711 @pindex netinet/in.h
1712 These macros are defined in the header file @file{netinet/in.h}.
1714 @deftypevr Macro int IPPORT_RESERVED
1715 @standards{BSD, netinet/in.h}
1716 Port numbers less than @code{IPPORT_RESERVED} are reserved for
1720 @deftypevr Macro int IPPORT_USERRESERVED
1721 @standards{BSD, netinet/in.h}
1722 Port numbers greater than or equal to @code{IPPORT_USERRESERVED} are
1723 reserved for explicit use; they will never be allocated automatically.
1726 @node Services Database
1727 @subsection The Services Database
1728 @cindex services database
1729 @cindex converting service name to port number
1730 @cindex converting port number to service name
1732 @pindex /etc/services
1733 The database that keeps track of ``well-known'' services is usually
1734 either the file @file{/etc/services} or an equivalent from a name server.
1735 You can use these utilities, declared in @file{netdb.h}, to access
1736 the services database.
1739 @deftp {Data Type} {struct servent}
1740 @standards{BSD, netdb.h}
1741 This data type holds information about entries from the services database.
1742 It has the following members:
1746 This is the ``official'' name of the service.
1748 @item char **s_aliases
1749 These are alternate names for the service, represented as an array of
1750 strings. A null pointer terminates the array.
1753 This is the port number for the service. Port numbers are given in
1754 network byte order; see @ref{Byte Order}.
1757 This is the name of the protocol to use with this service.
1758 @xref{Protocols Database}.
1762 To get information about a particular service, use the
1763 @code{getservbyname} or @code{getservbyport} functions. The information
1764 is returned in a statically-allocated structure; you must copy the
1765 information if you need to save it across calls.
1767 @deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto})
1768 @standards{BSD, netdb.h}
1769 @safety{@prelim{}@mtunsafe{@mtasurace{:servbyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1770 @c getservbyname =~ getpwuid @mtasurace:servbyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1771 @c libc_lock_lock dup @asulock @aculock
1772 @c malloc dup @ascuheap @acsmem
1773 @c getservbyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1774 @c realloc dup @ascuheap @acsmem
1775 @c free dup @ascuheap @acsmem
1776 @c libc_lock_unlock dup @aculock
1778 @c getservbyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1779 @c nscd_getservbyname_r @ascuheap @acsfd @acsmem
1780 @c nscd_getserv_r @ascuheap @acsfd @acsmem
1781 @c nscd_get_map_ref dup @ascuheap @acsfd @acsmem
1783 @c malloc dup @ascuheap @acsmem
1786 @c nscd_cache_search dup ok
1787 @c nscd_open_socket dup @acsfd
1790 @c close_not_cancel_no_status dup @acsfd
1791 @c nscd_drop_map_ref dup @ascuheap @acsmem
1792 @c nscd_unmap dup @ascuheap @acsmem
1793 @c free dup @ascuheap @acsmem
1794 @c nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1795 @c *fct.l -> _nss_*_getservbyname_r @ascuplugin
1796 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1797 The @code{getservbyname} function returns information about the
1798 service named @var{name} using protocol @var{proto}. If it can't find
1799 such a service, it returns a null pointer.
1801 This function is useful for servers as well as for clients; servers
1802 use it to determine which port they should listen on (@pxref{Listening}).
1805 @deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto})
1806 @standards{BSD, netdb.h}
1807 @safety{@prelim{}@mtunsafe{@mtasurace{:servbyport} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1808 @c getservbyport =~ getservbyname @mtasurace:servbyport @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1809 @c libc_lock_lock dup @asulock @aculock
1810 @c malloc dup @ascuheap @acsmem
1811 @c getservbyport_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1812 @c realloc dup @ascuheap @acsmem
1813 @c free dup @ascuheap @acsmem
1814 @c libc_lock_unlock dup @aculock
1816 @c getservbyport_r =~ getservbyname_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1817 @c nscd_getservbyport_r @ascuheap @acsfd @acsmem
1818 @c nscd_getserv_r dup @ascuheap @acsfd @acsmem
1819 @c nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1820 @c *fct.l -> _nss_*_getservbyport_r @ascuplugin
1821 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1822 The @code{getservbyport} function returns information about the
1823 service at port @var{port} using protocol @var{proto}. If it can't
1824 find such a service, it returns a null pointer.
1828 You can also scan the services database using @code{setservent},
1829 @code{getservent} and @code{endservent}. Be careful when using these
1830 functions because they are not reentrant.
1832 @deftypefun void setservent (int @var{stayopen})
1833 @standards{BSD, netdb.h}
1834 @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1835 @c setservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1836 @c libc_lock_lock dup @asulock @aculock
1837 @c nss_setent(nss_services_lookup2) @mtasurace:servenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1838 @c setup(nss_services_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1839 @c *lookup_fct = nss_services_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1840 @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1841 @c *fct.f @mtasurace:servent @ascuplugin
1842 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1843 @c libc_lock_unlock dup @aculock
1844 This function opens the services database to begin scanning it.
1846 If the @var{stayopen} argument is nonzero, this sets a flag so that
1847 subsequent calls to @code{getservbyname} or @code{getservbyport} will
1848 not close the database (as they usually would). This makes for more
1849 efficiency if you call those functions several times, by avoiding
1850 reopening the database for each call.
1853 @deftypefun {struct servent *} getservent (void)
1854 @standards{BSD, netdb.h}
1855 @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtasurace{:serventbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1856 @c getservent @mtasurace:servent @mtasurace:serventbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1857 @c libc_lock_lock dup @asulock @aculock
1858 @c nss_getent(getservent_r) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1859 @c malloc dup @ascuheap @acsmem
1860 @c *func = getservent_r dup @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1861 @c realloc dup @ascuheap @acsmem
1862 @c free dup @ascuheap @acsmem
1863 @c libc_lock_unlock dup @aculock
1865 @c getservent_r @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1866 @c libc_lock_lock dup @asulock @aculock
1867 @c nss_getent_r(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1868 @c setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1869 @c *fct.f @mtasurace:servent @ascuplugin
1870 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1871 @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1872 @c *sfct.f @mtasurace:servent @ascuplugin
1873 @c libc_lock_unlock dup @aculock
1874 This function returns the next entry in the services database. If
1875 there are no more entries, it returns a null pointer.
1878 @deftypefun void endservent (void)
1879 @standards{BSD, netdb.h}
1880 @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1881 @c endservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1882 @c libc_lock_lock @asulock @aculock
1883 @c nss_endent(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1884 @c setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1885 @c *fct.f @mtasurace:servent @ascuplugin
1886 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1887 @c libc_lock_unlock @aculock
1888 This function closes the services database.
1892 @subsection Byte Order Conversion
1893 @cindex byte order conversion, for socket
1894 @cindex converting byte order
1897 @cindex little-endian
1898 Different kinds of computers use different conventions for the
1899 ordering of bytes within a word. Some computers put the most
1900 significant byte within a word first (this is called ``big-endian''
1901 order), and others put it last (``little-endian'' order).
1903 @cindex network byte order
1904 So that machines with different byte order conventions can
1905 communicate, the Internet protocols specify a canonical byte order
1906 convention for data transmitted over the network. This is known
1907 as @dfn{network byte order}.
1909 When establishing an Internet socket connection, you must make sure that
1910 the data in the @code{sin_port} and @code{sin_addr} members of the
1911 @code{sockaddr_in} structure are represented in network byte order.
1912 If you are encoding integer data in the messages sent through the
1913 socket, you should convert this to network byte order too. If you don't
1914 do this, your program may fail when running on or talking to other kinds
1917 If you use @code{getservbyname} and @code{gethostbyname} or
1918 @code{inet_addr} to get the port number and host address, the values are
1919 already in network byte order, and you can copy them directly into
1920 the @code{sockaddr_in} structure.
1922 Otherwise, you have to convert the values explicitly. Use @code{htons}
1923 and @code{ntohs} to convert values for the @code{sin_port} member. Use
1924 @code{htonl} and @code{ntohl} to convert IPv4 addresses for the
1925 @code{sin_addr} member. (Remember, @code{struct in_addr} is equivalent
1926 to @code{uint32_t}.) These functions are declared in
1927 @file{netinet/in.h}.
1928 @pindex netinet/in.h
1930 @deftypefun {uint16_t} htons (uint16_t @var{hostshort})
1931 @standards{BSD, netinet/in.h}
1932 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1935 @c bswap_constant_16 ok
1937 This function converts the @code{uint16_t} integer @var{hostshort} from
1938 host byte order to network byte order.
1941 @deftypefun {uint16_t} ntohs (uint16_t @var{netshort})
1942 @standards{BSD, netinet/in.h}
1943 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1945 This function converts the @code{uint16_t} integer @var{netshort} from
1946 network byte order to host byte order.
1949 @deftypefun {uint32_t} htonl (uint32_t @var{hostlong})
1950 @standards{BSD, netinet/in.h}
1951 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1954 This function converts the @code{uint32_t} integer @var{hostlong} from
1955 host byte order to network byte order.
1957 This is used for IPv4 Internet addresses.
1960 @deftypefun {uint32_t} ntohl (uint32_t @var{netlong})
1961 @standards{BSD, netinet/in.h}
1962 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1964 This function converts the @code{uint32_t} integer @var{netlong} from
1965 network byte order to host byte order.
1967 This is used for IPv4 Internet addresses.
1970 @node Protocols Database
1971 @subsection Protocols Database
1972 @cindex protocols database
1974 The communications protocol used with a socket controls low-level
1975 details of how data are exchanged. For example, the protocol implements
1976 things like checksums to detect errors in transmissions, and routing
1977 instructions for messages. Normal user programs have little reason to
1978 mess with these details directly.
1980 @cindex TCP (Internet protocol)
1981 The default communications protocol for the Internet namespace depends on
1982 the communication style. For stream communication, the default is TCP
1983 (``transmission control protocol''). For datagram communication, the
1984 default is UDP (``user datagram protocol''). For reliable datagram
1985 communication, the default is RDP (``reliable datagram protocol'').
1986 You should nearly always use the default.
1988 @pindex /etc/protocols
1989 Internet protocols are generally specified by a name instead of a
1990 number. The network protocols that a host knows about are stored in a
1991 database. This is usually either derived from the file
1992 @file{/etc/protocols}, or it may be an equivalent provided by a name
1993 server. You look up the protocol number associated with a named
1994 protocol in the database using the @code{getprotobyname} function.
1996 Here are detailed descriptions of the utilities for accessing the
1997 protocols database. These are declared in @file{netdb.h}.
2000 @deftp {Data Type} {struct protoent}
2001 @standards{BSD, netdb.h}
2002 This data type is used to represent entries in the network protocols
2003 database. It has the following members:
2007 This is the official name of the protocol.
2009 @item char **p_aliases
2010 These are alternate names for the protocol, specified as an array of
2011 strings. The last element of the array is a null pointer.
2014 This is the protocol number (in host byte order); use this member as the
2015 @var{protocol} argument to @code{socket}.
2019 You can use @code{getprotobyname} and @code{getprotobynumber} to search
2020 the protocols database for a specific protocol. The information is
2021 returned in a statically-allocated structure; you must copy the
2022 information if you need to save it across calls.
2024 @deftypefun {struct protoent *} getprotobyname (const char *@var{name})
2025 @standards{BSD, netdb.h}
2026 @safety{@prelim{}@mtunsafe{@mtasurace{:protobyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
2027 @c getprotobyname =~ getpwuid @mtasurace:protobyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2028 @c libc_lock_lock dup @asulock @aculock
2029 @c malloc dup @ascuheap @acsmem
2030 @c getprotobyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2031 @c realloc dup @ascuheap @acsmem
2032 @c free dup @ascuheap @acsmem
2033 @c libc_lock_unlock dup @aculock
2035 @c getprotobyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2037 @c nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2038 @c *fct.l -> _nss_*_getprotobyname_r @ascuplugin
2039 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2040 The @code{getprotobyname} function returns information about the
2041 network protocol named @var{name}. If there is no such protocol, it
2042 returns a null pointer.
2045 @deftypefun {struct protoent *} getprotobynumber (int @var{protocol})
2046 @standards{BSD, netdb.h}
2047 @safety{@prelim{}@mtunsafe{@mtasurace{:protobynumber} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
2048 @c getprotobynumber =~ getpwuid @mtasurace:protobynumber @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2049 @c libc_lock_lock dup @asulock @aculock
2050 @c malloc dup @ascuheap @acsmem
2051 @c getprotobynumber_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2052 @c realloc dup @ascuheap @acsmem
2053 @c free dup @ascuheap @acsmem
2054 @c libc_lock_unlock dup @aculock
2056 @c getprotobynumber_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2058 @c nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2059 @c *fct.l -> _nss_*_getprotobynumber_r @ascuplugin
2060 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2061 The @code{getprotobynumber} function returns information about the
2062 network protocol with number @var{protocol}. If there is no such
2063 protocol, it returns a null pointer.
2066 You can also scan the whole protocols database one protocol at a time by
2067 using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}.
2068 Be careful when using these functions because they are not reentrant.
2070 @deftypefun void setprotoent (int @var{stayopen})
2071 @standards{BSD, netdb.h}
2072 @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
2073 @c setprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2074 @c libc_lock_lock dup @asulock @aculock
2075 @c nss_setent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2076 @c setup(nss_protocols_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2077 @c *lookup_fct = nss_protocols_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2078 @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2079 @c *fct.f @mtasurace:protoent @ascuplugin
2080 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2081 @c libc_lock_unlock dup @aculock
2082 This function opens the protocols database to begin scanning it.
2084 If the @var{stayopen} argument is nonzero, this sets a flag so that
2085 subsequent calls to @code{getprotobyname} or @code{getprotobynumber} will
2086 not close the database (as they usually would). This makes for more
2087 efficiency if you call those functions several times, by avoiding
2088 reopening the database for each call.
2091 @deftypefun {struct protoent *} getprotoent (void)
2092 @standards{BSD, netdb.h}
2093 @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtasurace{:protoentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
2094 @c getprotoent @mtasurace:protoent @mtasurace:protoentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2095 @c libc_lock_lock dup @asulock @aculock
2096 @c nss_getent(getprotoent_r) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2097 @c malloc dup @ascuheap @acsmem
2098 @c *func = getprotoent_r dup @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2099 @c realloc dup @ascuheap @acsmem
2100 @c free dup @ascuheap @acsmem
2101 @c libc_lock_unlock dup @aculock
2103 @c getprotoent_r @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2104 @c libc_lock_lock dup @asulock @aculock
2105 @c nss_getent_r(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2106 @c setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2107 @c *fct.f @mtasurace:servent @ascuplugin
2108 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2109 @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2110 @c *sfct.f @mtasurace:protoent @ascuplugin
2111 @c libc_lock_unlock dup @aculock
2112 This function returns the next entry in the protocols database. It
2113 returns a null pointer if there are no more entries.
2116 @deftypefun void endprotoent (void)
2117 @standards{BSD, netdb.h}
2118 @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
2119 @c endprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2120 @c libc_lock_lock @asulock @aculock
2121 @c nss_endent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2122 @c setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2123 @c *fct.f @mtasurace:protoent @ascuplugin
2124 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2125 @c libc_lock_unlock @aculock
2126 This function closes the protocols database.
2130 @subsection Internet Socket Example
2132 Here is an example showing how to create and name a socket in the
2133 Internet namespace. The newly created socket exists on the machine that
2134 the program is running on. Rather than finding and using the machine's
2135 Internet address, this example specifies @code{INADDR_ANY} as the host
2136 address; the system replaces that with the machine's actual address.
2139 @include mkisock.c.texi
2142 Here is another example, showing how you can fill in a @code{sockaddr_in}
2143 structure, given a host name string and a port number:
2146 @include isockad.c.texi
2149 @node Misc Namespaces
2150 @section Other Namespaces
2157 Certain other namespaces and associated protocol families are supported
2158 but not documented yet because they are not often used. @code{PF_NS}
2159 refers to the Xerox Network Software protocols. @code{PF_ISO} stands
2160 for Open Systems Interconnect. @code{PF_CCITT} refers to protocols from
2161 CCITT. @file{socket.h} defines these symbols and others naming protocols
2162 not actually implemented.
2164 @code{PF_IMPLINK} is used for communicating between hosts and Internet
2165 Message Processors. For information on this and @code{PF_ROUTE}, an
2166 occasionally-used local area routing protocol, see the GNU Hurd Manual
2167 (to appear in the future).
2169 @node Open/Close Sockets
2170 @section Opening and Closing Sockets
2172 This section describes the actual library functions for opening and
2173 closing sockets. The same functions work for all namespaces and
2177 * Creating a Socket:: How to open a socket.
2178 * Closing a Socket:: How to close a socket.
2179 * Socket Pairs:: These are created like pipes.
2182 @node Creating a Socket
2183 @subsection Creating a Socket
2184 @cindex creating a socket
2185 @cindex socket, creating
2186 @cindex opening a socket
2188 The primitive for creating a socket is the @code{socket} function,
2189 declared in @file{sys/socket.h}.
2190 @pindex sys/socket.h
2192 @deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol})
2193 @standards{BSD, sys/socket.h}
2194 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
2195 This function creates a socket and specifies communication style
2196 @var{style}, which should be one of the socket styles listed in
2197 @ref{Communication Styles}. The @var{namespace} argument specifies
2198 the namespace; it must be @code{PF_LOCAL} (@pxref{Local Namespace}) or
2199 @code{PF_INET} (@pxref{Internet Namespace}). @var{protocol}
2200 designates the specific protocol (@pxref{Socket Concepts}); zero is
2201 usually right for @var{protocol}.
2203 The return value from @code{socket} is the file descriptor for the new
2204 socket, or @code{-1} in case of error. The following @code{errno} error
2205 conditions are defined for this function:
2208 @item EPROTONOSUPPORT
2209 The @var{protocol} or @var{style} is not supported by the
2210 @var{namespace} specified.
2213 The process already has too many file descriptors open.
2216 The system already has too many file descriptors open.
2219 The process does not have the privilege to create a socket of the specified
2220 @var{style} or @var{protocol}.
2223 The system ran out of internal buffer space.
2226 The file descriptor returned by the @code{socket} function supports both
2227 read and write operations. However, like pipes, sockets do not support file
2228 positioning operations.
2231 For examples of how to call the @code{socket} function,
2232 see @ref{Local Socket Example}, or @ref{Inet Example}.
2235 @node Closing a Socket
2236 @subsection Closing a Socket
2237 @cindex socket, closing
2238 @cindex closing a socket
2239 @cindex shutting down a socket
2240 @cindex socket shutdown
2242 When you have finished using a socket, you can simply close its
2243 file descriptor with @code{close}; see @ref{Opening and Closing Files}.
2244 If there is still data waiting to be transmitted over the connection,
2245 normally @code{close} tries to complete this transmission. You
2246 can control this behavior using the @code{SO_LINGER} socket option to
2247 specify a timeout period; see @ref{Socket Options}.
2249 @pindex sys/socket.h
2250 You can also shut down only reception or transmission on a
2251 connection by calling @code{shutdown}, which is declared in
2252 @file{sys/socket.h}.
2254 @deftypefun int shutdown (int @var{socket}, int @var{how})
2255 @standards{BSD, sys/socket.h}
2256 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2257 The @code{shutdown} function shuts down the connection of socket
2258 @var{socket}. The argument @var{how} specifies what action to
2263 Stop receiving data for this socket. If further data arrives,
2267 Stop trying to transmit data from this socket. Discard any data
2268 waiting to be sent. Stop looking for acknowledgement of data already
2269 sent; don't retransmit it if it is lost.
2272 Stop both reception and transmission.
2275 The return value is @code{0} on success and @code{-1} on failure. The
2276 following @code{errno} error conditions are defined for this function:
2280 @var{socket} is not a valid file descriptor.
2283 @var{socket} is not a socket.
2286 @var{socket} is not connected.
2291 @subsection Socket Pairs
2292 @cindex creating a socket pair
2294 @cindex opening a socket pair
2296 @pindex sys/socket.h
2297 A @dfn{socket pair} consists of a pair of connected (but unnamed)
2298 sockets. It is very similar to a pipe and is used in much the same
2299 way. Socket pairs are created with the @code{socketpair} function,
2300 declared in @file{sys/socket.h}. A socket pair is much like a pipe; the
2301 main difference is that the socket pair is bidirectional, whereas the
2302 pipe has one input-only end and one output-only end (@pxref{Pipes and
2305 @deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]})
2306 @standards{BSD, sys/socket.h}
2307 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
2308 This function creates a socket pair, returning the file descriptors in
2309 @code{@var{filedes}[0]} and @code{@var{filedes}[1]}. The socket pair
2310 is a full-duplex communications channel, so that both reading and writing
2311 may be performed at either end.
2313 The @var{namespace}, @var{style} and @var{protocol} arguments are
2314 interpreted as for the @code{socket} function. @var{style} should be
2315 one of the communication styles listed in @ref{Communication Styles}.
2316 The @var{namespace} argument specifies the namespace, which must be
2317 @code{AF_LOCAL} (@pxref{Local Namespace}); @var{protocol} specifies the
2318 communications protocol, but zero is the only meaningful value.
2320 If @var{style} specifies a connectionless communication style, then
2321 the two sockets you get are not @emph{connected}, strictly speaking,
2322 but each of them knows the other as the default destination address,
2323 so they can send packets to each other.
2325 The @code{socketpair} function returns @code{0} on success and @code{-1}
2326 on failure. The following @code{errno} error conditions are defined
2331 The process has too many file descriptors open.
2334 The specified namespace is not supported.
2336 @item EPROTONOSUPPORT
2337 The specified protocol is not supported.
2340 The specified protocol does not support the creation of socket pairs.
2345 @section Using Sockets with Connections
2350 The most common communication styles involve making a connection to a
2351 particular other socket, and then exchanging data with that socket
2352 over and over. Making a connection is asymmetric; one side (the
2353 @dfn{client}) acts to request a connection, while the other side (the
2354 @dfn{server}) makes a socket and waits for the connection request.
2359 @ref{Connecting}, describes what the client program must do to
2360 initiate a connection with a server.
2363 @ref{Listening} and @ref{Accepting Connections} describe what the
2364 server program must do to wait for and act upon connection requests
2368 @ref{Transferring Data}, describes how data are transferred through the
2374 * Connecting:: What the client program must do.
2375 * Listening:: How a server program waits for requests.
2376 * Accepting Connections:: What the server does when it gets a request.
2377 * Who is Connected:: Getting the address of the
2378 other side of a connection.
2379 * Transferring Data:: How to send and receive data.
2380 * Byte Stream Example:: An example program: a client for communicating
2381 over a byte stream socket in the Internet namespace.
2382 * Server Example:: A corresponding server program.
2383 * Out-of-Band Data:: This is an advanced feature.
2387 @subsection Making a Connection
2388 @cindex connecting a socket
2389 @cindex socket, connecting
2390 @cindex socket, initiating a connection
2391 @cindex socket, client actions
2393 In making a connection, the client makes a connection while the server
2394 waits for and accepts the connection. Here we discuss what the client
2395 program must do with the @code{connect} function, which is declared in
2396 @file{sys/socket.h}.
2398 @deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
2399 @standards{BSD, sys/socket.h}
2400 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2401 The @code{connect} function initiates a connection from the socket
2402 with file descriptor @var{socket} to the socket whose address is
2403 specified by the @var{addr} and @var{length} arguments. (This socket
2404 is typically on another machine, and it must be already set up as a
2405 server.) @xref{Socket Addresses}, for information about how these
2406 arguments are interpreted.
2408 Normally, @code{connect} waits until the server responds to the request
2409 before it returns. You can set nonblocking mode on the socket
2410 @var{socket} to make @code{connect} return immediately without waiting
2411 for the response. @xref{File Status Flags}, for information about
2413 @c !!! how do you tell when it has finished connecting? I suspect the
2414 @c way you do it is select for writing.
2416 The normal return value from @code{connect} is @code{0}. If an error
2417 occurs, @code{connect} returns @code{-1}. The following @code{errno}
2418 error conditions are defined for this function:
2422 The socket @var{socket} is not a valid file descriptor.
2425 File descriptor @var{socket} is not a socket.
2428 The specified address is not available on the remote machine.
2431 The namespace of the @var{addr} is not supported by this socket.
2434 The socket @var{socket} is already connected.
2437 The attempt to establish the connection timed out.
2440 The server has actively refused to establish the connection.
2443 The network of the given @var{addr} isn't reachable from this host.
2446 The socket address of the given @var{addr} is already in use.
2449 The socket @var{socket} is non-blocking and the connection could not be
2450 established immediately. You can determine when the connection is
2451 completely established with @code{select}; @pxref{Waiting for I/O}.
2452 Another @code{connect} call on the same socket, before the connection is
2453 completely established, will fail with @code{EALREADY}.
2456 The socket @var{socket} is non-blocking and already has a pending
2457 connection in progress (see @code{EINPROGRESS} above).
2460 This function is defined as a cancellation point in multi-threaded
2461 programs, so one has to be prepared for this and make sure that
2462 allocated resources (like memory, file descriptors, semaphores or
2463 whatever) are freed even if the thread is canceled.
2464 @c @xref{pthread_cleanup_push}, for a method how to do this.
2468 @subsection Listening for Connections
2469 @cindex listening (sockets)
2470 @cindex sockets, server actions
2471 @cindex sockets, listening
2473 Now let us consider what the server process must do to accept
2474 connections on a socket. First it must use the @code{listen} function
2475 to enable connection requests on the socket, and then accept each
2476 incoming connection with a call to @code{accept} (@pxref{Accepting
2477 Connections}). Once connection requests are enabled on a server socket,
2478 the @code{select} function reports when the socket has a connection
2479 ready to be accepted (@pxref{Waiting for I/O}).
2481 The @code{listen} function is not allowed for sockets using
2482 connectionless communication styles.
2484 You can write a network server that does not even start running until a
2485 connection to it is requested. @xref{Inetd Servers}.
2487 In the Internet namespace, there are no special protection mechanisms
2488 for controlling access to a port; any process on any machine
2489 can make a connection to your server. If you want to restrict access to
2490 your server, make it examine the addresses associated with connection
2491 requests or implement some other handshaking or identification
2494 In the local namespace, the ordinary file protection bits control who has
2495 access to connect to the socket.
2497 @deftypefun int listen (int @var{socket}, int @var{n})
2498 @standards{BSD, sys/socket.h}
2499 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
2500 The @code{listen} function enables the socket @var{socket} to accept
2501 connections, thus making it a server socket.
2503 The argument @var{n} specifies the length of the queue for pending
2504 connections. When the queue fills, new clients attempting to connect
2505 fail with @code{ECONNREFUSED} until the server calls @code{accept} to
2506 accept a connection from the queue.
2508 The @code{listen} function returns @code{0} on success and @code{-1}
2509 on failure. The following @code{errno} error conditions are defined
2514 The argument @var{socket} is not a valid file descriptor.
2517 The argument @var{socket} is not a socket.
2520 The socket @var{socket} does not support this operation.
2524 @node Accepting Connections
2525 @subsection Accepting Connections
2526 @cindex sockets, accepting connections
2527 @cindex accepting connections
2529 When a server receives a connection request, it can complete the
2530 connection by accepting the request. Use the function @code{accept}
2533 A socket that has been established as a server can accept connection
2534 requests from multiple clients. The server's original socket
2535 @emph{does not become part of the connection}; instead, @code{accept}
2536 makes a new socket which participates in the connection.
2537 @code{accept} returns the descriptor for this socket. The server's
2538 original socket remains available for listening for further connection
2541 The number of pending connection requests on a server socket is finite.
2542 If connection requests arrive from clients faster than the server can
2543 act upon them, the queue can fill up and additional requests are refused
2544 with an @code{ECONNREFUSED} error. You can specify the maximum length of
2545 this queue as an argument to the @code{listen} function, although the
2546 system may also impose its own internal limit on the length of this
2549 @deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length_ptr})
2550 @standards{BSD, sys/socket.h}
2551 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
2552 This function is used to accept a connection request on the server
2553 socket @var{socket}.
2555 The @code{accept} function waits if there are no connections pending,
2556 unless the socket @var{socket} has nonblocking mode set. (You can use
2557 @code{select} to wait for a pending connection, with a nonblocking
2558 socket.) @xref{File Status Flags}, for information about nonblocking
2561 The @var{addr} and @var{length-ptr} arguments are used to return
2562 information about the name of the client socket that initiated the
2563 connection. @xref{Socket Addresses}, for information about the format
2566 Accepting a connection does not make @var{socket} part of the
2567 connection. Instead, it creates a new socket which becomes
2568 connected. The normal return value of @code{accept} is the file
2569 descriptor for the new socket.
2571 After @code{accept}, the original socket @var{socket} remains open and
2572 unconnected, and continues listening until you close it. You can
2573 accept further connections with @var{socket} by calling @code{accept}
2576 If an error occurs, @code{accept} returns @code{-1}. The following
2577 @code{errno} error conditions are defined for this function:
2581 The @var{socket} argument is not a valid file descriptor.
2584 The descriptor @var{socket} argument is not a socket.
2587 The descriptor @var{socket} does not support this operation.
2590 @var{socket} has nonblocking mode set, and there are no pending
2591 connections immediately available.
2594 This function is defined as a cancellation point in multi-threaded
2595 programs, so one has to be prepared for this and make sure that
2596 allocated resources (like memory, file descriptors, semaphores or
2597 whatever) are freed even if the thread is canceled.
2598 @c @xref{pthread_cleanup_push}, for a method how to do this.
2601 The @code{accept} function is not allowed for sockets using
2602 connectionless communication styles.
2604 @node Who is Connected
2605 @subsection Who is Connected to Me?
2607 @deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
2608 @standards{BSD, sys/socket.h}
2609 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2610 The @code{getpeername} function returns the address of the socket that
2611 @var{socket} is connected to; it stores the address in the memory space
2612 specified by @var{addr} and @var{length-ptr}. It stores the length of
2613 the address in @code{*@var{length-ptr}}.
2615 @xref{Socket Addresses}, for information about the format of the
2616 address. In some operating systems, @code{getpeername} works only for
2617 sockets in the Internet domain.
2619 The return value is @code{0} on success and @code{-1} on error. The
2620 following @code{errno} error conditions are defined for this function:
2624 The argument @var{socket} is not a valid file descriptor.
2627 The descriptor @var{socket} is not a socket.
2630 The socket @var{socket} is not connected.
2633 There are not enough internal buffers available.
2638 @node Transferring Data
2639 @subsection Transferring Data
2640 @cindex reading from a socket
2641 @cindex writing to a socket
2643 Once a socket has been connected to a peer, you can use the ordinary
2644 @code{read} and @code{write} operations (@pxref{I/O Primitives}) to
2645 transfer data. A socket is a two-way communications channel, so read
2646 and write operations can be performed at either end.
2648 There are also some I/O modes that are specific to socket operations.
2649 In order to specify these modes, you must use the @code{recv} and
2650 @code{send} functions instead of the more generic @code{read} and
2651 @code{write} functions. The @code{recv} and @code{send} functions take
2652 an additional argument which you can use to specify various flags to
2653 control special I/O modes. For example, you can specify the
2654 @code{MSG_OOB} flag to read or write out-of-band data, the
2655 @code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag
2656 to control inclusion of routing information on output.
2659 * Sending Data:: Sending data with @code{send}.
2660 * Receiving Data:: Reading data with @code{recv}.
2661 * Socket Data Options:: Using @code{send} and @code{recv}.
2665 @subsubsection Sending Data
2667 @pindex sys/socket.h
2668 The @code{send} function is declared in the header file
2669 @file{sys/socket.h}. If your @var{flags} argument is zero, you can just
2670 as well use @code{write} instead of @code{send}; see @ref{I/O
2671 Primitives}. If the socket was connected but the connection has broken,
2672 you get a @code{SIGPIPE} signal for any use of @code{send} or
2673 @code{write} (@pxref{Miscellaneous Signals}).
2675 @deftypefun ssize_t send (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags})
2676 @standards{BSD, sys/socket.h}
2677 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2678 The @code{send} function is like @code{write}, but with the additional
2679 flags @var{flags}. The possible values of @var{flags} are described
2680 in @ref{Socket Data Options}.
2682 This function returns the number of bytes transmitted, or @code{-1} on
2683 failure. If the socket is nonblocking, then @code{send} (like
2684 @code{write}) can return after sending just part of the data.
2685 @xref{File Status Flags}, for information about nonblocking mode.
2687 Note, however, that a successful return value merely indicates that
2688 the message has been sent without error, not necessarily that it has
2689 been received without error.
2691 The following @code{errno} error conditions are defined for this function:
2695 The @var{socket} argument is not a valid file descriptor.
2698 The operation was interrupted by a signal before any data was sent.
2699 @xref{Interrupted Primitives}.
2702 The descriptor @var{socket} is not a socket.
2705 The socket type requires that the message be sent atomically, but the
2706 message is too large for this to be possible.
2709 Nonblocking mode has been set on the socket, and the write operation
2710 would block. (Normally @code{send} blocks until the operation can be
2714 There is not enough internal buffer space available.
2717 You never connected this socket.
2720 This socket was connected but the connection is now broken. In this
2721 case, @code{send} generates a @code{SIGPIPE} signal first; if that
2722 signal is ignored or blocked, or if its handler returns, then
2723 @code{send} fails with @code{EPIPE}.
2726 This function is defined as a cancellation point in multi-threaded
2727 programs, so one has to be prepared for this and make sure that
2728 allocated resources (like memory, file descriptors, semaphores or
2729 whatever) are freed even if the thread is canceled.
2730 @c @xref{pthread_cleanup_push}, for a method how to do this.
2733 @node Receiving Data
2734 @subsubsection Receiving Data
2736 @pindex sys/socket.h
2737 The @code{recv} function is declared in the header file
2738 @file{sys/socket.h}. If your @var{flags} argument is zero, you can
2739 just as well use @code{read} instead of @code{recv}; see @ref{I/O
2742 @deftypefun ssize_t recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags})
2743 @standards{BSD, sys/socket.h}
2744 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2745 The @code{recv} function is like @code{read}, but with the additional
2746 flags @var{flags}. The possible values of @var{flags} are described
2747 in @ref{Socket Data Options}.
2749 If nonblocking mode is set for @var{socket}, and no data are available to
2750 be read, @code{recv} fails immediately rather than waiting. @xref{File
2751 Status Flags}, for information about nonblocking mode.
2753 This function returns the number of bytes received, or @code{-1} on failure.
2754 The following @code{errno} error conditions are defined for this function:
2758 The @var{socket} argument is not a valid file descriptor.
2761 The descriptor @var{socket} is not a socket.
2764 Nonblocking mode has been set on the socket, and the read operation
2765 would block. (Normally, @code{recv} blocks until there is input
2766 available to be read.)
2769 The operation was interrupted by a signal before any data was read.
2770 @xref{Interrupted Primitives}.
2773 You never connected this socket.
2776 This function is defined as a cancellation point in multi-threaded
2777 programs, so one has to be prepared for this and make sure that
2778 allocated resources (like memory, file descriptors, semaphores or
2779 whatever) are freed even if the thread is canceled.
2780 @c @xref{pthread_cleanup_push}, for a method how to do this.
2783 @node Socket Data Options
2784 @subsubsection Socket Data Options
2786 @pindex sys/socket.h
2787 The @var{flags} argument to @code{send} and @code{recv} is a bit
2788 mask. You can bitwise-OR the values of the following macros together
2789 to obtain a value for this argument. All are defined in the header
2790 file @file{sys/socket.h}.
2792 @deftypevr Macro int MSG_OOB
2793 @standards{BSD, sys/socket.h}
2794 Send or receive out-of-band data. @xref{Out-of-Band Data}.
2797 @deftypevr Macro int MSG_PEEK
2798 @standards{BSD, sys/socket.h}
2799 Look at the data but don't remove it from the input queue. This is
2800 only meaningful with input functions such as @code{recv}, not with
2804 @deftypevr Macro int MSG_DONTROUTE
2805 @standards{BSD, sys/socket.h}
2806 Don't include routing information in the message. This is only
2807 meaningful with output operations, and is usually only of interest for
2808 diagnostic or routing programs. We don't try to explain it here.
2811 @node Byte Stream Example
2812 @subsection Byte Stream Socket Example
2814 Here is an example client program that makes a connection for a byte
2815 stream socket in the Internet namespace. It doesn't do anything
2816 particularly interesting once it has connected to the server; it just
2817 sends a text string to the server and exits.
2819 This program uses @code{init_sockaddr} to set up the socket address; see
2823 @include inetcli.c.texi
2826 @node Server Example
2827 @subsection Byte Stream Connection Server Example
2829 The server end is much more complicated. Since we want to allow
2830 multiple clients to be connected to the server at the same time, it
2831 would be incorrect to wait for input from a single client by simply
2832 calling @code{read} or @code{recv}. Instead, the right thing to do is
2833 to use @code{select} (@pxref{Waiting for I/O}) to wait for input on
2834 all of the open sockets. This also allows the server to deal with
2835 additional connection requests.
2837 This particular server doesn't do anything interesting once it has
2838 gotten a message from a client. It does close the socket for that
2839 client when it detects an end-of-file condition (resulting from the
2840 client shutting down its end of the connection).
2842 This program uses @code{make_socket} to set up the socket address; see
2846 @include inetsrv.c.texi
2849 @node Out-of-Band Data
2850 @subsection Out-of-Band Data
2852 @cindex out-of-band data
2853 @cindex high-priority data
2854 Streams with connections permit @dfn{out-of-band} data that is
2855 delivered with higher priority than ordinary data. Typically the
2856 reason for sending out-of-band data is to send notice of an
2857 exceptional condition. To send out-of-band data use
2858 @code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending
2861 Out-of-band data are received with higher priority because the
2862 receiving process need not read it in sequence; to read the next
2863 available out-of-band data, use @code{recv} with the @code{MSG_OOB}
2864 flag (@pxref{Receiving Data}). Ordinary read operations do not read
2865 out-of-band data; they read only ordinary data.
2867 @cindex urgent socket condition
2868 When a socket finds that out-of-band data are on their way, it sends a
2869 @code{SIGURG} signal to the owner process or process group of the
2870 socket. You can specify the owner using the @code{F_SETOWN} command
2871 to the @code{fcntl} function; see @ref{Interrupt Input}. You must
2872 also establish a handler for this signal, as described in @ref{Signal
2873 Handling}, in order to take appropriate action such as reading the
2876 Alternatively, you can test for pending out-of-band data, or wait
2877 until there is out-of-band data, using the @code{select} function; it
2878 can wait for an exceptional condition on the socket. @xref{Waiting
2879 for I/O}, for more information about @code{select}.
2881 Notification of out-of-band data (whether with @code{SIGURG} or with
2882 @code{select}) indicates that out-of-band data are on the way; the data
2883 may not actually arrive until later. If you try to read the
2884 out-of-band data before it arrives, @code{recv} fails with an
2885 @code{EWOULDBLOCK} error.
2887 Sending out-of-band data automatically places a ``mark'' in the stream
2888 of ordinary data, showing where in the sequence the out-of-band data
2889 ``would have been''. This is useful when the meaning of out-of-band
2890 data is ``cancel everything sent so far''. Here is how you can test,
2891 in the receiving process, whether any ordinary data was sent before
2895 success = ioctl (socket, SIOCATMARK, &atmark);
2898 The @code{integer} variable @var{atmark} is set to a nonzero value if
2899 the socket's read pointer has reached the ``mark''.
2901 @c Posix 1.g specifies sockatmark for this ioctl. sockatmark is not
2904 Here's a function to discard any ordinary data preceding the
2909 discard_until_mark (int socket)
2913 /* @r{This is not an arbitrary limit; any size will do.} */
2915 int atmark, success;
2917 /* @r{If we have reached the mark, return.} */
2918 success = ioctl (socket, SIOCATMARK, &atmark);
2924 /* @r{Otherwise, read a bunch of ordinary data and discard it.}
2925 @r{This is guaranteed not to read past the mark}
2926 @r{if it starts before the mark.} */
2927 success = read (socket, buffer, sizeof buffer);
2934 If you don't want to discard the ordinary data preceding the mark, you
2935 may need to read some of it anyway, to make room in internal system
2936 buffers for the out-of-band data. If you try to read out-of-band data
2937 and get an @code{EWOULDBLOCK} error, try reading some ordinary data
2938 (saving it so that you can use it when you want it) and see if that
2939 makes room. Here is an example:
2946 struct buffer *next;
2949 /* @r{Read the out-of-band data from SOCKET and return it}
2950 @r{as a `struct buffer', which records the address of the data}
2953 @r{It may be necessary to read some ordinary data}
2954 @r{in order to make room for the out-of-band data.}
2955 @r{If so, the ordinary data are saved as a chain of buffers}
2956 @r{found in the `next' field of the value.} */
2959 read_oob (int socket)
2961 struct buffer *tail = 0;
2962 struct buffer *list = 0;
2966 /* @r{This is an arbitrary limit.}
2967 @r{Does anyone know how to do this without a limit?} */
2969 char *buf = (char *) xmalloc (BUF_SZ);
2973 /* @r{Try again to read the out-of-band data.} */
2974 success = recv (socket, buf, BUF_SZ, MSG_OOB);
2977 /* @r{We got it, so return it.} */
2979 = (struct buffer *) xmalloc (sizeof (struct buffer));
2981 link->size = success;
2986 /* @r{If we fail, see if we are at the mark.} */
2987 success = ioctl (socket, SIOCATMARK, &atmark);
2992 /* @r{At the mark; skipping past more ordinary data cannot help.}
2993 @r{So just wait a while.} */
2998 /* @r{Otherwise, read a bunch of ordinary data and save it.}
2999 @r{This is guaranteed not to read past the mark}
3000 @r{if it starts before the mark.} */
3001 success = read (socket, buf, BUF_SZ);
3005 /* @r{Save this data in the buffer list.} */
3008 = (struct buffer *) xmalloc (sizeof (struct buffer));
3010 link->size = success;
3012 /* @r{Add the new link to the end of the list.} */
3024 @section Datagram Socket Operations
3026 @cindex datagram socket
3027 This section describes how to use communication styles that don't use
3028 connections (styles @code{SOCK_DGRAM} and @code{SOCK_RDM}). Using
3029 these styles, you group data into packets and each packet is an
3030 independent communication. You specify the destination for each
3031 packet individually.
3033 Datagram packets are like letters: you send each one independently
3034 with its own destination address, and they may arrive in the wrong
3035 order or not at all.
3037 The @code{listen} and @code{accept} functions are not allowed for
3038 sockets using connectionless communication styles.
3041 * Sending Datagrams:: Sending packets on a datagram socket.
3042 * Receiving Datagrams:: Receiving packets on a datagram socket.
3043 * Datagram Example:: An example program: packets sent over a
3044 datagram socket in the local namespace.
3045 * Example Receiver:: Another program, that receives those packets.
3048 @node Sending Datagrams
3049 @subsection Sending Datagrams
3050 @cindex sending a datagram
3051 @cindex transmitting datagrams
3052 @cindex datagrams, transmitting
3054 @pindex sys/socket.h
3055 The normal way of sending data on a datagram socket is by using the
3056 @code{sendto} function, declared in @file{sys/socket.h}.
3058 You can call @code{connect} on a datagram socket, but this only
3059 specifies a default destination for further data transmission on the
3060 socket. When a socket has a default destination you can use
3061 @code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O
3062 Primitives}) to send a packet there. You can cancel the default
3063 destination by calling @code{connect} using an address format of
3064 @code{AF_UNSPEC} in the @var{addr} argument. @xref{Connecting}, for
3065 more information about the @code{connect} function.
3067 @deftypefun ssize_t sendto (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length})
3068 @standards{BSD, sys/socket.h}
3069 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3070 The @code{sendto} function transmits the data in the @var{buffer}
3071 through the socket @var{socket} to the destination address specified
3072 by the @var{addr} and @var{length} arguments. The @var{size} argument
3073 specifies the number of bytes to be transmitted.
3075 The @var{flags} are interpreted the same way as for @code{send}; see
3076 @ref{Socket Data Options}.
3078 The return value and error conditions are also the same as for
3079 @code{send}, but you cannot rely on the system to detect errors and
3080 report them; the most common error is that the packet is lost or there
3081 is no-one at the specified address to receive it, and the operating
3082 system on your machine usually does not know this.
3084 It is also possible for one call to @code{sendto} to report an error
3085 owing to a problem related to a previous call.
3087 This function is defined as a cancellation point in multi-threaded
3088 programs, so one has to be prepared for this and make sure that
3089 allocated resources (like memory, file descriptors, semaphores or
3090 whatever) are freed even if the thread is canceled.
3091 @c @xref{pthread_cleanup_push}, for a method how to do this.
3094 @node Receiving Datagrams
3095 @subsection Receiving Datagrams
3096 @cindex receiving datagrams
3098 The @code{recvfrom} function reads a packet from a datagram socket and
3099 also tells you where it was sent from. This function is declared in
3100 @file{sys/socket.h}.
3102 @deftypefun ssize_t recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
3103 @standards{BSD, sys/socket.h}
3104 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3105 The @code{recvfrom} function reads one packet from the socket
3106 @var{socket} into the buffer @var{buffer}. The @var{size} argument
3107 specifies the maximum number of bytes to be read.
3109 If the packet is longer than @var{size} bytes, then you get the first
3110 @var{size} bytes of the packet and the rest of the packet is lost.
3111 There's no way to read the rest of the packet. Thus, when you use a
3112 packet protocol, you must always know how long a packet to expect.
3114 The @var{addr} and @var{length-ptr} arguments are used to return the
3115 address where the packet came from. @xref{Socket Addresses}. For a
3116 socket in the local domain the address information won't be meaningful,
3117 since you can't read the address of such a socket (@pxref{Local
3118 Namespace}). You can specify a null pointer as the @var{addr} argument
3119 if you are not interested in this information.
3121 The @var{flags} are interpreted the same way as for @code{recv}
3122 (@pxref{Socket Data Options}). The return value and error conditions
3123 are also the same as for @code{recv}.
3125 This function is defined as a cancellation point in multi-threaded
3126 programs, so one has to be prepared for this and make sure that
3127 allocated resources (like memory, file descriptors, semaphores or
3128 whatever) are freed even if the thread is canceled.
3129 @c @xref{pthread_cleanup_push}, for a method how to do this.
3132 You can use plain @code{recv} (@pxref{Receiving Data}) instead of
3133 @code{recvfrom} if you don't need to find out who sent the packet
3134 (either because you know where it should come from or because you
3135 treat all possible senders alike). Even @code{read} can be used if
3136 you don't want to specify @var{flags} (@pxref{I/O Primitives}).
3138 If you need more flexibility and/or control over sending and receiving
3139 packets, see @code{sendmsg} and @code{recvmsg} (@pxref{Other Socket APIs}).
3141 @node Datagram Example
3142 @subsection Datagram Socket Example
3144 Here is a set of example programs that send messages over a datagram
3145 stream in the local namespace. Both the client and server programs use
3146 the @code{make_named_socket} function that was presented in @ref{Local
3147 Socket Example}, to create and name their sockets.
3149 First, here is the server program. It sits in a loop waiting for
3150 messages to arrive, bouncing each message back to the sender.
3151 Obviously this isn't a particularly useful program, but it does show
3152 the general ideas involved.
3155 @include filesrv.c.texi
3158 @node Example Receiver
3159 @subsection Example of Reading Datagrams
3161 Here is the client program corresponding to the server above.
3163 It sends a datagram to the server and then waits for a reply. Notice
3164 that the socket for the client (as well as for the server) in this
3165 example has to be given a name. This is so that the server can direct
3166 a message back to the client. Since the socket has no associated
3167 connection state, the only way the server can do this is by
3168 referencing the name of the client.
3171 @include filecli.c.texi
3174 Keep in mind that datagram socket communications are unreliable. In
3175 this example, the client program waits indefinitely if the message
3176 never reaches the server or if the server's response never comes
3177 back. It's up to the user running the program to kill and restart
3178 it if desired. A more automatic solution could be to use
3179 @code{select} (@pxref{Waiting for I/O}) to establish a timeout period
3180 for the reply, and in case of timeout either re-send the message or
3181 shut down the socket and exit.
3184 @section The @code{inetd} Daemon
3186 We've explained above how to write a server program that does its own
3187 listening. Such a server must already be running in order for anyone
3190 Another way to provide a service on an Internet port is to let the daemon
3191 program @code{inetd} do the listening. @code{inetd} is a program that
3192 runs all the time and waits (using @code{select}) for messages on a
3193 specified set of ports. When it receives a message, it accepts the
3194 connection (if the socket style calls for connections) and then forks a
3195 child process to run the corresponding server program. You specify the
3196 ports and their programs in the file @file{/etc/inetd.conf}.
3200 * Configuring Inetd::
3204 @subsection @code{inetd} Servers
3206 Writing a server program to be run by @code{inetd} is very simple. Each time
3207 someone requests a connection to the appropriate port, a new server
3208 process starts. The connection already exists at this time; the
3209 socket is available as the standard input descriptor and as the
3210 standard output descriptor (descriptors 0 and 1) in the server
3211 process. Thus the server program can begin reading and writing data
3212 right away. Often the program needs only the ordinary I/O facilities;
3213 in fact, a general-purpose filter program that knows nothing about
3214 sockets can work as a byte stream server run by @code{inetd}.
3216 You can also use @code{inetd} for servers that use connectionless
3217 communication styles. For these servers, @code{inetd} does not try to accept
3218 a connection since no connection is possible. It just starts the
3219 server program, which can read the incoming datagram packet from
3220 descriptor 0. The server program can handle one request and then
3221 exit, or you can choose to write it to keep reading more requests
3222 until no more arrive, and then exit. You must specify which of these
3223 two techniques the server uses when you configure @code{inetd}.
3225 @node Configuring Inetd
3226 @subsection Configuring @code{inetd}
3228 The file @file{/etc/inetd.conf} tells @code{inetd} which ports to listen to
3229 and what server programs to run for them. Normally each entry in the
3230 file is one line, but you can split it onto multiple lines provided
3231 all but the first line of the entry start with whitespace. Lines that
3232 start with @samp{#} are comments.
3234 Here are two standard entries in @file{/etc/inetd.conf}:
3237 ftp stream tcp nowait root /libexec/ftpd ftpd
3238 talk dgram udp wait root /libexec/talkd talkd
3241 An entry has this format:
3244 @var{service} @var{style} @var{protocol} @var{wait} @var{username} @var{program} @var{arguments}
3247 The @var{service} field says which service this program provides. It
3248 should be the name of a service defined in @file{/etc/services}.
3249 @code{inetd} uses @var{service} to decide which port to listen on for
3252 The fields @var{style} and @var{protocol} specify the communication
3253 style and the protocol to use for the listening socket. The style
3254 should be the name of a communication style, converted to lower case
3255 and with @samp{SOCK_} deleted---for example, @samp{stream} or
3256 @samp{dgram}. @var{protocol} should be one of the protocols listed in
3257 @file{/etc/protocols}. The typical protocol names are @samp{tcp} for
3258 byte stream connections and @samp{udp} for unreliable datagrams.
3260 The @var{wait} field should be either @samp{wait} or @samp{nowait}.
3261 Use @samp{wait} if @var{style} is a connectionless style and the
3262 server, once started, handles multiple requests as they come in.
3263 Use @samp{nowait} if @code{inetd} should start a new process for each message
3264 or request that comes in. If @var{style} uses connections, then
3265 @var{wait} @strong{must} be @samp{nowait}.
3267 @var{user} is the user name that the server should run as. @code{inetd} runs
3268 as root, so it can set the user ID of its children arbitrarily. It's
3269 best to avoid using @samp{root} for @var{user} if you can; but some
3270 servers, such as Telnet and FTP, read a username and passphrase
3271 themselves. These servers need to be root initially so they can log
3272 in as commanded by the data coming over the network.
3274 @var{program} together with @var{arguments} specifies the command to
3275 run to start the server. @var{program} should be an absolute file
3276 name specifying the executable file to run. @var{arguments} consists
3277 of any number of whitespace-separated words, which become the
3278 command-line arguments of @var{program}. The first word in
3279 @var{arguments} is argument zero, which should by convention be the
3280 program name itself (sans directories).
3282 If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the
3283 file and obey its new contents by sending the @code{inetd} process the
3284 @code{SIGHUP} signal. You'll have to use @code{ps} to determine the
3285 process ID of the @code{inetd} process as it is not fixed.
3287 @c !!! could document /etc/inetd.sec
3289 @node Socket Options
3290 @section Socket Options
3291 @cindex socket options
3293 This section describes how to read or set various options that modify
3294 the behavior of sockets and their underlying communications protocols.
3296 @cindex level, for socket options
3297 @cindex socket option level
3298 When you are manipulating a socket option, you must specify which
3299 @dfn{level} the option pertains to. This describes whether the option
3300 applies to the socket interface, or to a lower-level communications
3304 * Socket Option Functions:: The basic functions for setting and getting
3306 * Socket-Level Options:: Details of the options at the socket level.
3309 @node Socket Option Functions
3310 @subsection Socket Option Functions
3312 @pindex sys/socket.h
3313 Here are the functions for examining and modifying socket options.
3314 They are declared in @file{sys/socket.h}.
3316 @deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr})
3317 @standards{BSD, sys/socket.h}
3318 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3319 The @code{getsockopt} function gets information about the value of
3320 option @var{optname} at level @var{level} for socket @var{socket}.
3322 The option value is stored in the buffer that @var{optval} points to.
3323 Before the call, you should supply in @code{*@var{optlen-ptr}} the
3324 size of this buffer; on return, it contains the number of bytes of
3325 information actually stored in the buffer.
3327 Most options interpret the @var{optval} buffer as a single @code{int}
3330 The actual return value of @code{getsockopt} is @code{0} on success
3331 and @code{-1} on failure. The following @code{errno} error conditions
3336 The @var{socket} argument is not a valid file descriptor.
3339 The descriptor @var{socket} is not a socket.
3342 The @var{optname} doesn't make sense for the given @var{level}.
3346 @deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, const void *@var{optval}, socklen_t @var{optlen})
3347 @standards{BSD, sys/socket.h}
3348 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3349 This function is used to set the socket option @var{optname} at level
3350 @var{level} for socket @var{socket}. The value of the option is passed
3351 in the buffer @var{optval} of size @var{optlen}.
3356 The return value and error codes for @code{setsockopt} are the same as
3357 for @code{getsockopt}.
3360 The return value and error codes for @code{setsockopt} are the same as
3361 for @code{getsockopt}.
3366 @node Socket-Level Options
3367 @subsection Socket-Level Options
3369 @deftypevr Constant int SOL_SOCKET
3370 @standards{BSD, sys/socket.h}
3371 Use this constant as the @var{level} argument to @code{getsockopt} or
3372 @code{setsockopt} to manipulate the socket-level options described in
3376 @pindex sys/socket.h
3378 Here is a table of socket-level option names; all are defined in the
3379 header file @file{sys/socket.h}.
3383 @standards{BSD, sys/socket.h}
3384 @c Extra blank line here makes the table look better.
3386 This option toggles recording of debugging information in the underlying
3387 protocol modules. The value has type @code{int}; a nonzero value means
3389 @c !!! should say how this is used
3390 @c OK, anyone who knows, please explain.
3393 @standards{BSD, sys/socket.h}
3394 This option controls whether @code{bind} (@pxref{Setting Address})
3395 should permit reuse of local addresses for this socket. If you enable
3396 this option, you can actually have two sockets with the same Internet
3397 port number; but the system won't allow you to use the two
3398 identically-named sockets in a way that would confuse the Internet. The
3399 reason for this option is that some higher-level Internet protocols,
3400 including FTP, require you to keep reusing the same port number.
3402 The value has type @code{int}; a nonzero value means ``yes''.
3405 @standards{BSD, sys/socket.h}
3406 This option controls whether the underlying protocol should
3407 periodically transmit messages on a connected socket. If the peer
3408 fails to respond to these messages, the connection is considered
3409 broken. The value has type @code{int}; a nonzero value means
3413 @standards{BSD, sys/socket.h}
3414 This option controls whether outgoing messages bypass the normal
3415 message routing facilities. If set, messages are sent directly to the
3416 network interface instead. The value has type @code{int}; a nonzero
3417 value means ``yes''.
3420 @standards{BSD, sys/socket.h}
3421 This option specifies what should happen when the socket of a type
3422 that promises reliable delivery still has untransmitted messages when
3423 it is closed; see @ref{Closing a Socket}. The value has type
3424 @code{struct linger}.
3426 @deftp {Data Type} {struct linger}
3427 @standards{BSD, sys/socket.h}
3428 This structure type has the following members:
3432 This field is interpreted as a boolean. If nonzero, @code{close}
3433 blocks until the data are transmitted or the timeout period has expired.
3436 This specifies the timeout period, in seconds.
3441 @standards{BSD, sys/socket.h}
3442 This option controls whether datagrams may be broadcast from the socket.
3443 The value has type @code{int}; a nonzero value means ``yes''.
3446 @standards{BSD, sys/socket.h}
3447 If this option is set, out-of-band data received on the socket is
3448 placed in the normal input queue. This permits it to be read using
3449 @code{read} or @code{recv} without specifying the @code{MSG_OOB}
3450 flag. @xref{Out-of-Band Data}. The value has type @code{int}; a
3451 nonzero value means ``yes''.
3454 @standards{BSD, sys/socket.h}
3455 This option gets or sets the size of the output buffer. The value is a
3456 @code{size_t}, which is the size in bytes.
3459 @standards{BSD, sys/socket.h}
3460 This option gets or sets the size of the input buffer. The value is a
3461 @code{size_t}, which is the size in bytes.
3465 @standards{GNU, sys/socket.h}
3466 @standardsx{SO_TYPE, BSD, sys/socket.h}
3467 This option can be used with @code{getsockopt} only. It is used to
3468 get the socket's communication style. @code{SO_TYPE} is the
3469 historical name, and @code{SO_STYLE} is the preferred name in GNU.
3470 The value has type @code{int} and its value designates a communication
3471 style; see @ref{Communication Styles}.
3474 @standards{BSD, sys/socket.h}
3475 @c Extra blank line here makes the table look better.
3477 This option can be used with @code{getsockopt} only. It is used to reset
3478 the error status of the socket. The value is an @code{int}, which represents
3479 the previous error status.
3480 @c !!! what is "socket error status"? this is never defined.
3483 @node Networks Database
3484 @section Networks Database
3485 @cindex networks database
3486 @cindex converting network number to network name
3487 @cindex converting network name to network number
3489 @pindex /etc/networks
3491 Many systems come with a database that records a list of networks known
3492 to the system developer. This is usually kept either in the file
3493 @file{/etc/networks} or in an equivalent from a name server. This data
3494 base is useful for routing programs such as @code{route}, but it is not
3495 useful for programs that simply communicate over the network. We
3496 provide functions to access this database, which are declared in
3499 @deftp {Data Type} {struct netent}
3500 @standards{BSD, netdb.h}
3501 This data type is used to represent information about entries in the
3502 networks database. It has the following members:
3506 This is the ``official'' name of the network.
3508 @item char **n_aliases
3509 These are alternative names for the network, represented as a vector
3510 of strings. A null pointer terminates the array.
3512 @item int n_addrtype
3513 This is the type of the network number; this is always equal to
3514 @code{AF_INET} for Internet networks.
3516 @item unsigned long int n_net
3517 This is the network number. Network numbers are returned in host
3518 byte order; see @ref{Byte Order}.
3522 Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search
3523 the networks database for information about a specific network. The
3524 information is returned in a statically-allocated structure; you must
3525 copy the information if you need to save it.
3527 @deftypefun {struct netent *} getnetbyname (const char *@var{name})
3528 @standards{BSD, netdb.h}
3529 @safety{@prelim{}@mtunsafe{@mtasurace{:netbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
3530 @c getnetbyname =~ getpwuid @mtasurace:netbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3531 @c libc_lock_lock dup @asulock @aculock
3532 @c malloc dup @ascuheap @acsmem
3533 @c getnetbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3534 @c realloc dup @ascuheap @acsmem
3535 @c free dup @ascuheap @acsmem
3536 @c libc_lock_unlock dup @aculock
3538 @c getnetbyname_r =~ getpwuid_r @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3540 @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
3541 @c nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3542 @c *fct.l -> _nss_*_getnetbyname_r @ascuplugin
3543 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3544 The @code{getnetbyname} function returns information about the network
3545 named @var{name}. It returns a null pointer if there is no such
3549 @deftypefun {struct netent *} getnetbyaddr (uint32_t @var{net}, int @var{type})
3550 @standards{BSD, netdb.h}
3551 @safety{@prelim{}@mtunsafe{@mtasurace{:netbyaddr} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
3552 @c getnetbyaddr =~ getpwuid @mtasurace:netbyaddr @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3553 @c libc_lock_lock dup @asulock @aculock
3554 @c malloc dup @ascuheap @acsmem
3555 @c getnetbyaddr_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3556 @c realloc dup @ascuheap @acsmem
3557 @c free dup @ascuheap @acsmem
3558 @c libc_lock_unlock dup @aculock
3560 @c getnetbyaddr_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3562 @c nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3563 @c *fct.l -> _nss_*_getnetbyaddr_r @ascuplugin
3564 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3565 The @code{getnetbyaddr} function returns information about the network
3566 of type @var{type} with number @var{net}. You should specify a value of
3567 @code{AF_INET} for the @var{type} argument for Internet networks.
3569 @code{getnetbyaddr} returns a null pointer if there is no such
3573 You can also scan the networks database using @code{setnetent},
3574 @code{getnetent} and @code{endnetent}. Be careful when using these
3575 functions because they are not reentrant.
3577 @deftypefun void setnetent (int @var{stayopen})
3578 @standards{BSD, netdb.h}
3579 @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
3580 @c setnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3581 @c libc_lock_lock dup @asulock @aculock
3582 @c nss_setent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3583 @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
3584 @c setup(nss_networks_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3585 @c *lookup_fct = nss_networks_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3586 @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3587 @c *fct.f @mtasurace:netent @ascuplugin
3588 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3589 @c libc_lock_unlock dup @aculock
3590 This function opens and rewinds the networks database.
3592 If the @var{stayopen} argument is nonzero, this sets a flag so that
3593 subsequent calls to @code{getnetbyname} or @code{getnetbyaddr} will
3594 not close the database (as they usually would). This makes for more
3595 efficiency if you call those functions several times, by avoiding
3596 reopening the database for each call.
3599 @deftypefun {struct netent *} getnetent (void)
3600 @standards{BSD, netdb.h}
3601 @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtasurace{:netentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
3602 @c getnetent @mtasurace:netent @mtasurace:netentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3603 @c libc_lock_lock dup @asulock @aculock
3604 @c nss_getent(getnetent_r) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3605 @c malloc dup @ascuheap @acsmem
3606 @c *func = getnetent_r dup @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3607 @c realloc dup @ascuheap @acsmem
3608 @c free dup @ascuheap @acsmem
3609 @c libc_lock_unlock dup @aculock
3611 @c getnetent_r @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3612 @c libc_lock_lock dup @asulock @aculock
3613 @c nss_getent_r(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3614 @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
3615 @c setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3616 @c *fct.f @mtasurace:servent @ascuplugin
3617 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3618 @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3619 @c *sfct.f @mtasurace:netent @ascuplugin
3620 @c libc_lock_unlock dup @aculock
3621 This function returns the next entry in the networks database. It
3622 returns a null pointer if there are no more entries.
3625 @deftypefun void endnetent (void)
3626 @standards{BSD, netdb.h}
3627 @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
3628 @c endnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3629 @c libc_lock_lock @asulock @aculock
3630 @c nss_endent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3631 @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
3632 @c setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3633 @c *fct.f @mtasurace:netent @ascuplugin
3634 @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3635 @c libc_lock_unlock @aculock
3636 This function closes the networks database.
3639 @node Other Socket APIs
3640 @section Other Socket APIs
3642 @deftp {Data Type} {struct msghdr}
3643 @standards{BSD, sys/socket.h}
3646 @deftypefun ssize_t sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags})
3648 @manpagefunctionstub{sendmsg,2}
3651 @deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
3653 @manpagefunctionstub{recvmsg,2}