Use Linux 6.6 in build-many-glibcs.py
[glibc.git] / manual / socket.texi
blobf0e35d9e13175212689299d8a7a6b4ec932afdcc
1 @node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top
2 @c %MENU% A more complicated IPC mechanism, with networking support
3 @chapter Sockets
5 This chapter describes the GNU facilities for interprocess
6 communication using sockets.
8 @cindex socket
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.
28 @menu
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 @end menu
46 @node Socket Concepts
47 @section Socket Concepts
49 @cindex communication style (of a socket)
50 @cindex style of communication (of a socket)
51 When you create a socket, you must specify the style of communication
52 you want to use and the type of protocol that should implement it.
53 The @dfn{communication style} of a socket defines the user-level
54 semantics of sending and receiving data on the socket.  Choosing a
55 communication style specifies the answers to questions such as these:
57 @itemize @bullet
58 @item
59 @cindex packet
60 @cindex byte stream
61 @cindex stream (sockets)
62 @strong{What are the units of data transmission?}  Some communication
63 styles regard the data as a sequence of bytes with no larger
64 structure; others group the bytes into records (which are known in
65 this context as @dfn{packets}).
67 @item
68 @cindex loss of data on sockets
69 @cindex data loss on sockets
70 @strong{Can data be lost during normal operation?}  Some communication
71 styles guarantee that all the data sent arrives in the order it was
72 sent (barring system or network crashes); other styles occasionally
73 lose data as a normal part of operation, and may sometimes deliver
74 packets more than once or in the wrong order.
76 Designing a program to use unreliable communication styles usually
77 involves taking precautions to detect lost or misordered packets and
78 to retransmit data as needed.
80 @item
81 @strong{Is communication entirely with one partner?}  Some
82 communication styles are like a telephone call---you make a
83 @dfn{connection} with one remote socket and then exchange data
84 freely.  Other styles are like mailing letters---you specify a
85 destination address for each message you send.
86 @end itemize
88 @cindex namespace (of socket)
89 @cindex domain (of socket)
90 @cindex socket namespace
91 @cindex socket domain
92 You must also choose a @dfn{namespace} for naming the socket.  A socket
93 name (``address'') is meaningful only in the context of a particular
94 namespace.  In fact, even the data type to use for a socket name may
95 depend on the namespace.  Namespaces are also called ``domains'', but we
96 avoid that word as it can be confused with other usage of the same
97 term.  Each namespace has a symbolic name that starts with @samp{PF_}.
98 A corresponding symbolic name starting with @samp{AF_} designates the
99 address format for that namespace.
101 @cindex network protocol
102 @cindex protocol (of socket)
103 @cindex socket protocol
104 @cindex protocol family
105 Finally you must choose the @dfn{protocol} to carry out the
106 communication.  The protocol determines what low-level mechanism is used
107 to transmit and receive data.  Each protocol is valid for a particular
108 namespace and communication style; a namespace is sometimes called a
109 @dfn{protocol family} because of this, which is why the namespace names
110 start with @samp{PF_}.
112 The rules of a protocol apply to the data passing between two programs,
113 perhaps on different computers; most of these rules are handled by the
114 operating system and you need not know about them.  What you do need to
115 know about protocols is this:
117 @itemize @bullet
118 @item
119 In order to have communication between two sockets, they must specify
120 the @emph{same} protocol.
122 @item
123 Each protocol is meaningful with particular style/namespace
124 combinations and cannot be used with inappropriate combinations.  For
125 example, the TCP protocol fits only the byte stream style of
126 communication and the Internet namespace.
128 @item
129 For each combination of style and namespace there is a @dfn{default
130 protocol}, which you can request by specifying 0 as the protocol
131 number.  And that's what you should normally do---use the default.
132 @end itemize
134 Throughout the following description at various places
135 variables/parameters to denote sizes are required.  And here the trouble
136 starts.  In the first implementations the type of these variables was
137 simply @code{int}.  On most machines at that time an @code{int} was 32
138 bits wide, which created a @emph{de facto} standard requiring 32-bit
139 variables.  This is important since references to variables of this type
140 are passed to the kernel.
142 Then the POSIX people came and unified the interface with the words "all
143 size values are of type @code{size_t}".  On 64-bit machines
144 @code{size_t} is 64 bits wide, so pointers to variables were no longer
145 possible.
147 The Unix98 specification provides a solution by introducing a type
148 @code{socklen_t}.  This type is used in all of the cases that POSIX
149 changed to use @code{size_t}.  The only requirement of this type is that
150 it be an unsigned type of at least 32 bits.  Therefore, implementations
151 which require that references to 32-bit variables be passed can be as
152 happy as implementations which use 64-bit values.
155 @node Communication Styles
156 @section Communication Styles
158 @Theglibc{} includes support for several different kinds of sockets,
159 each with different characteristics.  This section describes the
160 supported socket types.  The symbolic constants listed here are
161 defined in @file{sys/socket.h}.
162 @pindex sys/socket.h
164 @deftypevr Macro int SOCK_STREAM
165 @standards{BSD, sys/socket.h}
166 The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}).
167 It operates over a connection with a particular remote socket and
168 transmits data reliably as a stream of bytes.
170 Use of this style is covered in detail in @ref{Connections}.
171 @end deftypevr
173 @deftypevr Macro int SOCK_DGRAM
174 @standards{BSD, sys/socket.h}
175 The @code{SOCK_DGRAM} style is used for sending
176 individually-addressed packets unreliably.
177 It is the diametrical opposite of @code{SOCK_STREAM}.
179 Each time you write data to a socket of this kind, that data becomes
180 one packet.  Since @code{SOCK_DGRAM} sockets do not have connections,
181 you must specify the recipient address with each packet.
183 The only guarantee that the system makes about your requests to
184 transmit data is that it will try its best to deliver each packet you
185 send.  It may succeed with the sixth packet after failing with the
186 fourth and fifth packets; the seventh packet may arrive before the
187 sixth, and may arrive a second time after the sixth.
189 The typical use for @code{SOCK_DGRAM} is in situations where it is
190 acceptable to simply re-send a packet if no response is seen in a
191 reasonable amount of time.
193 @xref{Datagrams}, for detailed information about how to use datagram
194 sockets.
195 @end deftypevr
197 @ignore
198 @c This appears to be only for the NS domain, which we aren't
199 @c discussing and probably won't support either.
200 @deftypevr Macro int SOCK_SEQPACKET
201 @standards{BSD, sys/socket.h}
202 This style is like @code{SOCK_STREAM} except that the data are
203 structured into packets.
205 A program that receives data over a @code{SOCK_SEQPACKET} socket
206 should be prepared to read the entire message packet in a single call
207 to @code{read}; if it only reads part of the message, the remainder of
208 the message is simply discarded instead of being available for
209 subsequent calls to @code{read}.
211 Many protocols do not support this communication style.
212 @end deftypevr
213 @end ignore
215 @ignore
216 @deftypevr Macro int SOCK_RDM
217 @standards{BSD, sys/socket.h}
218 This style is a reliable version of @code{SOCK_DGRAM}: it sends
219 individually addressed packets, but guarantees that each packet sent
220 arrives exactly once.
222 @strong{Warning:} It is not clear this is actually supported
223 by any operating system.
224 @end deftypevr
225 @end ignore
227 @deftypevr Macro int SOCK_RAW
228 @standards{BSD, sys/socket.h}
229 This style provides access to low-level network protocols and
230 interfaces.  Ordinary user programs usually have no need to use this
231 style.
232 @end deftypevr
234 @node Socket Addresses
235 @section Socket Addresses
237 @cindex address of socket
238 @cindex name of socket
239 @cindex binding a socket address
240 @cindex socket address (name) binding
241 The name of a socket is normally called an @dfn{address}.  The
242 functions and symbols for dealing with socket addresses were named
243 inconsistently, sometimes using the term ``name'' and sometimes using
244 ``address''.  You can regard these terms as synonymous where sockets
245 are concerned.
247 A socket newly created with the @code{socket} function has no
248 address.  Other processes can find it for communication only if you
249 give it an address.  We call this @dfn{binding} the address to the
250 socket, and the way to do it is with the @code{bind} function.
252 You need only be concerned with the address of a socket if other processes
253 are to find it and start communicating with it.  You can specify an
254 address for other sockets, but this is usually pointless; the first time
255 you send data from a socket, or use it to initiate a connection, the
256 system assigns an address automatically if you have not specified one.
258 Occasionally a client needs to specify an address because the server
259 discriminates based on address; for example, the rsh and rlogin
260 protocols look at the client's socket address and only bypass passphrase
261 checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
263 The details of socket addresses vary depending on what namespace you are
264 using.  @xref{Local Namespace}, or @ref{Internet Namespace}, for specific
265 information.
267 Regardless of the namespace, you use the same functions @code{bind} and
268 @code{getsockname} to set and examine a socket's address.  These
269 functions use a phony data type, @code{struct sockaddr *}, to accept the
270 address.  In practice, the address lives in a structure of some other
271 data type appropriate to the address format you are using, but you cast
272 its address to @code{struct sockaddr *} when you pass it to
273 @code{bind}.
275 @menu
276 * Address Formats::             About @code{struct sockaddr}.
277 * Setting Address::             Binding an address to a socket.
278 * Reading Address::             Reading the address of a socket.
279 @end menu
281 @node Address Formats
282 @subsection Address Formats
284 The functions @code{bind} and @code{getsockname} use the generic data
285 type @code{struct sockaddr *} to represent a pointer to a socket
286 address.  You can't use this data type effectively to interpret an
287 address or construct one; for that, you must use the proper data type
288 for the socket's namespace.
290 Thus, the usual practice is to construct an address of the proper
291 namespace-specific type, then cast a pointer to @code{struct sockaddr *}
292 when you call @code{bind} or @code{getsockname}.
294 The one piece of information that you can get from the @code{struct
295 sockaddr} data type is the @dfn{address format designator}.  This tells
296 you which data type to use to understand the address fully.
298 @pindex sys/socket.h
299 The symbols in this section are defined in the header file
300 @file{sys/socket.h}.
302 @deftp {Data Type} {struct sockaddr}
303 @standards{BSD, sys/socket.h}
304 The @code{struct sockaddr} type itself has the following members:
306 @table @code
307 @item short int sa_family
308 This is the code for the address format of this address.  It
309 identifies the format of the data which follows.
311 @item char sa_data[14]
312 This is the actual socket address data, which is format-dependent.  Its
313 length also depends on the format, and may well be more than 14.  The
314 length 14 of @code{sa_data} is essentially arbitrary.
315 @end table
316 @end deftp
318 Each address format has a symbolic name which starts with @samp{AF_}.
319 Each of them corresponds to a @samp{PF_} symbol which designates the
320 corresponding namespace.  Here is a list of address format names:
322 @vtable @code
323 @item AF_LOCAL
324 @standards{POSIX, sys/socket.h}
325 This designates the address format that goes with the local namespace.
326 (@code{PF_LOCAL} is the name of that namespace.)  @xref{Local Namespace
327 Details}, for information about this address format.
329 @item AF_UNIX
330 @standards{BSD, sys/socket.h}
331 @standards{Unix98, sys/socket.h}
332 This is a synonym for @code{AF_LOCAL}.  Although @code{AF_LOCAL} is
333 mandated by POSIX.1g, @code{AF_UNIX} is portable to more systems.
334 @code{AF_UNIX} was the traditional name stemming from BSD, so even most
335 POSIX systems support it.  It is also the name of choice in the Unix98
336 specification. (The same is true for @code{PF_UNIX}
337 vs. @code{PF_LOCAL}).
339 @item AF_FILE
340 @standards{GNU, sys/socket.h}
341 This is another synonym for @code{AF_LOCAL}, for compatibility.
342 (@code{PF_FILE} is likewise a synonym for @code{PF_LOCAL}.)
344 @item AF_INET
345 @standards{BSD, sys/socket.h}
346 This designates the address format that goes with the Internet
347 namespace.  (@code{PF_INET} is the name of that namespace.)
348 @xref{Internet Address Formats}.
350 @item AF_INET6
351 @standards{IPv6 Basic API, sys/socket.h}
352 This is similar to @code{AF_INET}, but refers to the IPv6 protocol.
353 (@code{PF_INET6} is the name of the corresponding namespace.)
355 @item AF_UNSPEC
356 @standards{BSD, sys/socket.h}
357 This designates no particular address format.  It is used only in rare
358 cases, such as to clear out the default destination address of a
359 ``connected'' datagram socket.  @xref{Sending Datagrams}.
361 The corresponding namespace designator symbol @code{PF_UNSPEC} exists
362 for completeness, but there is no reason to use it in a program.
363 @end vtable
365 @file{sys/socket.h} defines symbols starting with @samp{AF_} for many
366 different kinds of networks, most or all of which are not actually
367 implemented.  We will document those that really work as we receive
368 information about how to use them.
370 @node Setting Address
371 @subsection Setting the Address of a Socket
373 @pindex sys/socket.h
374 Use the @code{bind} function to assign an address to a socket.  The
375 prototype for @code{bind} is in the header file @file{sys/socket.h}.
376 For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}.
378 @deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
379 @standards{BSD, sys/socket.h}
380 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
381 @c Direct syscall, except on Hurd.
382 The @code{bind} function assigns an address to the socket
383 @var{socket}.  The @var{addr} and @var{length} arguments specify the
384 address; the detailed format of the address depends on the namespace.
385 The first part of the address is always the format designator, which
386 specifies a namespace, and says that the address is in the format of
387 that namespace.
389 The return value is @code{0} on success and @code{-1} on failure.  The
390 following @code{errno} error conditions are defined for this function:
392 @table @code
393 @item EBADF
394 The @var{socket} argument is not a valid file descriptor.
396 @item ENOTSOCK
397 The descriptor @var{socket} is not a socket.
399 @item EADDRNOTAVAIL
400 The specified address is not available on this machine.
402 @item EADDRINUSE
403 Some other socket is already using the specified address.
405 @item EINVAL
406 The socket @var{socket} already has an address.
408 @item EACCES
409 You do not have permission to access the requested address.  (In the
410 Internet domain, only the super-user is allowed to specify a port number
411 in the range 0 through @code{IPPORT_RESERVED} minus one; see
412 @ref{Ports}.)
413 @end table
415 Additional conditions may be possible depending on the particular namespace
416 of the socket.
417 @end deftypefun
419 @node Reading Address
420 @subsection Reading the Address of a Socket
422 @pindex sys/socket.h
423 Use the function @code{getsockname} to examine the address of an
424 Internet socket.  The prototype for this function is in the header file
425 @file{sys/socket.h}.
427 @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
428 @standards{BSD, sys/socket.h}
429 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsmem{/hurd}}}
430 @c Direct syscall, except on Hurd, where it seems like it might leak
431 @c VM if cancelled.
432 The @code{getsockname} function returns information about the
433 address of the socket @var{socket} in the locations specified by the
434 @var{addr} and @var{length-ptr} arguments.  Note that the
435 @var{length-ptr} is a pointer; you should initialize it to be the
436 allocation size of @var{addr}, and on return it contains the actual
437 size of the address data.
439 The format of the address data depends on the socket namespace.  The
440 length of the information is usually fixed for a given namespace, so
441 normally you can know exactly how much space is needed and can provide
442 that much.  The usual practice is to allocate a place for the value
443 using the proper data type for the socket's namespace, then cast its
444 address to @code{struct sockaddr *} to pass it to @code{getsockname}.
446 The return value is @code{0} on success and @code{-1} on error.  The
447 following @code{errno} error conditions are defined for this function:
449 @table @code
450 @item EBADF
451 The @var{socket} argument is not a valid file descriptor.
453 @item ENOTSOCK
454 The descriptor @var{socket} is not a socket.
456 @item ENOBUFS
457 There are not enough internal buffers available for the operation.
458 @end table
459 @end deftypefun
461 You can't read the address of a socket in the file namespace.  This is
462 consistent with the rest of the system; in general, there's no way to
463 find a file's name from a descriptor for that file.
465 @node Interface Naming
466 @section Interface Naming
468 Each network interface has a name.  This usually consists of a few
469 letters that relate to the type of interface, which may be followed by a
470 number if there is more than one interface of that type.  Examples
471 might be @code{lo} (the loopback interface) and @code{eth0} (the first
472 Ethernet interface).
474 Although such names are convenient for humans, it would be clumsy to
475 have to use them whenever a program needs to refer to an interface.  In
476 such situations an interface is referred to by its @dfn{index}, which is
477 an arbitrarily-assigned small positive integer.
479 The following functions, constants and data types are declared in the
480 header file @file{net/if.h}.
482 @deftypevr Constant size_t IFNAMSIZ
483 @standards{???, net/if.h}
484 This constant defines the maximum buffer size needed to hold an
485 interface name, including its terminating zero byte.
486 @end deftypevr
488 @deftypefun {unsigned int} if_nametoindex (const char *@var{ifname})
489 @standards{IPv6 basic API, net/if.h}
490 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
491 @c It opens a socket to use ioctl on the fd to get the index.
492 @c opensock may call socket and access multiple times until it finds a
493 @c socket family that works.  The Linux implementation has a potential
494 @c concurrency issue WRT last_type and last_family not being updated
495 @c atomically, but it is harmless; the generic implementation, OTOH,
496 @c takes a lock, which makes all callers AS- and AC-Unsafe.
497 @c  opensock @asulock @aculock @acsfd
498 This function yields the interface index corresponding to a particular
499 name.  If no interface exists with the name given, it returns 0.
500 @end deftypefun
502 @deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname})
503 @standards{IPv6 basic API, net/if.h}
504 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
505 @c It opens a socket with opensock to use ioctl on the fd to get the
506 @c name from the index.
507 This function maps an interface index to its corresponding name.  The
508 returned name is placed in the buffer pointed to by @code{ifname}, which
509 must be at least @code{IFNAMSIZ} bytes in length.  If the index was
510 invalid, the function's return value is a null pointer, otherwise it is
511 @code{ifname}.
512 @end deftypefun
514 @deftp {Data Type} {struct if_nameindex}
515 @standards{IPv6 basic API, net/if.h}
516 This data type is used to hold the information about a single
517 interface.  It has the following members:
519 @table @code
520 @item unsigned int if_index;
521 This is the interface index.
523 @item char *if_name
524 This is the null-terminated index name.
526 @end table
527 @end deftp
529 @deftypefun {struct if_nameindex *} if_nameindex (void)
530 @standards{IPv6 basic API, net/if.h}
531 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@aculock{/hurd} @acsfd{} @acsmem{}}}
532 @c if_nameindex @ascuheap @asulock/hurd @aculock/hurd @acsfd @acsmem
533 @c  [linux]
534 @c   netlink_open @acsfd @acsmem/hurd
535 @c    socket dup @acsfd
536 @c    memset dup ok
537 @c    bind dup ok
538 @c    netlink_close dup @acsfd
539 @c    getsockname dup @acsmem/hurd
540 @c   netlink_request @ascuheap @acsmem
541 @c    getpagesize dup ok
542 @c    malloc dup @ascuheap @acsmem
543 @c    netlink_sendreq ok
544 @c     memset dup ok
545 @c     sendto dup ok
546 @c    recvmsg dup ok
547 @c    memcpy dup ok
548 @c    free dup @ascuheap @acsmem
549 @c   netlink_free_handle @ascuheap @acsmem
550 @c    free dup @ascuheap @acsmem
551 @c   netlink_close @acsfd
552 @c    close dup @acsfd
553 @c   malloc dup @asuheap @acsmem
554 @c   strndup @ascuheap @acsmem
555 @c   if_freenameindex @ascuheap @acsmem
556 @c  [hurd]
557 @c   opensock dup @asulock @aculock @acsfd
558 @c   hurd_socket_server ok
559 @c   pfinet_siocgifconf ok
560 @c   malloc @ascuheap @acsmem
561 @c   strdup @ascuheap @acsmem
562 @c   ioctl dup ok
563 @c   free @ascuheap @acsmem
564 This function returns an array of @code{if_nameindex} structures, one
565 for every interface that is present.  The end of the list is indicated
566 by a structure with an interface of 0 and a null name pointer.  If an
567 error occurs, this function returns a null pointer.
569 The returned structure must be freed with @code{if_freenameindex} after
570 use.
571 @end deftypefun
573 @deftypefun void if_freenameindex (struct if_nameindex *@var{ptr})
574 @standards{IPv6 basic API, net/if.h}
575 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
576 @c if_freenameindex @ascuheap @acsmem
577 @c  free dup @ascuheap @acsmem
578 This function frees the structure returned by an earlier call to
579 @code{if_nameindex}.
580 @end deftypefun
582 @node Local Namespace
583 @section The Local Namespace
584 @cindex local namespace, for sockets
586 This section describes the details of the local namespace, whose
587 symbolic name (required when you create a socket) is @code{PF_LOCAL}.
588 The local namespace is also known as ``Unix domain sockets''.  Another
589 name is file namespace since socket addresses are normally implemented
590 as file names.
592 @menu
593 * Concepts: Local Namespace Concepts. What you need to understand.
594 * Details: Local Namespace Details.   Address format, symbolic names, etc.
595 * Example: Local Socket Example.      Example of creating a socket.
596 @end menu
598 @node Local Namespace Concepts
599 @subsection Local Namespace Concepts
601 In the local namespace socket addresses are file names.  You can specify
602 any file name you want as the address of the socket, but you must have
603 write permission on the directory containing it.
604 @c XXX The following was said to be wrong.
605 @c In order to connect to a socket you must have read permission for it.
606 It's common to put these files in the @file{/tmp} directory.
608 One peculiarity of the local namespace is that the name is only used
609 when opening the connection; once open the address is not meaningful and
610 may not exist.
612 Another peculiarity is that you cannot connect to such a socket from
613 another machine--not even if the other machine shares the file system
614 which contains the name of the socket.  You can see the socket in a
615 directory listing, but connecting to it never succeeds.  Some programs
616 take advantage of this, such as by asking the client to send its own
617 process ID, and using the process IDs to distinguish between clients.
618 However, we recommend you not use this method in protocols you design,
619 as we might someday permit connections from other machines that mount
620 the same file systems.  Instead, send each new client an identifying
621 number if you want it to have one.
623 After you close a socket in the local namespace, you should delete the
624 file name from the file system.  Use @code{unlink} or @code{remove} to
625 do this; see @ref{Deleting Files}.
627 The local namespace supports just one protocol for any communication
628 style; it is protocol number @code{0}.
630 @node Local Namespace Details
631 @subsection Details of Local Namespace
633 @pindex sys/socket.h
634 To create a socket in the local namespace, use the constant
635 @code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or
636 @code{socketpair}.  This constant is defined in @file{sys/socket.h}.
638 @deftypevr Macro int PF_LOCAL
639 @standards{POSIX, sys/socket.h}
640 This designates the local namespace, in which socket addresses are local
641 names, and its associated family of protocols.  @code{PF_LOCAL} is the
642 macro used by POSIX.1g.
643 @end deftypevr
645 @deftypevr Macro int PF_UNIX
646 @standards{BSD, sys/socket.h}
647 This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
648 @end deftypevr
650 @deftypevr Macro int PF_FILE
651 @standards{GNU, sys/socket.h}
652 This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
653 @end deftypevr
655 The structure for specifying socket names in the local namespace is
656 defined in the header file @file{sys/un.h}:
657 @pindex sys/un.h
659 @deftp {Data Type} {struct sockaddr_un}
660 @standards{BSD, sys/un.h}
661 This structure is used to specify local namespace socket addresses.  It has
662 the following members:
664 @table @code
665 @item short int sun_family
666 This identifies the address family or format of the socket address.
667 You should store the value @code{AF_LOCAL} to designate the local
668 namespace.  @xref{Socket Addresses}.
670 @item char sun_path[108]
671 This is the file name to use.
673 @strong{Incomplete:}  Why is 108 a magic number?  RMS suggests making
674 this a zero-length array and tweaking the following example to use
675 @code{alloca} to allocate an appropriate amount of storage based on
676 the length of the filename.
677 @end table
678 @end deftp
680 You should compute the @var{length} parameter for a socket address in
681 the local namespace as the sum of the size of the @code{sun_family}
682 component and the string length (@emph{not} the allocation size!) of
683 the file name string.  This can be done using the macro @code{SUN_LEN}:
685 @deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr})
686 @standards{BSD, sys/un.h}
687 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
688 This macro computes the length of the socket address in the local namespace.
689 @end deftypefn
691 @node Local Socket Example
692 @subsection Example of Local-Namespace Sockets
694 Here is an example showing how to create and name a socket in the local
695 namespace.
697 @smallexample
698 @include mkfsock.c.texi
699 @end smallexample
701 @node Internet Namespace
702 @section The Internet Namespace
703 @cindex Internet namespace, for sockets
705 This section describes the details of the protocols and socket naming
706 conventions used in the Internet namespace.
708 Originally the Internet namespace used only IP version 4 (IPv4).  With
709 the growing number of hosts on the Internet, a new protocol with a
710 larger address space was necessary: IP version 6 (IPv6).  IPv6
711 introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
712 features, and will eventually replace IPv4.
714 To create a socket in the IPv4 Internet namespace, use the symbolic name
715 @code{PF_INET} of this namespace as the @var{namespace} argument to
716 @code{socket} or @code{socketpair}.  For IPv6 addresses you need the
717 macro @code{PF_INET6}.  These macros are defined in @file{sys/socket.h}.
718 @pindex sys/socket.h
720 @deftypevr Macro int PF_INET
721 @standards{BSD, sys/socket.h}
722 This designates the IPv4 Internet namespace and associated family of
723 protocols.
724 @end deftypevr
726 @deftypevr Macro int PF_INET6
727 @standards{X/Open, sys/socket.h}
728 This designates the IPv6 Internet namespace and associated family of
729 protocols.
730 @end deftypevr
732 A socket address for the Internet namespace includes the following components:
734 @itemize @bullet
735 @item
736 The address of the machine you want to connect to.  Internet addresses
737 can be specified in several ways; these are discussed in @ref{Internet
738 Address Formats}, @ref{Host Addresses} and @ref{Host Names}.
740 @item
741 A port number for that machine.  @xref{Ports}.
742 @end itemize
744 You must ensure that the address and port number are represented in a
745 canonical format called @dfn{network byte order}.  @xref{Byte Order},
746 for information about this.
748 @menu
749 * Internet Address Formats::    How socket addresses are specified in the
750                                  Internet namespace.
751 * Host Addresses::              All about host addresses of Internet host.
752 * Ports::                       Internet port numbers.
753 * Services Database::           Ports may have symbolic names.
754 * Byte Order::                  Different hosts may use different byte
755                                  ordering conventions; you need to
756                                  canonicalize host address and port number.
757 * Protocols Database::          Referring to protocols by name.
758 * Inet Example::                Putting it all together.
759 @end menu
761 @node Internet Address Formats
762 @subsection Internet Socket Address Formats
764 In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6
765 (@code{AF_INET6}), a socket address consists of a host address
766 and a port on that host.  In addition, the protocol you choose serves
767 effectively as a part of the address because local port numbers are
768 meaningful only within a particular protocol.
770 The data types for representing socket addresses in the Internet namespace
771 are defined in the header file @file{netinet/in.h}.
772 @pindex netinet/in.h
774 @deftp {Data Type} {struct sockaddr_in}
775 @standards{BSD, netinet/in.h}
776 This is the data type used to represent socket addresses in the
777 Internet namespace.  It has the following members:
779 @table @code
780 @item sa_family_t sin_family
781 This identifies the address family or format of the socket address.
782 You should store the value @code{AF_INET} in this member.  The address
783 family is stored in host byte order.  @xref{Socket Addresses}.
785 @item struct in_addr sin_addr
786 This is the IPv4 address.  @xref{Host Addresses}, and @ref{Host
787 Names}, for how to get a value to store here.  The IPv4 address is
788 stored in network byte order.
790 @item unsigned short int sin_port
791 This is the port number.  @xref{Ports}.  The port number is stored in
792 network byte order.
793 @end table
794 @end deftp
796 When you call @code{bind} or @code{getsockname}, you should specify
797 @code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
798 you are using an IPv4 Internet namespace socket address.
800 @deftp {Data Type} {struct sockaddr_in6}
801 This is the data type used to represent socket addresses in the IPv6
802 namespace.  It has the following members:
804 @table @code
805 @item sa_family_t sin6_family
806 This identifies the address family or format of the socket address.
807 You should store the value of @code{AF_INET6} in this member.
808 @xref{Socket Addresses}.  The address family is stored in host byte
809 order.
811 @item struct in6_addr sin6_addr
812 This is the IPv6 address of the host machine.  @xref{Host
813 Addresses}, and @ref{Host Names}, for how to get a value to store
814 here.  The address is stored in network byte order.
816 @item uint32_t sin6_flowinfo
817 @cindex flow label
818 @cindex IPv6 flow label
819 @cindex traffic class
820 @cindex IPv6 traffic class
821 This combines the IPv6 traffic class and flow label values, as found
822 in the IPv6 header.  This field is stored in network byte order.  Only
823 the 28 lower bits (of the number in network byte order) are used; the
824 remaining bits must be zero.  The lower 20 bits are the flow label, and
825 bits 20 to 27 are the the traffic class.  Typically, this field is
826 zero.
828 @item uint32_t sin6_scope_id
829 @cindex scope ID
830 @cindex IPv6 scope ID
831 For link-local addresses, this identifies the interface on which this
832 address is valid.  The scope ID is stored in host byte order.
833 Typically, this field is zero.
835 @item uint16_t sin6_port
836 This is the port number.  @xref{Ports}.  The port number is stored in
837 network byte order.
839 @end table
840 @end deftp
842 @node Host Addresses
843 @subsection Host Addresses
845 Each computer on the Internet has one or more @dfn{Internet addresses},
846 numbers which identify that computer among all those on the Internet.
847 Users typically write IPv4 numeric host addresses as sequences of four
848 numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6
849 numeric host addresses as sequences of up to eight numbers separated by
850 colons, as in @samp{5f03:1200:836f:c100::1}.
852 Each computer also has one or more @dfn{host names}, which are strings
853 of words separated by periods, as in @samp{www.gnu.org}.
855 Programs that let the user specify a host typically accept both numeric
856 addresses and host names.  To open a connection a program needs a
857 numeric address, and so must convert a host name to the numeric address
858 it stands for.
860 @menu
861 * Abstract Host Addresses::     What a host number consists of.
862 * Data type: Host Address Data Type.    Data type for a host number.
863 * Functions: Host Address Functions.    Functions to operate on them.
864 * Names: Host Names.            Translating host names to host numbers.
865 @end menu
867 @node Abstract Host Addresses
868 @subsubsection Internet Host Addresses
869 @cindex host address, Internet
870 @cindex Internet host address
872 @ifinfo
873 Each computer on the Internet has one or more Internet addresses,
874 numbers which identify that computer among all those on the Internet.
875 @end ifinfo
877 @cindex network number
878 @cindex local network address number
879 An IPv4 Internet host address is a number containing four bytes of data.
880 Historically these are divided into two parts, a @dfn{network number} and a
881 @dfn{local network address number} within that network.  In the
882 mid-1990s classless addresses were introduced which changed this
883 behavior.  Since some functions implicitly expect the old definitions,
884 we first describe the class-based network and will then describe
885 classless addresses.  IPv6 uses only classless addresses and therefore
886 the following paragraphs don't apply.
888 The class-based IPv4 network number consists of the first one, two or
889 three bytes; the rest of the bytes are the local address.
891 IPv4 network numbers are registered with the Network Information Center
892 (NIC), and are divided into three classes---A, B and C.  The local
893 network address numbers of individual machines are registered with the
894 administrator of the particular network.
896 Class A networks have single-byte numbers in the range 0 to 127.  There
897 are only a small number of Class A networks, but they can each support a
898 very large number of hosts.  Medium-sized Class B networks have two-byte
899 network numbers, with the first byte in the range 128 to 191.  Class C
900 networks are the smallest; they have three-byte network numbers, with
901 the first byte in the range 192-255.  Thus, the first 1, 2, or 3 bytes
902 of an Internet address specify a network.  The remaining bytes of the
903 Internet address specify the address within that network.
905 The Class A network 0 is reserved for broadcast to all networks.  In
906 addition, the host number 0 within each network is reserved for broadcast
907 to all hosts in that network.  These uses are obsolete now but for
908 compatibility reasons you shouldn't use network 0 and host number 0.
910 The Class A network 127 is reserved for loopback; you can always use
911 the Internet address @samp{127.0.0.1} to refer to the host machine.
913 Since a single machine can be a member of multiple networks, it can
914 have multiple Internet host addresses.  However, there is never
915 supposed to be more than one machine with the same host address.
917 @c !!! this section could document the IN_CLASS* macros in <netinet/in.h>.
918 @c No, it shouldn't since they're obsolete.
920 @cindex standard dot notation, for Internet addresses
921 @cindex dot notation, for Internet addresses
922 There are four forms of the @dfn{standard numbers-and-dots notation}
923 for Internet addresses:
925 @table @code
926 @item @var{a}.@var{b}.@var{c}.@var{d}
927 This specifies all four bytes of the address individually and is the
928 commonly used representation.
930 @item @var{a}.@var{b}.@var{c}
931 The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
932 This is useful for specifying host addresses in a Class B network with
933 network address number @code{@var{a}.@var{b}}.
935 @item @var{a}.@var{b}
936 The last part of the address, @var{b}, is interpreted as a 3-byte quantity.
937 This is useful for specifying host addresses in a Class A network with
938 network address number @var{a}.
940 @item @var{a}
941 If only one part is given, this corresponds directly to the host address
942 number.
943 @end table
945 Within each part of the address, the usual C conventions for specifying
946 the radix apply.  In other words, a leading @samp{0x} or @samp{0X} implies
947 hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
948 radix is assumed.
950 @subsubheading Classless Addresses
952 IPv4 addresses (and IPv6 addresses also) are now considered classless;
953 the distinction between classes A, B and C can be ignored.  Instead an
954 IPv4 host address consists of a 32-bit address and a 32-bit mask.  The
955 mask contains set bits for the network part and cleared bits for the
956 host part.  The network part is contiguous from the left, with the
957 remaining bits representing the host.  As a consequence, the netmask can
958 simply be specified as the number of set bits.  Classes A, B and C are
959 just special cases of this general rule.  For example, class A addresses
960 have a netmask of @samp{255.0.0.0} or a prefix length of 8.
962 Classless IPv4 network addresses are written in numbers-and-dots
963 notation with the prefix length appended and a slash as separator.  For
964 example the class A network 10 is written as @samp{10.0.0.0/8}.
966 @subsubheading IPv6 Addresses
968 IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data.  A host
969 address is usually written as eight 16-bit hexadecimal numbers that are
970 separated by colons.  Two colons are used to abbreviate strings of
971 consecutive zeros.  For example, the IPv6 loopback address
972 @samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}.
974 @node Host Address Data Type
975 @subsubsection Host Address Data Type
977 IPv4 Internet host addresses are represented in some contexts as integers
978 (type @code{uint32_t}).  In other contexts, the integer is
979 packaged inside a structure of type @code{struct in_addr}.  It would
980 be better if the usage were made consistent, but it is not hard to extract
981 the integer from the structure or put the integer into a structure.
983 You will find older code that uses @code{unsigned long int} for
984 IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct
985 in_addr}.  Historically @code{unsigned long int} was a 32-bit number but
986 with 64-bit machines this has changed.  Using @code{unsigned long int}
987 might break the code if it is used on machines where this type doesn't
988 have 32 bits.  @code{uint32_t} is specified by Unix98 and guaranteed to have
989 32 bits.
991 IPv6 Internet host addresses have 128 bits and are packaged inside a
992 structure of type @code{struct in6_addr}.
994 The following basic definitions for Internet addresses are declared in
995 the header file @file{netinet/in.h}:
996 @pindex netinet/in.h
998 @deftp {Data Type} {struct in_addr}
999 @standards{BSD, netinet/in.h}
1000 This data type is used in certain contexts to contain an IPv4 Internet
1001 host address.  It has just one field, named @code{s_addr}, which records
1002 the host address number as an @code{uint32_t}.
1003 @end deftp
1005 @deftypevr Macro {uint32_t} INADDR_LOOPBACK
1006 @standards{BSD, netinet/in.h}
1007 You can use this constant to stand for ``the address of this machine,''
1008 instead of finding its actual address.  It is the IPv4 Internet address
1009 @samp{127.0.0.1}, which is usually called @samp{localhost}.  This
1010 special constant saves you the trouble of looking up the address of your
1011 own machine.  Also, the system usually implements @code{INADDR_LOOPBACK}
1012 specially, avoiding any network traffic for the case of one machine
1013 talking to itself.
1014 @end deftypevr
1016 @deftypevr Macro {uint32_t} INADDR_ANY
1017 @standards{BSD, netinet/in.h}
1018 You can use this constant to stand for ``any incoming address'' when
1019 binding to an address.  @xref{Setting Address}.  This is the usual
1020 address to give in the @code{sin_addr} member of @w{@code{struct
1021 sockaddr_in}} when you want to accept Internet connections.
1022 @end deftypevr
1024 @deftypevr Macro {uint32_t} INADDR_BROADCAST
1025 @standards{BSD, netinet/in.h}
1026 This constant is the address you use to send a broadcast message.
1027 @c !!! broadcast needs further documented
1028 @end deftypevr
1030 @deftypevr Macro {uint32_t} INADDR_NONE
1031 @standards{BSD, netinet/in.h}
1032 This constant is returned by some functions to indicate an error.
1033 @end deftypevr
1035 @deftp {Data Type} {struct in6_addr}
1036 @standards{IPv6 basic API, netinet/in.h}
1037 This data type is used to store an IPv6 address.  It stores 128 bits of
1038 data, which can be accessed (via a union) in a variety of ways.
1039 @end deftp
1041 @deftypevr Constant {struct in6_addr} in6addr_loopback
1042 @standards{IPv6 basic API, netinet/in.h}
1043 This constant is the IPv6 address @samp{::1}, the loopback address.  See
1044 above for a description of what this means.  The macro
1045 @code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your
1046 own variables to this value.
1047 @end deftypevr
1049 @deftypevr Constant {struct in6_addr} in6addr_any
1050 @standards{IPv6 basic API, netinet/in.h}
1051 This constant is the IPv6 address @samp{::}, the unspecified address.  See
1052 above for a description of what this means.  The macro
1053 @code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your
1054 own variables to this value.
1055 @end deftypevr
1057 @node Host Address Functions
1058 @subsubsection Host Address Functions
1060 @pindex arpa/inet.h
1061 @noindent
1062 These additional functions for manipulating Internet addresses are
1063 declared in the header file @file{arpa/inet.h}.  They represent Internet
1064 addresses in network byte order, and network numbers and
1065 local-address-within-network numbers in host byte order.  @xref{Byte
1066 Order}, for an explanation of network and host byte order.
1068 @deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr})
1069 @standards{BSD, arpa/inet.h}
1070 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1071 @c inet_aton @mtslocale
1072 @c  isdigit dup @mtslocale
1073 @c  strtoul dup @mtslocale
1074 @c  isascii dup @mtslocale
1075 @c  isspace dup @mtslocale
1076 @c  htonl dup ok
1077 This function converts the IPv4 Internet host address @var{name}
1078 from the standard numbers-and-dots notation into binary data and stores
1079 it in the @code{struct in_addr} that @var{addr} points to.
1080 @code{inet_aton} returns nonzero if the address is valid, zero if not.
1081 @end deftypefun
1083 @deftypefun {uint32_t} inet_addr (const char *@var{name})
1084 @standards{BSD, arpa/inet.h}
1085 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1086 @c inet_addr @mtslocale
1087 @c  inet_aton dup @mtslocale
1088 This function converts the IPv4 Internet host address @var{name} from the
1089 standard numbers-and-dots notation into binary data.  If the input is
1090 not valid, @code{inet_addr} returns @code{INADDR_NONE}.  This is an
1091 obsolete interface to @code{inet_aton}, described immediately above.  It
1092 is obsolete because @code{INADDR_NONE} is a valid address
1093 (255.255.255.255), and @code{inet_aton} provides a cleaner way to
1094 indicate error return.
1095 @end deftypefun
1097 @deftypefun {uint32_t} inet_network (const char *@var{name})
1098 @standards{BSD, arpa/inet.h}
1099 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1100 @c inet_network @mtslocale
1101 @c  isdigit dup @mtslocale
1102 @c  isxdigit dup @mtslocale
1103 @c  tolower dup @mtslocale
1104 @c  isspace dup @mtslocale
1105 This function extracts the network number from the address @var{name},
1106 given in the standard numbers-and-dots notation.  The returned address is
1107 in host order.  If the input is not valid, @code{inet_network} returns
1108 @code{-1}.
1110 The function works only with traditional IPv4 class A, B and C network
1111 types.  It doesn't work with classless addresses and shouldn't be used
1112 anymore.
1113 @end deftypefun
1115 @deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
1116 @standards{BSD, arpa/inet.h}
1117 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asurace{}}@acsafe{}}
1118 @c inet_ntoa @mtslocale @asurace
1119 @c   writes to a thread-local static buffer
1120 @c  snprintf @mtslocale [no @ascuheap or @acsmem]
1121 This function converts the IPv4 Internet host address @var{addr} to a
1122 string in the standard numbers-and-dots notation.  The return value is
1123 a pointer into a statically-allocated buffer.  Subsequent calls will
1124 overwrite the same buffer, so you should copy the string if you need
1125 to save it.
1127 In multi-threaded programs each thread has its own statically-allocated
1128 buffer.  But still subsequent calls of @code{inet_ntoa} in the same
1129 thread will overwrite the result of the last call.
1131 Instead of @code{inet_ntoa} the newer function @code{inet_ntop} which is
1132 described below should be used since it handles both IPv4 and IPv6
1133 addresses.
1134 @end deftypefun
1136 @deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local})
1137 @standards{BSD, arpa/inet.h}
1138 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1139 @c inet_makeaddr ok
1140 @c  htonl dup ok
1141 This function makes an IPv4 Internet host address by combining the network
1142 number @var{net} with the local-address-within-network number
1143 @var{local}.
1144 @end deftypefun
1146 @deftypefun uint32_t inet_lnaof (struct in_addr @var{addr})
1147 @standards{BSD, arpa/inet.h}
1148 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1149 @c inet_lnaof ok
1150 @c  ntohl dup ok
1151 @c  IN_CLASSA ok
1152 @c  IN_CLASSB ok
1153 This function returns the local-address-within-network part of the
1154 Internet host address @var{addr}.
1156 The function works only with traditional IPv4 class A, B and C network
1157 types.  It doesn't work with classless addresses and shouldn't be used
1158 anymore.
1159 @end deftypefun
1161 @deftypefun uint32_t inet_netof (struct in_addr @var{addr})
1162 @standards{BSD, arpa/inet.h}
1163 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1164 @c inet_netof ok
1165 @c  ntohl dup ok
1166 @c  IN_CLASSA ok
1167 @c  IN_CLASSB ok
1168 This function returns the network number part of the Internet host
1169 address @var{addr}.
1171 The function works only with traditional IPv4 class A, B and C network
1172 types.  It doesn't work with classless addresses and shouldn't be used
1173 anymore.
1174 @end deftypefun
1176 @deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf})
1177 @standards{IPv6 basic API, arpa/inet.h}
1178 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1179 @c inet_pton @mtslocale
1180 @c  inet_pton4 ok
1181 @c   memcpy dup ok
1182 @c  inet_pton6 @mtslocale
1183 @c   memset dup ok
1184 @c   tolower dup @mtslocale
1185 @c   strchr dup ok
1186 @c   inet_pton4 dup ok
1187 @c   memcpy dup ok
1188 This function converts an Internet address (either IPv4 or IPv6) from
1189 presentation (textual) to network (binary) format.  @var{af} should be
1190 either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of
1191 address being converted.  @var{cp} is a pointer to the input string, and
1192 @var{buf} is a pointer to a buffer for the result.  It is the caller's
1193 responsibility to make sure the buffer is large enough.
1194 @end deftypefun
1196 @deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len})
1197 @standards{IPv6 basic API, arpa/inet.h}
1198 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1199 @c inet_ntop @mtslocale
1200 @c  inet_ntop4 @mtslocale
1201 @c   sprintf dup @mtslocale [no @ascuheap or @acsmem]
1202 @c   strcpy dup ok
1203 @c  inet_ntop6 @mtslocale
1204 @c   memset dup ok
1205 @c   inet_ntop4 dup @mtslocale
1206 @c   sprintf dup @mtslocale [no @ascuheap or @acsmem]
1207 @c   strcpy dup ok
1208 This function converts an Internet address (either IPv4 or IPv6) from
1209 network (binary) to presentation (textual) form.  @var{af} should be
1210 either @code{AF_INET} or @code{AF_INET6}, as appropriate.  @var{cp} is a
1211 pointer to the address to be converted.  @var{buf} should be a pointer
1212 to a buffer to hold the result, and @var{len} is the length of this
1213 buffer.  The return value from the function will be this buffer address.
1214 @end deftypefun
1216 @node Host Names
1217 @subsubsection Host Names
1218 @cindex hosts database
1219 @cindex converting host name to address
1220 @cindex converting host address to name
1222 Besides the standard numbers-and-dots notation for Internet addresses,
1223 you can also refer to a host by a symbolic name.  The advantage of a
1224 symbolic name is that it is usually easier to remember.  For example,
1225 the machine with Internet address @samp{158.121.106.19} is also known as
1226 @samp{alpha.gnu.org}; and other machines in the @samp{gnu.org}
1227 domain can refer to it simply as @samp{alpha}.
1229 @pindex /etc/hosts
1230 @pindex netdb.h
1231 Internally, the system uses a database to keep track of the mapping
1232 between host names and host numbers.  This database is usually either
1233 the file @file{/etc/hosts} or an equivalent provided by a name server.
1234 The functions and other symbols for accessing this database are declared
1235 in @file{netdb.h}.  They are BSD features, defined unconditionally if
1236 you include @file{netdb.h}.
1238 @deftp {Data Type} {struct hostent}
1239 @standards{BSD, netdb.h}
1240 This data type is used to represent an entry in the hosts database.  It
1241 has the following members:
1243 @table @code
1244 @item char *h_name
1245 This is the ``official'' name of the host.
1247 @item char **h_aliases
1248 These are alternative names for the host, represented as a null-terminated
1249 vector of strings.
1251 @item int h_addrtype
1252 This is the host address type; in practice, its value is always either
1253 @code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6
1254 hosts.  In principle other kinds of addresses could be represented in
1255 the database as well as Internet addresses; if this were done, you
1256 might find a value in this field other than @code{AF_INET} or
1257 @code{AF_INET6}.  @xref{Socket Addresses}.
1259 @item int h_length
1260 This is the length, in bytes, of each address.
1262 @item char **h_addr_list
1263 This is the vector of addresses for the host.  (Recall that the host
1264 might be connected to multiple networks and have different addresses on
1265 each one.)  The vector is terminated by a null pointer.
1267 @item char *h_addr
1268 This is a synonym for @code{h_addr_list[0]}; in other words, it is the
1269 first host address.
1270 @end table
1271 @end deftp
1273 As far as the host database is concerned, each address is just a block
1274 of memory @code{h_length} bytes long.  But in other contexts there is an
1275 implicit assumption that you can convert IPv4 addresses to a
1276 @code{struct in_addr} or an @code{uint32_t}.  Host addresses in
1277 a @code{struct hostent} structure are always given in network byte
1278 order; see @ref{Byte Order}.
1280 You can use @code{gethostbyname}, @code{gethostbyname2} or
1281 @code{gethostbyaddr} to search the hosts database for information about
1282 a particular host.  The information is returned in a
1283 statically-allocated structure; you must copy the information if you
1284 need to save it across calls.  You can also use @code{getaddrinfo} and
1285 @code{getnameinfo} to obtain this information.
1287 @deftypefun {struct hostent *} gethostbyname (const char *@var{name})
1288 @standards{BSD, netdb.h}
1289 @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1290 @c gethostbyname @mtasurace:hostbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1291 @c  libc_lock_lock dup @asulock @aculock
1292 @c  malloc dup @ascuheap @acsmem
1293 @c  nss_hostname_digits_dots @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1294 @c   res_maybe_init(!preinit) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1295 @c    res_iclose @acsuheap @acsmem @acsfd
1296 @c     close_not_cancel_no_status dup @acsfd
1297 @c     free dup @acsuheap @acsmem
1298 @c    res_vinit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1299 @c     res_randomid ok
1300 @c      getpid dup ok
1301 @c     getenv dup @mtsenv
1302 @c     strncpy dup ok
1303 @c     fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
1304 @c     fsetlocking dup ok [no concurrent uses]
1305 @c     fgets_unlocked dup ok [no concurrent uses]
1306 @c     MATCH ok
1307 @c      strncmp dup ok
1308 @c     strpbrk dup ok
1309 @c     strchr dup ok
1310 @c     inet_aton dup @mtslocale
1311 @c     htons dup
1312 @c     inet_pton dup @mtslocale
1313 @c     malloc dup @ascuheap @acsmem
1314 @c     IN6_IS_ADDR_LINKLOCAL ok
1315 @c      htonl dup ok
1316 @c     IN6_IS_ADDR_MC_LINKLOCAL ok
1317 @c     if_nametoindex dup @asulock @aculock @acsfd
1318 @c     strtoul dup @mtslocale
1319 @c     ISSORTMASK ok
1320 @c      strchr dup ok
1321 @c     isascii dup @mtslocale
1322 @c     isspace dup @mtslocale
1323 @c     net_mask ok
1324 @c      ntohl dup ok
1325 @c      IN_CLASSA dup ok
1326 @c      htonl dup ok
1327 @c      IN_CLASSB dup ok
1328 @c     res_setoptions @mtslocale
1329 @c      strncmp dup ok
1330 @c      atoi dup @mtslocale
1331 @c     fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
1332 @c     inet_makeaddr dup ok
1333 @c     gethostname dup ok
1334 @c     strcpy dup ok
1335 @c     rawmemchr dup ok
1336 @c    res_ninit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1337 @c     res_vinit dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1338 @c   isdigit dup @mtslocale
1339 @c   isxdigit dup @mtslocale
1340 @c   strlen dup ok
1341 @c   realloc dup @ascuheap @acsmem
1342 @c   free dup @ascuheap @acsmem
1343 @c   memset dup ok
1344 @c   inet_aton dup @mtslocale
1345 @c   inet_pton dup @mtslocale
1346 @c   strcpy dup ok
1347 @c   memcpy dup ok
1348 @c   strchr dup ok
1349 @c  gethostbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1350 @c  realloc dup @ascuheap @acsmem
1351 @c  free dup @ascuheap @acsmem
1352 @c  libc_lock_unlock dup @aculock
1353 @c  set_h_errno ok
1354 The @code{gethostbyname} function returns information about the host
1355 named @var{name}.  If the lookup fails, it returns a null pointer.
1356 @end deftypefun
1358 @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
1359 @standards{IPv6 Basic API, netdb.h}
1360 @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname2} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1361 @c gethostbyname2 @mtasurace:hostbyname2 @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1362 @c  libc_lock_lock dup @asulock @aculock
1363 @c  malloc dup @ascuheap @acsmem
1364 @c  nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1365 @c  gethostbyname2_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1366 @c  realloc dup @ascuheap @acsmem
1367 @c  free dup @ascuheap @acsmem
1368 @c  libc_lock_unlock dup @aculock
1369 @c  set_h_errno dup ok
1370 The @code{gethostbyname2} function is like @code{gethostbyname}, but
1371 allows the caller to specify the desired address family (e.g.@:
1372 @code{AF_INET} or @code{AF_INET6}) of the result.
1373 @end deftypefun
1375 @deftypefun {struct hostent *} gethostbyaddr (const void *@var{addr}, socklen_t @var{length}, int @var{format})
1376 @standards{BSD, netdb.h}
1377 @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyaddr} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1378 @c gethostbyaddr @mtasurace:hostbyaddr @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1379 @c  libc_lock_lock dup @asulock @aculock
1380 @c  malloc dup @ascuheap @acsmem
1381 @c  gethostbyaddr_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1382 @c  realloc dup @ascuheap @acsmem
1383 @c  free dup @ascuheap @acsmem
1384 @c  libc_lock_unlock dup @aculock
1385 @c  set_h_errno dup ok
1386 The @code{gethostbyaddr} function returns information about the host
1387 with Internet address @var{addr}.  The parameter @var{addr} is not
1388 really a pointer to char - it can be a pointer to an IPv4 or an IPv6
1389 address.  The @var{length} argument is the size (in bytes) of the address
1390 at @var{addr}.  @var{format} specifies the address format; for an IPv4
1391 Internet address, specify a value of @code{AF_INET}; for an IPv6
1392 Internet address, use @code{AF_INET6}.
1394 If the lookup fails, @code{gethostbyaddr} returns a null pointer.
1395 @end deftypefun
1397 @vindex h_errno
1398 If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
1399 fails, you can find out the reason by looking at the value of the
1400 variable @code{h_errno}.  (It would be cleaner design for these
1401 functions to set @code{errno}, but use of @code{h_errno} is compatible
1402 with other systems.)
1404 Here are the error codes that you may find in @code{h_errno}:
1406 @vtable @code
1407 @item HOST_NOT_FOUND
1408 @standards{BSD, netdb.h}
1409 No such host is known in the database.
1411 @item TRY_AGAIN
1412 @standards{BSD, netdb.h}
1413 This condition happens when the name server could not be contacted.  If
1414 you try again later, you may succeed then.
1416 @item NO_RECOVERY
1417 @standards{BSD, netdb.h}
1418 A non-recoverable error occurred.
1420 @item NO_ADDRESS
1421 @standards{BSD, netdb.h}
1422 The host database contains an entry for the name, but it doesn't have an
1423 associated Internet address.
1424 @end vtable
1426 The lookup functions above all have one thing in common: they are not
1427 reentrant and therefore unusable in multi-threaded applications.
1428 Therefore provides @theglibc{} a new set of functions which can be
1429 used in this context.
1431 @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})
1432 @standards{GNU, netdb.h}
1433 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1434 @c gethostbyname_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1435 @c  nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1436 @c  nscd_gethostbyname_r @mtsenv @ascuheap @acsfd @acsmem
1437 @c   nscd_gethst_r @mtsenv @ascuheap @acsfd @acsmem
1438 @c    getenv dup @mtsenv
1439 @c    nscd_get_map_ref dup @ascuheap @acsfd @acsmem
1440 @c    nscd_cache_search dup ok
1441 @c    memcpy dup ok
1442 @c    nscd_open_socket dup @acsfd
1443 @c    readvall dup ok
1444 @c    readall dup ok
1445 @c    close_not_cancel_no_status dup @acsfd
1446 @c    nscd_drop_map_ref dup @ascuheap @acsmem
1447 @c    nscd_unmap dup @ascuheap @acsmem
1448 @c  res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1449 @c  res_hconf_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called]
1450 @c   res_hconf.c:do_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1451 @c    memset dup ok
1452 @c    getenv dup @mtsenv
1453 @c    fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
1454 @c    fsetlocking dup ok [no concurrent uses]
1455 @c    fgets_unlocked dup ok [no concurrent uses]
1456 @c    strchrnul dup ok
1457 @c    res_hconf.c:parse_line @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1458 @c     skip_ws dup @mtslocale
1459 @c     skip_string dup @mtslocale
1460 @c     strncasecmp dup @mtslocale
1461 @c     strlen dup ok
1462 @c     asprintf dup @mtslocale @ascuheap @acsmem
1463 @c     fxprintf dup @asucorrupt @aculock @acucorrupt
1464 @c     free dup @ascuheap @acsmem
1465 @c     arg_trimdomain_list dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1466 @c     arg_spoof dup @mtslocale
1467 @c     arg_bool dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1468 @c     isspace dup @mtslocale
1469 @c    fclose dup @ascuheap @asulock @acsmem @acsfd @aculock
1470 @c    arg_spoof @mtslocale
1471 @c     skip_string @mtslocale
1472 @c      isspace dup @mtslocale
1473 @c     strncasecmp dup @mtslocale
1474 @c    arg_bool @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1475 @c     strncasecmp dup @mtslocale
1476 @c     asprintf dup @mtslocale @ascuheap @acsmem
1477 @c     fxprintf dup @asucorrupt @aculock @acucorrupt
1478 @c     free dup @ascuheap @acsmem
1479 @c    arg_trimdomain_list @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
1480 @c     skip_string dup @mtslocale
1481 @c     asprintf dup @mtslocale @ascuheap @acsmem
1482 @c     fxprintf dup @asucorrupt @aculock @acucorrupt
1483 @c     free dup @ascuheap @acsmem
1484 @c     strndup dup @ascuheap @acsmem
1485 @c     skip_ws @mtslocale
1486 @c      isspace dup @mtslocale
1487 @c  nss_hosts_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1488 @c   nss_database_lookup dup @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock
1489 @c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1490 @c  *fct.l -> _nss_*_gethostbyname_r @ascuplugin
1491 @c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1492 @c  res_hconf_reorder_addrs @asulock @ascuheap @aculock @acsmem @acsfd
1493 @c   socket dup @acsfd
1494 @c   libc_lock_lock dup @asulock @aculock
1495 @c   ifreq @ascuheap @acsmem
1496 @c   malloc dup @ascuheap @acsmem
1497 @c   if_nextreq dup ok
1498 @c   ioctl dup ok
1499 @c   realloc dup @ascuheap @acsmem
1500 @c   if_freereq dup @acsmem
1501 @c   libc_lock_unlock dup @aculock
1502 @c   close dup @acsfd
1503 The @code{gethostbyname_r} function returns information about the host
1504 named @var{name}.  The caller must pass a pointer to an object of type
1505 @code{struct hostent} in the @var{result_buf} parameter.  In addition
1506 the function may need extra buffer space and the caller must pass a
1507 pointer and the size of the buffer in the @var{buf} and @var{buflen}
1508 parameters.
1510 A pointer to the buffer, in which the result is stored, is available in
1511 @code{*@var{result}} after the function call successfully returned.  The
1512 buffer passed as the @var{buf} parameter can be freed only once the caller
1513 has finished with the result hostent struct, or has copied it including all
1514 the other memory that it points to.  If an error occurs or if no entry is
1515 found, the pointer @code{*@var{result}} is a null pointer.  Success is
1516 signalled by a zero return value.  If the function failed the return value
1517 is an error number.  In addition to the errors defined for
1518 @code{gethostbyname} it can also be @code{ERANGE}.  In this case the call
1519 should be repeated with a larger buffer.  Additional error information is
1520 not stored in the global variable @code{h_errno} but instead in the object
1521 pointed to by @var{h_errnop}.
1523 Here's a small example:
1524 @smallexample
1525 struct hostent *
1526 gethostname (char *host)
1528   struct hostent *hostbuf, *hp;
1529   size_t hstbuflen;
1530   char *tmphstbuf;
1531   int res;
1532   int herr;
1534   hostbuf = malloc (sizeof (struct hostent));
1535   hstbuflen = 1024;
1536   tmphstbuf = malloc (hstbuflen);
1538   while ((res = gethostbyname_r (host, hostbuf, tmphstbuf, hstbuflen,
1539                                  &hp, &herr)) == ERANGE)
1540     @{
1541       /* Enlarge the buffer.  */
1542       tmphstbuf = reallocarray (tmphstbuf, hstbuflen, 2);
1543       hstbuflen *= 2;
1544     @}
1546   free (tmphstbuf);
1547   /*  Check for errors.  */
1548   if (res || hp == NULL)
1549     return NULL;
1550   return hp;
1552 @end smallexample
1553 @end deftypefun
1555 @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})
1556 @standards{GNU, netdb.h}
1557 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1558 @c gethostbyname2_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1559 @c  nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1560 @c  nscd_gethostbyname2_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
1561 @c   nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
1562 @c  res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1563 @c  res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called]
1564 @c  nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1565 @c  *fct.l -> _nss_*_gethostbyname2_r @ascuplugin
1566 @c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1567 @c  res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd
1568 The @code{gethostbyname2_r} function is like @code{gethostbyname_r}, but
1569 allows the caller to specify the desired address family (e.g.@:
1570 @code{AF_INET} or @code{AF_INET6}) for the result.
1571 @end deftypefun
1573 @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})
1574 @standards{GNU, netdb.h}
1575 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
1576 @c gethostbyaddr_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
1577 @c  memcmp dup ok
1578 @c  nscd_gethostbyaddr_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
1579 @c   nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
1580 @c  res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1581 @c  res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called]
1582 @c  nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1583 @c  *fct.l -> _nss_*_gethostbyaddr_r @ascuplugin
1584 @c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1585 @c  res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd
1586 @c  res_hconf_trim_domains @mtslocale
1587 @c   res_hconf_trim_domain @mtslocale
1588 @c    strlen dup ok
1589 @c    strcasecmp dup @mtslocale
1590 The @code{gethostbyaddr_r} function returns information about the host
1591 with Internet address @var{addr}.  The parameter @var{addr} is not
1592 really a pointer to char - it can be a pointer to an IPv4 or an IPv6
1593 address.  The @var{length} argument is the size (in bytes) of the address
1594 at @var{addr}.  @var{format} specifies the address format; for an IPv4
1595 Internet address, specify a value of @code{AF_INET}; for an IPv6
1596 Internet address, use @code{AF_INET6}.
1598 Similar to the @code{gethostbyname_r} function, the caller must provide
1599 buffers for the result and memory used internally.  In case of success
1600 the function returns zero.  Otherwise the value is an error number where
1601 @code{ERANGE} has the special meaning that the caller-provided buffer is
1602 too small.
1603 @end deftypefun
1605 You can also scan the entire hosts database one entry at a time using
1606 @code{sethostent}, @code{gethostent} and @code{endhostent}.  Be careful
1607 when using these functions because they are not reentrant.
1609 @deftypefun void sethostent (int @var{stayopen})
1610 @standards{BSD, netdb.h}
1611 @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1612 @c sethostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1613 @c  libc_lock_lock dup @asulock @aculock
1614 @c  nss_setent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1615 @c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1616 @c   set_h_errno dup ok
1617 @c   setup(nss_hosts_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1618 @c    *lookup_fct = nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1619 @c    nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1620 @c   *fct.f @mtasurace:hostent @ascuplugin
1621 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1622 @c  libc_lock_unlock dup @aculock
1623 This function opens the hosts database to begin scanning it.  You can
1624 then call @code{gethostent} to read the entries.
1626 @c There was a rumor that this flag has different meaning if using the DNS,
1627 @c but it appears this description is accurate in that case also.
1628 If the @var{stayopen} argument is nonzero, this sets a flag so that
1629 subsequent calls to @code{gethostbyname} or @code{gethostbyaddr} will
1630 not close the database (as they usually would).  This makes for more
1631 efficiency if you call those functions several times, by avoiding
1632 reopening the database for each call.
1633 @end deftypefun
1635 @deftypefun {struct hostent *} gethostent (void)
1636 @standards{BSD, netdb.h}
1637 @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtasurace{:hostentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1638 @c gethostent @mtasurace:hostent @mtasurace:hostentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1639 @c  libc_lock_lock dup @asulock @aculock
1640 @c  nss_getent(gethostent_r) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1641 @c   malloc dup @ascuheap @acsmem
1642 @c   *func = gethostent_r dup @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1643 @c   realloc dup @ascuheap @acsmem
1644 @c   free dup @ascuheap @acsmem
1645 @c  libc_lock_unlock dup @aculock
1647 @c gethostent_r @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1648 @c  libc_lock_lock dup @asulock @aculock
1649 @c  nss_getent_r(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1650 @c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1651 @c   setup(nss_hosts_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1652 @c   *fct.f @mtasurace:hostent @ascuplugin
1653 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1654 @c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1655 @c   *sfct.f @mtasurace:hostent @ascuplugin
1656 @c  libc_lock_unlock dup @aculock
1658 This function returns the next entry in the hosts database.  It
1659 returns a null pointer if there are no more entries.
1660 @end deftypefun
1662 @deftypefun void endhostent (void)
1663 @standards{BSD, netdb.h}
1664 @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1665 @c endhostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1666 @c  libc_lock_lock @asulock @aculock
1667 @c  nss_endent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1668 @c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1669 @c   setup(nss_passwd_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1670 @c   *fct.f @mtasurace:hostent @ascuplugin
1671 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1672 @c  libc_lock_unlock @aculock
1673 This function closes the hosts database.
1674 @end deftypefun
1676 @node Ports
1677 @subsection Internet Ports
1678 @cindex port number
1680 A socket address in the Internet namespace consists of a machine's
1681 Internet address plus a @dfn{port number} which distinguishes the
1682 sockets on a given machine (for a given protocol).  Port numbers range
1683 from 0 to 65,535.
1685 Port numbers less than @code{IPPORT_RESERVED} are reserved for standard
1686 servers, such as @code{finger} and @code{telnet}.  There is a database
1687 that keeps track of these, and you can use the @code{getservbyname}
1688 function to map a service name onto a port number; see @ref{Services
1689 Database}.
1691 If you write a server that is not one of the standard ones defined in
1692 the database, you must choose a port number for it.  Use a number
1693 greater than @code{IPPORT_USERRESERVED}; such numbers are reserved for
1694 servers and won't ever be generated automatically by the system.
1695 Avoiding conflicts with servers being run by other users is up to you.
1697 When you use a socket without specifying its address, the system
1698 generates a port number for it.  This number is between
1699 @code{IPPORT_RESERVED} and @code{IPPORT_USERRESERVED}.
1701 On the Internet, it is actually legitimate to have two different
1702 sockets with the same port number, as long as they never both try to
1703 communicate with the same socket address (host address plus port
1704 number).  You shouldn't duplicate a port number except in special
1705 circumstances where a higher-level protocol requires it.  Normally,
1706 the system won't let you do it; @code{bind} normally insists on
1707 distinct port numbers.  To reuse a port number, you must set the
1708 socket option @code{SO_REUSEADDR}.  @xref{Socket-Level Options}.
1710 @pindex netinet/in.h
1711 These macros are defined in the header file @file{netinet/in.h}.
1713 @deftypevr Macro int IPPORT_RESERVED
1714 @standards{BSD, netinet/in.h}
1715 Port numbers less than @code{IPPORT_RESERVED} are reserved for
1716 superuser use.
1717 @end deftypevr
1719 @deftypevr Macro int IPPORT_USERRESERVED
1720 @standards{BSD, netinet/in.h}
1721 Port numbers greater than or equal to @code{IPPORT_USERRESERVED} are
1722 reserved for explicit use; they will never be allocated automatically.
1723 @end deftypevr
1725 @node Services Database
1726 @subsection The Services Database
1727 @cindex services database
1728 @cindex converting service name to port number
1729 @cindex converting port number to service name
1731 @pindex /etc/services
1732 The database that keeps track of ``well-known'' services is usually
1733 either the file @file{/etc/services} or an equivalent from a name server.
1734 You can use these utilities, declared in @file{netdb.h}, to access
1735 the services database.
1736 @pindex netdb.h
1738 @deftp {Data Type} {struct servent}
1739 @standards{BSD, netdb.h}
1740 This data type holds information about entries from the services database.
1741 It has the following members:
1743 @table @code
1744 @item char *s_name
1745 This is the ``official'' name of the service.
1747 @item char **s_aliases
1748 These are alternate names for the service, represented as an array of
1749 strings.  A null pointer terminates the array.
1751 @item int s_port
1752 This is the port number for the service.  Port numbers are given in
1753 network byte order; see @ref{Byte Order}.
1755 @item char *s_proto
1756 This is the name of the protocol to use with this service.
1757 @xref{Protocols Database}.
1758 @end table
1759 @end deftp
1761 To get information about a particular service, use the
1762 @code{getservbyname} or @code{getservbyport} functions.  The information
1763 is returned in a statically-allocated structure; you must copy the
1764 information if you need to save it across calls.
1766 @deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto})
1767 @standards{BSD, netdb.h}
1768 @safety{@prelim{}@mtunsafe{@mtasurace{:servbyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1769 @c getservbyname =~ getpwuid @mtasurace:servbyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1770 @c  libc_lock_lock dup @asulock @aculock
1771 @c  malloc dup @ascuheap @acsmem
1772 @c  getservbyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1773 @c  realloc dup @ascuheap @acsmem
1774 @c  free dup @ascuheap @acsmem
1775 @c  libc_lock_unlock dup @aculock
1777 @c getservbyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1778 @c  nscd_getservbyname_r @ascuheap @acsfd @acsmem
1779 @c   nscd_getserv_r @ascuheap @acsfd @acsmem
1780 @c    nscd_get_map_ref dup @ascuheap @acsfd @acsmem
1781 @c    strlen dup ok
1782 @c    malloc dup @ascuheap @acsmem
1783 @c    mempcpy dup ok
1784 @c    memcpy dup ok
1785 @c    nscd_cache_search dup ok
1786 @c    nscd_open_socket dup @acsfd
1787 @c    readvall dup ok
1788 @c    readall dup ok
1789 @c    close_not_cancel_no_status dup @acsfd
1790 @c    nscd_drop_map_ref dup @ascuheap @acsmem
1791 @c    nscd_unmap dup @ascuheap @acsmem
1792 @c    free dup @ascuheap @acsmem
1793 @c  nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1794 @c  *fct.l -> _nss_*_getservbyname_r @ascuplugin
1795 @c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1796 The @code{getservbyname} function returns information about the
1797 service named @var{name} using protocol @var{proto}.  If it can't find
1798 such a service, it returns a null pointer.
1800 This function is useful for servers as well as for clients; servers
1801 use it to determine which port they should listen on (@pxref{Listening}).
1802 @end deftypefun
1804 @deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto})
1805 @standards{BSD, netdb.h}
1806 @safety{@prelim{}@mtunsafe{@mtasurace{:servbyport} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1807 @c getservbyport =~ getservbyname @mtasurace:servbyport @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1808 @c  libc_lock_lock dup @asulock @aculock
1809 @c  malloc dup @ascuheap @acsmem
1810 @c  getservbyport_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1811 @c  realloc dup @ascuheap @acsmem
1812 @c  free dup @ascuheap @acsmem
1813 @c  libc_lock_unlock dup @aculock
1815 @c getservbyport_r =~ getservbyname_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1816 @c  nscd_getservbyport_r @ascuheap @acsfd @acsmem
1817 @c   nscd_getserv_r dup @ascuheap @acsfd @acsmem
1818 @c  nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1819 @c  *fct.l -> _nss_*_getservbyport_r @ascuplugin
1820 @c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1821 The @code{getservbyport} function returns information about the
1822 service at port @var{port} using protocol @var{proto}.  If it can't
1823 find such a service, it returns a null pointer.
1824 @end deftypefun
1826 @noindent
1827 You can also scan the services database using @code{setservent},
1828 @code{getservent} and @code{endservent}.  Be careful when using these
1829 functions because they are not reentrant.
1831 @deftypefun void setservent (int @var{stayopen})
1832 @standards{BSD, netdb.h}
1833 @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1834 @c setservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1835 @c  libc_lock_lock dup @asulock @aculock
1836 @c  nss_setent(nss_services_lookup2) @mtasurace:servenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1837 @c   setup(nss_services_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1838 @c    *lookup_fct = nss_services_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1839 @c    nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1840 @c   *fct.f @mtasurace:servent @ascuplugin
1841 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1842 @c  libc_lock_unlock dup @aculock
1843 This function opens the services database to begin scanning it.
1845 If the @var{stayopen} argument is nonzero, this sets a flag so that
1846 subsequent calls to @code{getservbyname} or @code{getservbyport} will
1847 not close the database (as they usually would).  This makes for more
1848 efficiency if you call those functions several times, by avoiding
1849 reopening the database for each call.
1850 @end deftypefun
1852 @deftypefun {struct servent *} getservent (void)
1853 @standards{BSD, netdb.h}
1854 @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtasurace{:serventbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1855 @c getservent @mtasurace:servent @mtasurace:serventbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1856 @c  libc_lock_lock dup @asulock @aculock
1857 @c  nss_getent(getservent_r) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1858 @c   malloc dup @ascuheap @acsmem
1859 @c   *func = getservent_r dup @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1860 @c   realloc dup @ascuheap @acsmem
1861 @c   free dup @ascuheap @acsmem
1862 @c  libc_lock_unlock dup @aculock
1864 @c getservent_r @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1865 @c  libc_lock_lock dup @asulock @aculock
1866 @c  nss_getent_r(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1867 @c   setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1868 @c   *fct.f @mtasurace:servent @ascuplugin
1869 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1870 @c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1871 @c   *sfct.f @mtasurace:servent @ascuplugin
1872 @c  libc_lock_unlock dup @aculock
1873 This function returns the next entry in the services database.  If
1874 there are no more entries, it returns a null pointer.
1875 @end deftypefun
1877 @deftypefun void endservent (void)
1878 @standards{BSD, netdb.h}
1879 @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1880 @c endservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1881 @c  libc_lock_lock @asulock @aculock
1882 @c  nss_endent(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1883 @c   setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1884 @c   *fct.f @mtasurace:servent @ascuplugin
1885 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
1886 @c  libc_lock_unlock @aculock
1887 This function closes the services database.
1888 @end deftypefun
1890 @node Byte Order
1891 @subsection Byte Order Conversion
1892 @cindex byte order conversion, for socket
1893 @cindex converting byte order
1895 @cindex big-endian
1896 @cindex little-endian
1897 Different kinds of computers use different conventions for the
1898 ordering of bytes within a word.  Some computers put the most
1899 significant byte within a word first (this is called ``big-endian''
1900 order), and others put it last (``little-endian'' order).
1902 @cindex network byte order
1903 So that machines with different byte order conventions can
1904 communicate, the Internet protocols specify a canonical byte order
1905 convention for data transmitted over the network.  This is known
1906 as @dfn{network byte order}.
1908 When establishing an Internet socket connection, you must make sure that
1909 the data in the @code{sin_port} and @code{sin_addr} members of the
1910 @code{sockaddr_in} structure are represented in network byte order.
1911 If you are encoding integer data in the messages sent through the
1912 socket, you should convert this to network byte order too.  If you don't
1913 do this, your program may fail when running on or talking to other kinds
1914 of machines.
1916 If you use @code{getservbyname} and @code{gethostbyname} or
1917 @code{inet_addr} to get the port number and host address, the values are
1918 already in network byte order, and you can copy them directly into
1919 the @code{sockaddr_in} structure.
1921 Otherwise, you have to convert the values explicitly.  Use @code{htons}
1922 and @code{ntohs} to convert values for the @code{sin_port} member.  Use
1923 @code{htonl} and @code{ntohl} to convert IPv4 addresses for the
1924 @code{sin_addr} member.  (Remember, @code{struct in_addr} is equivalent
1925 to @code{uint32_t}.)  These functions are declared in
1926 @file{netinet/in.h}.
1927 @pindex netinet/in.h
1929 @deftypefun {uint16_t} htons (uint16_t @var{hostshort})
1930 @standards{BSD, netinet/in.h}
1931 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1932 @c htons ok
1933 @c  bswap_16 ok
1934 @c   bswap_constant_16 ok
1936 This function converts the @code{uint16_t} integer @var{hostshort} from
1937 host byte order to network byte order.
1938 @end deftypefun
1940 @deftypefun {uint16_t} ntohs (uint16_t @var{netshort})
1941 @standards{BSD, netinet/in.h}
1942 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1943 @c Alias to htons.
1944 This function converts the @code{uint16_t} integer @var{netshort} from
1945 network byte order to host byte order.
1946 @end deftypefun
1948 @deftypefun {uint32_t} htonl (uint32_t @var{hostlong})
1949 @standards{BSD, netinet/in.h}
1950 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1951 @c htonl ok
1952 @c  bswap_32 dup ok
1953 This function converts the @code{uint32_t} integer @var{hostlong} from
1954 host byte order to network byte order.
1956 This is used for IPv4 Internet addresses.
1957 @end deftypefun
1959 @deftypefun {uint32_t} ntohl (uint32_t @var{netlong})
1960 @standards{BSD, netinet/in.h}
1961 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1962 @c Alias to htonl.
1963 This function converts the @code{uint32_t} integer @var{netlong} from
1964 network byte order to host byte order.
1966 This is used for IPv4 Internet addresses.
1967 @end deftypefun
1969 @node Protocols Database
1970 @subsection Protocols Database
1971 @cindex protocols database
1973 The communications protocol used with a socket controls low-level
1974 details of how data are exchanged.  For example, the protocol implements
1975 things like checksums to detect errors in transmissions, and routing
1976 instructions for messages.  Normal user programs have little reason to
1977 mess with these details directly.
1979 @cindex TCP (Internet protocol)
1980 The default communications protocol for the Internet namespace depends on
1981 the communication style.  For stream communication, the default is TCP
1982 (``transmission control protocol'').  For datagram communication, the
1983 default is UDP (``user datagram protocol'').  For reliable datagram
1984 communication, the default is RDP (``reliable datagram protocol'').
1985 You should nearly always use the default.
1987 @pindex /etc/protocols
1988 Internet protocols are generally specified by a name instead of a
1989 number.  The network protocols that a host knows about are stored in a
1990 database.  This is usually either derived from the file
1991 @file{/etc/protocols}, or it may be an equivalent provided by a name
1992 server.  You look up the protocol number associated with a named
1993 protocol in the database using the @code{getprotobyname} function.
1995 Here are detailed descriptions of the utilities for accessing the
1996 protocols database.  These are declared in @file{netdb.h}.
1997 @pindex netdb.h
1999 @deftp {Data Type} {struct protoent}
2000 @standards{BSD, netdb.h}
2001 This data type is used to represent entries in the network protocols
2002 database.  It has the following members:
2004 @table @code
2005 @item char *p_name
2006 This is the official name of the protocol.
2008 @item char **p_aliases
2009 These are alternate names for the protocol, specified as an array of
2010 strings.  The last element of the array is a null pointer.
2012 @item int p_proto
2013 This is the protocol number (in host byte order); use this member as the
2014 @var{protocol} argument to @code{socket}.
2015 @end table
2016 @end deftp
2018 You can use @code{getprotobyname} and @code{getprotobynumber} to search
2019 the protocols database for a specific protocol.  The information is
2020 returned in a statically-allocated structure; you must copy the
2021 information if you need to save it across calls.
2023 @deftypefun {struct protoent *} getprotobyname (const char *@var{name})
2024 @standards{BSD, netdb.h}
2025 @safety{@prelim{}@mtunsafe{@mtasurace{:protobyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
2026 @c getprotobyname =~ getpwuid @mtasurace:protobyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2027 @c  libc_lock_lock dup @asulock @aculock
2028 @c  malloc dup @ascuheap @acsmem
2029 @c  getprotobyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2030 @c  realloc dup @ascuheap @acsmem
2031 @c  free dup @ascuheap @acsmem
2032 @c  libc_lock_unlock dup @aculock
2034 @c getprotobyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2035 @c   no nscd support
2036 @c  nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2037 @c  *fct.l -> _nss_*_getprotobyname_r @ascuplugin
2038 @c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2039 The @code{getprotobyname} function returns information about the
2040 network protocol named @var{name}.  If there is no such protocol, it
2041 returns a null pointer.
2042 @end deftypefun
2044 @deftypefun {struct protoent *} getprotobynumber (int @var{protocol})
2045 @standards{BSD, netdb.h}
2046 @safety{@prelim{}@mtunsafe{@mtasurace{:protobynumber} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
2047 @c getprotobynumber =~ getpwuid @mtasurace:protobynumber @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2048 @c  libc_lock_lock dup @asulock @aculock
2049 @c  malloc dup @ascuheap @acsmem
2050 @c  getprotobynumber_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2051 @c  realloc dup @ascuheap @acsmem
2052 @c  free dup @ascuheap @acsmem
2053 @c  libc_lock_unlock dup @aculock
2055 @c getprotobynumber_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2056 @c   no nscd support
2057 @c  nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2058 @c  *fct.l -> _nss_*_getprotobynumber_r @ascuplugin
2059 @c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2060 The @code{getprotobynumber} function returns information about the
2061 network protocol with number @var{protocol}.  If there is no such
2062 protocol, it returns a null pointer.
2063 @end deftypefun
2065 You can also scan the whole protocols database one protocol at a time by
2066 using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}.
2067 Be careful when using these functions because they are not reentrant.
2069 @deftypefun void setprotoent (int @var{stayopen})
2070 @standards{BSD, netdb.h}
2071 @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
2072 @c setprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2073 @c  libc_lock_lock dup @asulock @aculock
2074 @c  nss_setent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2075 @c   setup(nss_protocols_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2076 @c    *lookup_fct = nss_protocols_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2077 @c    nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2078 @c   *fct.f @mtasurace:protoent @ascuplugin
2079 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2080 @c  libc_lock_unlock dup @aculock
2081 This function opens the protocols database to begin scanning it.
2083 If the @var{stayopen} argument is nonzero, this sets a flag so that
2084 subsequent calls to @code{getprotobyname} or @code{getprotobynumber} will
2085 not close the database (as they usually would).  This makes for more
2086 efficiency if you call those functions several times, by avoiding
2087 reopening the database for each call.
2088 @end deftypefun
2090 @deftypefun {struct protoent *} getprotoent (void)
2091 @standards{BSD, netdb.h}
2092 @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtasurace{:protoentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
2093 @c getprotoent @mtasurace:protoent @mtasurace:protoentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2094 @c  libc_lock_lock dup @asulock @aculock
2095 @c  nss_getent(getprotoent_r) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2096 @c   malloc dup @ascuheap @acsmem
2097 @c   *func = getprotoent_r dup @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2098 @c   realloc dup @ascuheap @acsmem
2099 @c   free dup @ascuheap @acsmem
2100 @c  libc_lock_unlock dup @aculock
2102 @c getprotoent_r @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2103 @c  libc_lock_lock dup @asulock @aculock
2104 @c  nss_getent_r(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2105 @c   setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2106 @c   *fct.f @mtasurace:servent @ascuplugin
2107 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2108 @c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2109 @c   *sfct.f @mtasurace:protoent @ascuplugin
2110 @c  libc_lock_unlock dup @aculock
2111 This function returns the next entry in the protocols database.  It
2112 returns a null pointer if there are no more entries.
2113 @end deftypefun
2115 @deftypefun void endprotoent (void)
2116 @standards{BSD, netdb.h}
2117 @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
2118 @c endprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2119 @c  libc_lock_lock @asulock @aculock
2120 @c  nss_endent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2121 @c   setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2122 @c   *fct.f @mtasurace:protoent @ascuplugin
2123 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
2124 @c  libc_lock_unlock @aculock
2125 This function closes the protocols database.
2126 @end deftypefun
2128 @node Inet Example
2129 @subsection Internet Socket Example
2131 Here is an example showing how to create and name a socket in the
2132 Internet namespace.  The newly created socket exists on the machine that
2133 the program is running on.  Rather than finding and using the machine's
2134 Internet address, this example specifies @code{INADDR_ANY} as the host
2135 address; the system replaces that with the machine's actual address.
2137 @smallexample
2138 @include mkisock.c.texi
2139 @end smallexample
2141 Here is another example, showing how you can fill in a @code{sockaddr_in}
2142 structure, given a host name string and a port number:
2144 @smallexample
2145 @include isockad.c.texi
2146 @end smallexample
2148 @node Misc Namespaces
2149 @section Other Namespaces
2151 @vindex PF_NS
2152 @vindex PF_ISO
2153 @vindex PF_CCITT
2154 @vindex PF_IMPLINK
2155 @vindex PF_ROUTE
2156 Certain other namespaces and associated protocol families are supported
2157 but not documented yet because they are not often used.  @code{PF_NS}
2158 refers to the Xerox Network Software protocols.  @code{PF_ISO} stands
2159 for Open Systems Interconnect.  @code{PF_CCITT} refers to protocols from
2160 CCITT.  @file{socket.h} defines these symbols and others naming protocols
2161 not actually implemented.
2163 @code{PF_IMPLINK} is used for communicating between hosts and Internet
2164 Message Processors.  For information on this and @code{PF_ROUTE}, an
2165 occasionally-used local area routing protocol, see the GNU Hurd Manual
2166 (to appear in the future).
2168 @node Open/Close Sockets
2169 @section Opening and Closing Sockets
2171 This section describes the actual library functions for opening and
2172 closing sockets.  The same functions work for all namespaces and
2173 connection styles.
2175 @menu
2176 * Creating a Socket::           How to open a socket.
2177 * Closing a Socket::            How to close a socket.
2178 * Socket Pairs::                These are created like pipes.
2179 @end menu
2181 @node Creating a Socket
2182 @subsection Creating a Socket
2183 @cindex creating a socket
2184 @cindex socket, creating
2185 @cindex opening a socket
2187 The primitive for creating a socket is the @code{socket} function,
2188 declared in @file{sys/socket.h}.
2189 @pindex sys/socket.h
2191 @deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol})
2192 @standards{BSD, sys/socket.h}
2193 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
2194 This function creates a socket and specifies communication style
2195 @var{style}, which should be one of the socket styles listed in
2196 @ref{Communication Styles}.  The @var{namespace} argument specifies
2197 the namespace; it must be @code{PF_LOCAL} (@pxref{Local Namespace}) or
2198 @code{PF_INET} (@pxref{Internet Namespace}).  @var{protocol}
2199 designates the specific protocol (@pxref{Socket Concepts}); zero is
2200 usually right for @var{protocol}.
2202 The return value from @code{socket} is the file descriptor for the new
2203 socket, or @code{-1} in case of error.  The following @code{errno} error
2204 conditions are defined for this function:
2206 @table @code
2207 @item EPROTONOSUPPORT
2208 The @var{protocol} or @var{style} is not supported by the
2209 @var{namespace} specified.
2211 @item EMFILE
2212 The process already has too many file descriptors open.
2214 @item ENFILE
2215 The system already has too many file descriptors open.
2217 @item EACCES
2218 The process does not have the privilege to create a socket of the specified
2219 @var{style} or @var{protocol}.
2221 @item ENOBUFS
2222 The system ran out of internal buffer space.
2223 @end table
2225 The file descriptor returned by the @code{socket} function supports both
2226 read and write operations.  However, like pipes, sockets do not support file
2227 positioning operations.
2228 @end deftypefun
2230 For examples of how to call the @code{socket} function,
2231 see @ref{Local Socket Example}, or @ref{Inet Example}.
2234 @node Closing a Socket
2235 @subsection Closing a Socket
2236 @cindex socket, closing
2237 @cindex closing a socket
2238 @cindex shutting down a socket
2239 @cindex socket shutdown
2241 When you have finished using a socket, you can simply close its
2242 file descriptor with @code{close}; see @ref{Opening and Closing Files}.
2243 If there is still data waiting to be transmitted over the connection,
2244 normally @code{close} tries to complete this transmission.  You
2245 can control this behavior using the @code{SO_LINGER} socket option to
2246 specify a timeout period; see @ref{Socket Options}.
2248 @pindex sys/socket.h
2249 You can also shut down only reception or transmission on a
2250 connection by calling @code{shutdown}, which is declared in
2251 @file{sys/socket.h}.
2253 @deftypefun int shutdown (int @var{socket}, int @var{how})
2254 @standards{BSD, sys/socket.h}
2255 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2256 The @code{shutdown} function shuts down the connection of socket
2257 @var{socket}.  The argument @var{how} specifies what action to
2258 perform:
2260 @table @code
2261 @item 0
2262 Stop receiving data for this socket.  If further data arrives,
2263 reject it.
2265 @item 1
2266 Stop trying to transmit data from this socket.  Discard any data
2267 waiting to be sent.  Stop looking for acknowledgement of data already
2268 sent; don't retransmit it if it is lost.
2270 @item 2
2271 Stop both reception and transmission.
2272 @end table
2274 The return value is @code{0} on success and @code{-1} on failure.  The
2275 following @code{errno} error conditions are defined for this function:
2277 @table @code
2278 @item EBADF
2279 @var{socket} is not a valid file descriptor.
2281 @item ENOTSOCK
2282 @var{socket} is not a socket.
2284 @item ENOTCONN
2285 @var{socket} is not connected.
2286 @end table
2287 @end deftypefun
2289 @node Socket Pairs
2290 @subsection Socket Pairs
2291 @cindex creating a socket pair
2292 @cindex socket pair
2293 @cindex opening a socket pair
2295 @pindex sys/socket.h
2296 A @dfn{socket pair} consists of a pair of connected (but unnamed)
2297 sockets.  It is very similar to a pipe and is used in much the same
2298 way.  Socket pairs are created with the @code{socketpair} function,
2299 declared in @file{sys/socket.h}.  A socket pair is much like a pipe; the
2300 main difference is that the socket pair is bidirectional, whereas the
2301 pipe has one input-only end and one output-only end (@pxref{Pipes and
2302 FIFOs}).
2304 @deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]})
2305 @standards{BSD, sys/socket.h}
2306 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
2307 This function creates a socket pair, returning the file descriptors in
2308 @code{@var{filedes}[0]} and @code{@var{filedes}[1]}.  The socket pair
2309 is a full-duplex communications channel, so that both reading and writing
2310 may be performed at either end.
2312 The @var{namespace}, @var{style} and @var{protocol} arguments are
2313 interpreted as for the @code{socket} function.  @var{style} should be
2314 one of the communication styles listed in @ref{Communication Styles}.
2315 The @var{namespace} argument specifies the namespace, which must be
2316 @code{AF_LOCAL} (@pxref{Local Namespace}); @var{protocol} specifies the
2317 communications protocol, but zero is the only meaningful value.
2319 If @var{style} specifies a connectionless communication style, then
2320 the two sockets you get are not @emph{connected}, strictly speaking,
2321 but each of them knows the other as the default destination address,
2322 so they can send packets to each other.
2324 The @code{socketpair} function returns @code{0} on success and @code{-1}
2325 on failure.  The following @code{errno} error conditions are defined
2326 for this function:
2328 @table @code
2329 @item EMFILE
2330 The process has too many file descriptors open.
2332 @item EAFNOSUPPORT
2333 The specified namespace is not supported.
2335 @item EPROTONOSUPPORT
2336 The specified protocol is not supported.
2338 @item EOPNOTSUPP
2339 The specified protocol does not support the creation of socket pairs.
2340 @end table
2341 @end deftypefun
2343 @node Connections
2344 @section Using Sockets with Connections
2346 @cindex connection
2347 @cindex client
2348 @cindex server
2349 The most common communication styles involve making a connection to a
2350 particular other socket, and then exchanging data with that socket
2351 over and over.  Making a connection is asymmetric; one side (the
2352 @dfn{client}) acts to request a connection, while the other side (the
2353 @dfn{server}) makes a socket and waits for the connection request.
2355 @iftex
2356 @itemize @bullet
2357 @item
2358 @ref{Connecting}, describes what the client program must do to
2359 initiate a connection with a server.
2361 @item
2362 @ref{Listening} and @ref{Accepting Connections} describe what the
2363 server program must do to wait for and act upon connection requests
2364 from clients.
2366 @item
2367 @ref{Transferring Data}, describes how data are transferred through the
2368 connected socket.
2369 @end itemize
2370 @end iftex
2372 @menu
2373 * Connecting::               What the client program must do.
2374 * Listening::                How a server program waits for requests.
2375 * Accepting Connections::    What the server does when it gets a request.
2376 * Who is Connected::         Getting the address of the
2377                                 other side of a connection.
2378 * Transferring Data::        How to send and receive data.
2379 * Byte Stream Example::      An example program: a client for communicating
2380                               over a byte stream socket in the Internet namespace.
2381 * Server Example::           A corresponding server program.
2382 * Out-of-Band Data::         This is an advanced feature.
2383 @end menu
2385 @node Connecting
2386 @subsection Making a Connection
2387 @cindex connecting a socket
2388 @cindex socket, connecting
2389 @cindex socket, initiating a connection
2390 @cindex socket, client actions
2392 In making a connection, the client makes a connection while the server
2393 waits for and accepts the connection.  Here we discuss what the client
2394 program must do with the @code{connect} function, which is declared in
2395 @file{sys/socket.h}.
2397 @deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
2398 @standards{BSD, sys/socket.h}
2399 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2400 The @code{connect} function initiates a connection from the socket
2401 with file descriptor @var{socket} to the socket whose address is
2402 specified by the @var{addr} and @var{length} arguments.  (This socket
2403 is typically on another machine, and it must be already set up as a
2404 server.)  @xref{Socket Addresses}, for information about how these
2405 arguments are interpreted.
2407 Normally, @code{connect} waits until the server responds to the request
2408 before it returns.  You can set nonblocking mode on the socket
2409 @var{socket} to make @code{connect} return immediately without waiting
2410 for the response.  @xref{File Status Flags}, for information about
2411 nonblocking mode.
2412 @c !!! how do you tell when it has finished connecting?  I suspect the
2413 @c way you do it is select for writing.
2415 The normal return value from @code{connect} is @code{0}.  If an error
2416 occurs, @code{connect} returns @code{-1}.  The following @code{errno}
2417 error conditions are defined for this function:
2419 @table @code
2420 @item EBADF
2421 The socket @var{socket} is not a valid file descriptor.
2423 @item ENOTSOCK
2424 File descriptor @var{socket} is not a socket.
2426 @item EADDRNOTAVAIL
2427 The specified address is not available on the remote machine.
2429 @item EAFNOSUPPORT
2430 The namespace of the @var{addr} is not supported by this socket.
2432 @item EISCONN
2433 The socket @var{socket} is already connected.
2435 @item ETIMEDOUT
2436 The attempt to establish the connection timed out.
2438 @item ECONNREFUSED
2439 The server has actively refused to establish the connection.
2441 @item ENETUNREACH
2442 The network of the given @var{addr} isn't reachable from this host.
2444 @item EADDRINUSE
2445 The socket address of the given @var{addr} is already in use.
2447 @item EINPROGRESS
2448 The socket @var{socket} is non-blocking and the connection could not be
2449 established immediately.  You can determine when the connection is
2450 completely established with @code{select}; @pxref{Waiting for I/O}.
2451 Another @code{connect} call on the same socket, before the connection is
2452 completely established, will fail with @code{EALREADY}.
2454 @item EALREADY
2455 The socket @var{socket} is non-blocking and already has a pending
2456 connection in progress (see @code{EINPROGRESS} above).
2457 @end table
2459 This function is defined as a cancellation point in multi-threaded
2460 programs, so one has to be prepared for this and make sure that
2461 allocated resources (like memory, file descriptors, semaphores or
2462 whatever) are freed even if the thread is canceled.
2463 @c @xref{pthread_cleanup_push}, for a method how to do this.
2464 @end deftypefun
2466 @node Listening
2467 @subsection Listening for Connections
2468 @cindex listening (sockets)
2469 @cindex sockets, server actions
2470 @cindex sockets, listening
2472 Now let us consider what the server process must do to accept
2473 connections on a socket.  First it must use the @code{listen} function
2474 to enable connection requests on the socket, and then accept each
2475 incoming connection with a call to @code{accept} (@pxref{Accepting
2476 Connections}).  Once connection requests are enabled on a server socket,
2477 the @code{select} function reports when the socket has a connection
2478 ready to be accepted (@pxref{Waiting for I/O}).
2480 The @code{listen} function is not allowed for sockets using
2481 connectionless communication styles.
2483 You can write a network server that does not even start running until a
2484 connection to it is requested.  @xref{Inetd Servers}.
2486 In the Internet namespace, there are no special protection mechanisms
2487 for controlling access to a port; any process on any machine
2488 can make a connection to your server.  If you want to restrict access to
2489 your server, make it examine the addresses associated with connection
2490 requests or implement some other handshaking or identification
2491 protocol.
2493 In the local namespace, the ordinary file protection bits control who has
2494 access to connect to the socket.
2496 @deftypefun int listen (int @var{socket}, int @var{n})
2497 @standards{BSD, sys/socket.h}
2498 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
2499 The @code{listen} function enables the socket @var{socket} to accept
2500 connections, thus making it a server socket.
2502 The argument @var{n} specifies the length of the queue for pending
2503 connections.  When the queue fills, new clients attempting to connect
2504 fail with @code{ECONNREFUSED} until the server calls @code{accept} to
2505 accept a connection from the queue.
2507 The @code{listen} function returns @code{0} on success and @code{-1}
2508 on failure.  The following @code{errno} error conditions are defined
2509 for this function:
2511 @table @code
2512 @item EBADF
2513 The argument @var{socket} is not a valid file descriptor.
2515 @item ENOTSOCK
2516 The argument @var{socket} is not a socket.
2518 @item EOPNOTSUPP
2519 The socket @var{socket} does not support this operation.
2520 @end table
2521 @end deftypefun
2523 @node Accepting Connections
2524 @subsection Accepting Connections
2525 @cindex sockets, accepting connections
2526 @cindex accepting connections
2528 When a server receives a connection request, it can complete the
2529 connection by accepting the request.  Use the function @code{accept}
2530 to do this.
2532 A socket that has been established as a server can accept connection
2533 requests from multiple clients.  The server's original socket
2534 @emph{does not become part of the connection}; instead, @code{accept}
2535 makes a new socket which participates in the connection.
2536 @code{accept} returns the descriptor for this socket.  The server's
2537 original socket remains available for listening for further connection
2538 requests.
2540 The number of pending connection requests on a server socket is finite.
2541 If connection requests arrive from clients faster than the server can
2542 act upon them, the queue can fill up and additional requests are refused
2543 with an @code{ECONNREFUSED} error.  You can specify the maximum length of
2544 this queue as an argument to the @code{listen} function, although the
2545 system may also impose its own internal limit on the length of this
2546 queue.
2548 @deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length_ptr})
2549 @standards{BSD, sys/socket.h}
2550 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
2551 This function is used to accept a connection request on the server
2552 socket @var{socket}.
2554 The @code{accept} function waits if there are no connections pending,
2555 unless the socket @var{socket} has nonblocking mode set.  (You can use
2556 @code{select} to wait for a pending connection, with a nonblocking
2557 socket.)  @xref{File Status Flags}, for information about nonblocking
2558 mode.
2560 The @var{addr} and @var{length-ptr} arguments are used to return
2561 information about the name of the client socket that initiated the
2562 connection.  @xref{Socket Addresses}, for information about the format
2563 of the information.
2565 Accepting a connection does not make @var{socket} part of the
2566 connection.  Instead, it creates a new socket which becomes
2567 connected.  The normal return value of @code{accept} is the file
2568 descriptor for the new socket.
2570 After @code{accept}, the original socket @var{socket} remains open and
2571 unconnected, and continues listening until you close it.  You can
2572 accept further connections with @var{socket} by calling @code{accept}
2573 again.
2575 If an error occurs, @code{accept} returns @code{-1}.  The following
2576 @code{errno} error conditions are defined for this function:
2578 @table @code
2579 @item EBADF
2580 The @var{socket} argument is not a valid file descriptor.
2582 @item ENOTSOCK
2583 The descriptor @var{socket} argument is not a socket.
2585 @item EOPNOTSUPP
2586 The descriptor @var{socket} does not support this operation.
2588 @item EWOULDBLOCK
2589 @var{socket} has nonblocking mode set, and there are no pending
2590 connections immediately available.
2591 @end table
2593 This function is defined as a cancellation point in multi-threaded
2594 programs, so one has to be prepared for this and make sure that
2595 allocated resources (like memory, file descriptors, semaphores or
2596 whatever) are freed even if the thread is canceled.
2597 @c @xref{pthread_cleanup_push}, for a method how to do this.
2598 @end deftypefun
2600 The @code{accept} function is not allowed for sockets using
2601 connectionless communication styles.
2603 @node Who is Connected
2604 @subsection Who is Connected to Me?
2606 @deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
2607 @standards{BSD, sys/socket.h}
2608 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2609 The @code{getpeername} function returns the address of the socket that
2610 @var{socket} is connected to; it stores the address in the memory space
2611 specified by @var{addr} and @var{length-ptr}.  It stores the length of
2612 the address in @code{*@var{length-ptr}}.
2614 @xref{Socket Addresses}, for information about the format of the
2615 address.  In some operating systems, @code{getpeername} works only for
2616 sockets in the Internet domain.
2618 The return value is @code{0} on success and @code{-1} on error.  The
2619 following @code{errno} error conditions are defined for this function:
2621 @table @code
2622 @item EBADF
2623 The argument @var{socket} is not a valid file descriptor.
2625 @item ENOTSOCK
2626 The descriptor @var{socket} is not a socket.
2628 @item ENOTCONN
2629 The socket @var{socket} is not connected.
2631 @item ENOBUFS
2632 There are not enough internal buffers available.
2633 @end table
2634 @end deftypefun
2637 @node Transferring Data
2638 @subsection Transferring Data
2639 @cindex reading from a socket
2640 @cindex writing to a socket
2642 Once a socket has been connected to a peer, you can use the ordinary
2643 @code{read} and @code{write} operations (@pxref{I/O Primitives}) to
2644 transfer data.  A socket is a two-way communications channel, so read
2645 and write operations can be performed at either end.
2647 There are also some I/O modes that are specific to socket operations.
2648 In order to specify these modes, you must use the @code{recv} and
2649 @code{send} functions instead of the more generic @code{read} and
2650 @code{write} functions.  The @code{recv} and @code{send} functions take
2651 an additional argument which you can use to specify various flags to
2652 control special I/O modes.  For example, you can specify the
2653 @code{MSG_OOB} flag to read or write out-of-band data, the
2654 @code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag
2655 to control inclusion of routing information on output.
2657 @menu
2658 * Sending Data::                Sending data with @code{send}.
2659 * Receiving Data::              Reading data with @code{recv}.
2660 * Socket Data Options::         Using @code{send} and @code{recv}.
2661 @end menu
2663 @node Sending Data
2664 @subsubsection Sending Data
2666 @pindex sys/socket.h
2667 The @code{send} function is declared in the header file
2668 @file{sys/socket.h}.  If your @var{flags} argument is zero, you can just
2669 as well use @code{write} instead of @code{send}; see @ref{I/O
2670 Primitives}.  If the socket was connected but the connection has broken,
2671 you get a @code{SIGPIPE} signal for any use of @code{send} or
2672 @code{write} (@pxref{Miscellaneous Signals}).
2674 @deftypefun ssize_t send (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags})
2675 @standards{BSD, sys/socket.h}
2676 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2677 The @code{send} function is like @code{write}, but with the additional
2678 flags @var{flags}.  The possible values of @var{flags} are described
2679 in @ref{Socket Data Options}.
2681 This function returns the number of bytes transmitted, or @code{-1} on
2682 failure.  If the socket is nonblocking, then @code{send} (like
2683 @code{write}) can return after sending just part of the data.
2684 @xref{File Status Flags}, for information about nonblocking mode.
2686 Note, however, that a successful return value merely indicates that
2687 the message has been sent without error, not necessarily that it has
2688 been received without error.
2690 The following @code{errno} error conditions are defined for this function:
2692 @table @code
2693 @item EBADF
2694 The @var{socket} argument is not a valid file descriptor.
2696 @item EINTR
2697 The operation was interrupted by a signal before any data was sent.
2698 @xref{Interrupted Primitives}.
2700 @item ENOTSOCK
2701 The descriptor @var{socket} is not a socket.
2703 @item EMSGSIZE
2704 The socket type requires that the message be sent atomically, but the
2705 message is too large for this to be possible.
2707 @item EWOULDBLOCK
2708 Nonblocking mode has been set on the socket, and the write operation
2709 would block.  (Normally @code{send} blocks until the operation can be
2710 completed.)
2712 @item ENOBUFS
2713 There is not enough internal buffer space available.
2715 @item ENOTCONN
2716 You never connected this socket.
2718 @item EPIPE
2719 This socket was connected but the connection is now broken.  In this
2720 case, @code{send} generates a @code{SIGPIPE} signal first; if that
2721 signal is ignored or blocked, or if its handler returns, then
2722 @code{send} fails with @code{EPIPE}.
2723 @end table
2725 This function is defined as a cancellation point in multi-threaded
2726 programs, so one has to be prepared for this and make sure that
2727 allocated resources (like memory, file descriptors, semaphores or
2728 whatever) are freed even if the thread is canceled.
2729 @c @xref{pthread_cleanup_push}, for a method how to do this.
2730 @end deftypefun
2732 @node Receiving Data
2733 @subsubsection Receiving Data
2735 @pindex sys/socket.h
2736 The @code{recv} function is declared in the header file
2737 @file{sys/socket.h}.  If your @var{flags} argument is zero, you can
2738 just as well use @code{read} instead of @code{recv}; see @ref{I/O
2739 Primitives}.
2741 @deftypefun ssize_t recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags})
2742 @standards{BSD, sys/socket.h}
2743 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2744 The @code{recv} function is like @code{read}, but with the additional
2745 flags @var{flags}.  The possible values of @var{flags} are described
2746 in @ref{Socket Data Options}.
2748 If nonblocking mode is set for @var{socket}, and no data are available to
2749 be read, @code{recv} fails immediately rather than waiting.  @xref{File
2750 Status Flags}, for information about nonblocking mode.
2752 This function returns the number of bytes received, or @code{-1} on failure.
2753 The following @code{errno} error conditions are defined for this function:
2755 @table @code
2756 @item EBADF
2757 The @var{socket} argument is not a valid file descriptor.
2759 @item ENOTSOCK
2760 The descriptor @var{socket} is not a socket.
2762 @item EWOULDBLOCK
2763 Nonblocking mode has been set on the socket, and the read operation
2764 would block.  (Normally, @code{recv} blocks until there is input
2765 available to be read.)
2767 @item EINTR
2768 The operation was interrupted by a signal before any data was read.
2769 @xref{Interrupted Primitives}.
2771 @item ENOTCONN
2772 You never connected this socket.
2773 @end table
2775 This function is defined as a cancellation point in multi-threaded
2776 programs, so one has to be prepared for this and make sure that
2777 allocated resources (like memory, file descriptors, semaphores or
2778 whatever) are freed even if the thread is canceled.
2779 @c @xref{pthread_cleanup_push}, for a method how to do this.
2780 @end deftypefun
2782 @node Socket Data Options
2783 @subsubsection Socket Data Options
2785 @pindex sys/socket.h
2786 The @var{flags} argument to @code{send} and @code{recv} is a bit
2787 mask.  You can bitwise-OR the values of the following macros together
2788 to obtain a value for this argument.  All are defined in the header
2789 file @file{sys/socket.h}.
2791 @deftypevr Macro int MSG_OOB
2792 @standards{BSD, sys/socket.h}
2793 Send or receive out-of-band data.  @xref{Out-of-Band Data}.
2794 @end deftypevr
2796 @deftypevr Macro int MSG_PEEK
2797 @standards{BSD, sys/socket.h}
2798 Look at the data but don't remove it from the input queue.  This is
2799 only meaningful with input functions such as @code{recv}, not with
2800 @code{send}.
2801 @end deftypevr
2803 @deftypevr Macro int MSG_DONTROUTE
2804 @standards{BSD, sys/socket.h}
2805 Don't include routing information in the message.  This is only
2806 meaningful with output operations, and is usually only of interest for
2807 diagnostic or routing programs.  We don't try to explain it here.
2808 @end deftypevr
2810 @node Byte Stream Example
2811 @subsection Byte Stream Socket Example
2813 Here is an example client program that makes a connection for a byte
2814 stream socket in the Internet namespace.  It doesn't do anything
2815 particularly interesting once it has connected to the server; it just
2816 sends a text string to the server and exits.
2818 This program uses @code{init_sockaddr} to set up the socket address; see
2819 @ref{Inet Example}.
2821 @smallexample
2822 @include inetcli.c.texi
2823 @end smallexample
2825 @node Server Example
2826 @subsection Byte Stream Connection Server Example
2828 The server end is much more complicated.  Since we want to allow
2829 multiple clients to be connected to the server at the same time, it
2830 would be incorrect to wait for input from a single client by simply
2831 calling @code{read} or @code{recv}.  Instead, the right thing to do is
2832 to use @code{select} (@pxref{Waiting for I/O}) to wait for input on
2833 all of the open sockets.  This also allows the server to deal with
2834 additional connection requests.
2836 This particular server doesn't do anything interesting once it has
2837 gotten a message from a client.  It does close the socket for that
2838 client when it detects an end-of-file condition (resulting from the
2839 client shutting down its end of the connection).
2841 This program uses @code{make_socket} to set up the socket address; see
2842 @ref{Inet Example}.
2844 @smallexample
2845 @include inetsrv.c.texi
2846 @end smallexample
2848 @node Out-of-Band Data
2849 @subsection Out-of-Band Data
2851 @cindex out-of-band data
2852 @cindex high-priority data
2853 Streams with connections permit @dfn{out-of-band} data that is
2854 delivered with higher priority than ordinary data.  Typically the
2855 reason for sending out-of-band data is to send notice of an
2856 exceptional condition.  To send out-of-band data use
2857 @code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending
2858 Data}).
2860 Out-of-band data are received with higher priority because the
2861 receiving process need not read it in sequence; to read the next
2862 available out-of-band data, use @code{recv} with the @code{MSG_OOB}
2863 flag (@pxref{Receiving Data}).  Ordinary read operations do not read
2864 out-of-band data; they read only ordinary data.
2866 @cindex urgent socket condition
2867 When a socket finds that out-of-band data are on their way, it sends a
2868 @code{SIGURG} signal to the owner process or process group of the
2869 socket.  You can specify the owner using the @code{F_SETOWN} command
2870 to the @code{fcntl} function; see @ref{Interrupt Input}.  You must
2871 also establish a handler for this signal, as described in @ref{Signal
2872 Handling}, in order to take appropriate action such as reading the
2873 out-of-band data.
2875 Alternatively, you can test for pending out-of-band data, or wait
2876 until there is out-of-band data, using the @code{select} function; it
2877 can wait for an exceptional condition on the socket.  @xref{Waiting
2878 for I/O}, for more information about @code{select}.
2880 Notification of out-of-band data (whether with @code{SIGURG} or with
2881 @code{select}) indicates that out-of-band data are on the way; the data
2882 may not actually arrive until later.  If you try to read the
2883 out-of-band data before it arrives, @code{recv} fails with an
2884 @code{EWOULDBLOCK} error.
2886 Sending out-of-band data automatically places a ``mark'' in the stream
2887 of ordinary data, showing where in the sequence the out-of-band data
2888 ``would have been''.  This is useful when the meaning of out-of-band
2889 data is ``cancel everything sent so far''.  Here is how you can test,
2890 in the receiving process, whether any ordinary data was sent before
2891 the mark:
2893 @smallexample
2894 success = ioctl (socket, SIOCATMARK, &atmark);
2895 @end smallexample
2897 The @code{integer} variable @var{atmark} is set to a nonzero value if
2898 the socket's read pointer has reached the ``mark''.
2900 @c Posix  1.g specifies sockatmark for this ioctl.  sockatmark is not
2901 @c implemented yet.
2903 Here's a function to discard any ordinary data preceding the
2904 out-of-band mark:
2906 @smallexample
2908 discard_until_mark (int socket)
2910   while (1)
2911     @{
2912       /* @r{This is not an arbitrary limit; any size will do.}  */
2913       char buffer[1024];
2914       int atmark, success;
2916       /* @r{If we have reached the mark, return.}  */
2917       success = ioctl (socket, SIOCATMARK, &atmark);
2918       if (success < 0)
2919         perror ("ioctl");
2920       if (result)
2921         return;
2923       /* @r{Otherwise, read a bunch of ordinary data and discard it.}
2924          @r{This is guaranteed not to read past the mark}
2925          @r{if it starts before the mark.}  */
2926       success = read (socket, buffer, sizeof buffer);
2927       if (success < 0)
2928         perror ("read");
2929     @}
2931 @end smallexample
2933 If you don't want to discard the ordinary data preceding the mark, you
2934 may need to read some of it anyway, to make room in internal system
2935 buffers for the out-of-band data.  If you try to read out-of-band data
2936 and get an @code{EWOULDBLOCK} error, try reading some ordinary data
2937 (saving it so that you can use it when you want it) and see if that
2938 makes room.  Here is an example:
2940 @smallexample
2941 struct buffer
2943   char *buf;
2944   int size;
2945   struct buffer *next;
2948 /* @r{Read the out-of-band data from SOCKET and return it}
2949    @r{as a `struct buffer', which records the address of the data}
2950    @r{and its size.}
2952    @r{It may be necessary to read some ordinary data}
2953    @r{in order to make room for the out-of-band data.}
2954    @r{If so, the ordinary data are saved as a chain of buffers}
2955    @r{found in the `next' field of the value.}  */
2957 struct buffer *
2958 read_oob (int socket)
2960   struct buffer *tail = 0;
2961   struct buffer *list = 0;
2963   while (1)
2964     @{
2965       /* @r{This is an arbitrary limit.}
2966          @r{Does anyone know how to do this without a limit?}  */
2967 #define BUF_SZ 1024
2968       char *buf = (char *) xmalloc (BUF_SZ);
2969       int success;
2970       int atmark;
2972       /* @r{Try again to read the out-of-band data.}  */
2973       success = recv (socket, buf, BUF_SZ, MSG_OOB);
2974       if (success >= 0)
2975         @{
2976           /* @r{We got it, so return it.}  */
2977           struct buffer *link
2978             = (struct buffer *) xmalloc (sizeof (struct buffer));
2979           link->buf = buf;
2980           link->size = success;
2981           link->next = list;
2982           return link;
2983         @}
2985       /* @r{If we fail, see if we are at the mark.}  */
2986       success = ioctl (socket, SIOCATMARK, &atmark);
2987       if (success < 0)
2988         perror ("ioctl");
2989       if (atmark)
2990         @{
2991           /* @r{At the mark; skipping past more ordinary data cannot help.}
2992              @r{So just wait a while.}  */
2993           sleep (1);
2994           continue;
2995         @}
2997       /* @r{Otherwise, read a bunch of ordinary data and save it.}
2998          @r{This is guaranteed not to read past the mark}
2999          @r{if it starts before the mark.}  */
3000       success = read (socket, buf, BUF_SZ);
3001       if (success < 0)
3002         perror ("read");
3004       /* @r{Save this data in the buffer list.}  */
3005       @{
3006         struct buffer *link
3007           = (struct buffer *) xmalloc (sizeof (struct buffer));
3008         link->buf = buf;
3009         link->size = success;
3011         /* @r{Add the new link to the end of the list.}  */
3012         if (tail)
3013           tail->next = link;
3014         else
3015           list = link;
3016         tail = link;
3017       @}
3018     @}
3020 @end smallexample
3022 @node Datagrams
3023 @section Datagram Socket Operations
3025 @cindex datagram socket
3026 This section describes how to use communication styles that don't use
3027 connections (styles @code{SOCK_DGRAM} and @code{SOCK_RDM}).  Using
3028 these styles, you group data into packets and each packet is an
3029 independent communication.  You specify the destination for each
3030 packet individually.
3032 Datagram packets are like letters: you send each one independently
3033 with its own destination address, and they may arrive in the wrong
3034 order or not at all.
3036 The @code{listen} and @code{accept} functions are not allowed for
3037 sockets using connectionless communication styles.
3039 @menu
3040 * Sending Datagrams::    Sending packets on a datagram socket.
3041 * Receiving Datagrams::  Receiving packets on a datagram socket.
3042 * Datagram Example::     An example program: packets sent over a
3043                            datagram socket in the local namespace.
3044 * Example Receiver::     Another program, that receives those packets.
3045 @end menu
3047 @node Sending Datagrams
3048 @subsection Sending Datagrams
3049 @cindex sending a datagram
3050 @cindex transmitting datagrams
3051 @cindex datagrams, transmitting
3053 @pindex sys/socket.h
3054 The normal way of sending data on a datagram socket is by using the
3055 @code{sendto} function, declared in @file{sys/socket.h}.
3057 You can call @code{connect} on a datagram socket, but this only
3058 specifies a default destination for further data transmission on the
3059 socket.  When a socket has a default destination you can use
3060 @code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O
3061 Primitives}) to send a packet there.  You can cancel the default
3062 destination by calling @code{connect} using an address format of
3063 @code{AF_UNSPEC} in the @var{addr} argument.  @xref{Connecting}, for
3064 more information about the @code{connect} function.
3066 @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})
3067 @standards{BSD, sys/socket.h}
3068 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3069 The @code{sendto} function transmits the data in the @var{buffer}
3070 through the socket @var{socket} to the destination address specified
3071 by the @var{addr} and @var{length} arguments.  The @var{size} argument
3072 specifies the number of bytes to be transmitted.
3074 The @var{flags} are interpreted the same way as for @code{send}; see
3075 @ref{Socket Data Options}.
3077 The return value and error conditions are also the same as for
3078 @code{send}, but you cannot rely on the system to detect errors and
3079 report them; the most common error is that the packet is lost or there
3080 is no-one at the specified address to receive it, and the operating
3081 system on your machine usually does not know this.
3083 It is also possible for one call to @code{sendto} to report an error
3084 owing to a problem related to a previous call.
3086 This function is defined as a cancellation point in multi-threaded
3087 programs, so one has to be prepared for this and make sure that
3088 allocated resources (like memory, file descriptors, semaphores or
3089 whatever) are freed even if the thread is canceled.
3090 @c @xref{pthread_cleanup_push}, for a method how to do this.
3091 @end deftypefun
3093 @node Receiving Datagrams
3094 @subsection Receiving Datagrams
3095 @cindex receiving datagrams
3097 The @code{recvfrom} function reads a packet from a datagram socket and
3098 also tells you where it was sent from.  This function is declared in
3099 @file{sys/socket.h}.
3101 @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})
3102 @standards{BSD, sys/socket.h}
3103 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3104 The @code{recvfrom} function reads one packet from the socket
3105 @var{socket} into the buffer @var{buffer}.  The @var{size} argument
3106 specifies the maximum number of bytes to be read.
3108 If the packet is longer than @var{size} bytes, then you get the first
3109 @var{size} bytes of the packet and the rest of the packet is lost.
3110 There's no way to read the rest of the packet.  Thus, when you use a
3111 packet protocol, you must always know how long a packet to expect.
3113 The @var{addr} and @var{length-ptr} arguments are used to return the
3114 address where the packet came from.  @xref{Socket Addresses}.  For a
3115 socket in the local domain the address information won't be meaningful,
3116 since you can't read the address of such a socket (@pxref{Local
3117 Namespace}).  You can specify a null pointer as the @var{addr} argument
3118 if you are not interested in this information.
3120 The @var{flags} are interpreted the same way as for @code{recv}
3121 (@pxref{Socket Data Options}).  The return value and error conditions
3122 are also the same as for @code{recv}.
3124 This function is defined as a cancellation point in multi-threaded
3125 programs, so one has to be prepared for this and make sure that
3126 allocated resources (like memory, file descriptors, semaphores or
3127 whatever) are freed even if the thread is canceled.
3128 @c @xref{pthread_cleanup_push}, for a method how to do this.
3129 @end deftypefun
3131 You can use plain @code{recv} (@pxref{Receiving Data}) instead of
3132 @code{recvfrom} if you don't need to find out who sent the packet
3133 (either because you know where it should come from or because you
3134 treat all possible senders alike).  Even @code{read} can be used if
3135 you don't want to specify @var{flags} (@pxref{I/O Primitives}).
3137 @ignore
3138 @c sendmsg and recvmsg are like readv and writev in that they
3139 @c use a series of buffers.  It's not clear this is worth
3140 @c supporting or that we support them.
3141 @c !!! they can do more; it is hairy
3143 @deftp {Data Type} {struct msghdr}
3144 @standards{BSD, sys/socket.h}
3145 @end deftp
3147 @deftypefun ssize_t sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags})
3148 @standards{BSD, sys/socket.h}
3149 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3151 This function is defined as a cancellation point in multi-threaded
3152 programs, so one has to be prepared for this and make sure that
3153 allocated resources (like memory, files descriptors, semaphores or
3154 whatever) are freed even if the thread is cancel.
3155 @c @xref{pthread_cleanup_push}, for a method how to do this.
3156 @end deftypefun
3158 @deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
3159 @standards{BSD, sys/socket.h}
3160 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3162 This function is defined as a cancellation point in multi-threaded
3163 programs, so one has to be prepared for this and make sure that
3164 allocated resources (like memory, files descriptors, semaphores or
3165 whatever) are freed even if the thread is canceled.
3166 @c @xref{pthread_cleanup_push}, for a method how to do this.
3167 @end deftypefun
3168 @end ignore
3170 @node Datagram Example
3171 @subsection Datagram Socket Example
3173 Here is a set of example programs that send messages over a datagram
3174 stream in the local namespace.  Both the client and server programs use
3175 the @code{make_named_socket} function that was presented in @ref{Local
3176 Socket Example}, to create and name their sockets.
3178 First, here is the server program.  It sits in a loop waiting for
3179 messages to arrive, bouncing each message back to the sender.
3180 Obviously this isn't a particularly useful program, but it does show
3181 the general ideas involved.
3183 @smallexample
3184 @include filesrv.c.texi
3185 @end smallexample
3187 @node Example Receiver
3188 @subsection Example of Reading Datagrams
3190 Here is the client program corresponding to the server above.
3192 It sends a datagram to the server and then waits for a reply.  Notice
3193 that the socket for the client (as well as for the server) in this
3194 example has to be given a name.  This is so that the server can direct
3195 a message back to the client.  Since the socket has no associated
3196 connection state, the only way the server can do this is by
3197 referencing the name of the client.
3199 @smallexample
3200 @include filecli.c.texi
3201 @end smallexample
3203 Keep in mind that datagram socket communications are unreliable.  In
3204 this example, the client program waits indefinitely if the message
3205 never reaches the server or if the server's response never comes
3206 back.  It's up to the user running the program to kill and restart
3207 it if desired.  A more automatic solution could be to use
3208 @code{select} (@pxref{Waiting for I/O}) to establish a timeout period
3209 for the reply, and in case of timeout either re-send the message or
3210 shut down the socket and exit.
3212 @node Inetd
3213 @section The @code{inetd} Daemon
3215 We've explained above how to write a server program that does its own
3216 listening.  Such a server must already be running in order for anyone
3217 to connect to it.
3219 Another way to provide a service on an Internet port is to let the daemon
3220 program @code{inetd} do the listening.  @code{inetd} is a program that
3221 runs all the time and waits (using @code{select}) for messages on a
3222 specified set of ports.  When it receives a message, it accepts the
3223 connection (if the socket style calls for connections) and then forks a
3224 child process to run the corresponding server program.  You specify the
3225 ports and their programs in the file @file{/etc/inetd.conf}.
3227 @menu
3228 * Inetd Servers::
3229 * Configuring Inetd::
3230 @end menu
3232 @node Inetd Servers
3233 @subsection @code{inetd} Servers
3235 Writing a server program to be run by @code{inetd} is very simple.  Each time
3236 someone requests a connection to the appropriate port, a new server
3237 process starts.  The connection already exists at this time; the
3238 socket is available as the standard input descriptor and as the
3239 standard output descriptor (descriptors 0 and 1) in the server
3240 process.  Thus the server program can begin reading and writing data
3241 right away.  Often the program needs only the ordinary I/O facilities;
3242 in fact, a general-purpose filter program that knows nothing about
3243 sockets can work as a byte stream server run by @code{inetd}.
3245 You can also use @code{inetd} for servers that use connectionless
3246 communication styles.  For these servers, @code{inetd} does not try to accept
3247 a connection since no connection is possible.  It just starts the
3248 server program, which can read the incoming datagram packet from
3249 descriptor 0.  The server program can handle one request and then
3250 exit, or you can choose to write it to keep reading more requests
3251 until no more arrive, and then exit.  You must specify which of these
3252 two techniques the server uses when you configure @code{inetd}.
3254 @node Configuring Inetd
3255 @subsection Configuring @code{inetd}
3257 The file @file{/etc/inetd.conf} tells @code{inetd} which ports to listen to
3258 and what server programs to run for them.  Normally each entry in the
3259 file is one line, but you can split it onto multiple lines provided
3260 all but the first line of the entry start with whitespace.  Lines that
3261 start with @samp{#} are comments.
3263 Here are two standard entries in @file{/etc/inetd.conf}:
3265 @smallexample
3266 ftp     stream  tcp     nowait  root    /libexec/ftpd   ftpd
3267 talk    dgram   udp     wait    root    /libexec/talkd  talkd
3268 @end smallexample
3270 An entry has this format:
3272 @smallexample
3273 @var{service} @var{style} @var{protocol} @var{wait} @var{username} @var{program} @var{arguments}
3274 @end smallexample
3276 The @var{service} field says which service this program provides.  It
3277 should be the name of a service defined in @file{/etc/services}.
3278 @code{inetd} uses @var{service} to decide which port to listen on for
3279 this entry.
3281 The fields @var{style} and @var{protocol} specify the communication
3282 style and the protocol to use for the listening socket.  The style
3283 should be the name of a communication style, converted to lower case
3284 and with @samp{SOCK_} deleted---for example, @samp{stream} or
3285 @samp{dgram}.  @var{protocol} should be one of the protocols listed in
3286 @file{/etc/protocols}.  The typical protocol names are @samp{tcp} for
3287 byte stream connections and @samp{udp} for unreliable datagrams.
3289 The @var{wait} field should be either @samp{wait} or @samp{nowait}.
3290 Use @samp{wait} if @var{style} is a connectionless style and the
3291 server, once started, handles multiple requests as they come in.
3292 Use @samp{nowait} if @code{inetd} should start a new process for each message
3293 or request that comes in.  If @var{style} uses connections, then
3294 @var{wait} @strong{must} be @samp{nowait}.
3296 @var{user} is the user name that the server should run as.  @code{inetd} runs
3297 as root, so it can set the user ID of its children arbitrarily.  It's
3298 best to avoid using @samp{root} for @var{user} if you can; but some
3299 servers, such as Telnet and FTP, read a username and passphrase
3300 themselves.  These servers need to be root initially so they can log
3301 in as commanded by the data coming over the network.
3303 @var{program} together with @var{arguments} specifies the command to
3304 run to start the server.  @var{program} should be an absolute file
3305 name specifying the executable file to run.  @var{arguments} consists
3306 of any number of whitespace-separated words, which become the
3307 command-line arguments of @var{program}.  The first word in
3308 @var{arguments} is argument zero, which should by convention be the
3309 program name itself (sans directories).
3311 If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the
3312 file and obey its new contents by sending the @code{inetd} process the
3313 @code{SIGHUP} signal.  You'll have to use @code{ps} to determine the
3314 process ID of the @code{inetd} process as it is not fixed.
3316 @c !!! could document /etc/inetd.sec
3318 @node Socket Options
3319 @section Socket Options
3320 @cindex socket options
3322 This section describes how to read or set various options that modify
3323 the behavior of sockets and their underlying communications protocols.
3325 @cindex level, for socket options
3326 @cindex socket option level
3327 When you are manipulating a socket option, you must specify which
3328 @dfn{level} the option pertains to.  This describes whether the option
3329 applies to the socket interface, or to a lower-level communications
3330 protocol interface.
3332 @menu
3333 * Socket Option Functions::     The basic functions for setting and getting
3334                                  socket options.
3335 * Socket-Level Options::        Details of the options at the socket level.
3336 @end menu
3338 @node Socket Option Functions
3339 @subsection Socket Option Functions
3341 @pindex sys/socket.h
3342 Here are the functions for examining and modifying socket options.
3343 They are declared in @file{sys/socket.h}.
3345 @deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr})
3346 @standards{BSD, sys/socket.h}
3347 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3348 The @code{getsockopt} function gets information about the value of
3349 option @var{optname} at level @var{level} for socket @var{socket}.
3351 The option value is stored in the buffer that @var{optval} points to.
3352 Before the call, you should supply in @code{*@var{optlen-ptr}} the
3353 size of this buffer; on return, it contains the number of bytes of
3354 information actually stored in the buffer.
3356 Most options interpret the @var{optval} buffer as a single @code{int}
3357 value.
3359 The actual return value of @code{getsockopt} is @code{0} on success
3360 and @code{-1} on failure.  The following @code{errno} error conditions
3361 are defined:
3363 @table @code
3364 @item EBADF
3365 The @var{socket} argument is not a valid file descriptor.
3367 @item ENOTSOCK
3368 The descriptor @var{socket} is not a socket.
3370 @item ENOPROTOOPT
3371 The @var{optname} doesn't make sense for the given @var{level}.
3372 @end table
3373 @end deftypefun
3375 @deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, const void *@var{optval}, socklen_t @var{optlen})
3376 @standards{BSD, sys/socket.h}
3377 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3378 This function is used to set the socket option @var{optname} at level
3379 @var{level} for socket @var{socket}.  The value of the option is passed
3380 in the buffer @var{optval} of size @var{optlen}.
3382 @c Argh. -zw
3383 @iftex
3384 @hfuzz 6pt
3385 The return value and error codes for @code{setsockopt} are the same as
3386 for @code{getsockopt}.
3387 @end iftex
3388 @ifinfo
3389 The return value and error codes for @code{setsockopt} are the same as
3390 for @code{getsockopt}.
3391 @end ifinfo
3393 @end deftypefun
3395 @node Socket-Level Options
3396 @subsection Socket-Level Options
3398 @deftypevr Constant int SOL_SOCKET
3399 @standards{BSD, sys/socket.h}
3400 Use this constant as the @var{level} argument to @code{getsockopt} or
3401 @code{setsockopt} to manipulate the socket-level options described in
3402 this section.
3403 @end deftypevr
3405 @pindex sys/socket.h
3406 @noindent
3407 Here is a table of socket-level option names; all are defined in the
3408 header file @file{sys/socket.h}.
3410 @vtable @code
3411 @item SO_DEBUG
3412 @standards{BSD, sys/socket.h}
3413 @c Extra blank line here makes the table look better.
3415 This option toggles recording of debugging information in the underlying
3416 protocol modules.  The value has type @code{int}; a nonzero value means
3417 ``yes''.
3418 @c !!! should say how this is used
3419 @c OK, anyone who knows, please explain.
3421 @item SO_REUSEADDR
3422 @standards{BSD, sys/socket.h}
3423 This option controls whether @code{bind} (@pxref{Setting Address})
3424 should permit reuse of local addresses for this socket.  If you enable
3425 this option, you can actually have two sockets with the same Internet
3426 port number; but the system won't allow you to use the two
3427 identically-named sockets in a way that would confuse the Internet.  The
3428 reason for this option is that some higher-level Internet protocols,
3429 including FTP, require you to keep reusing the same port number.
3431 The value has type @code{int}; a nonzero value means ``yes''.
3433 @item SO_KEEPALIVE
3434 @standards{BSD, sys/socket.h}
3435 This option controls whether the underlying protocol should
3436 periodically transmit messages on a connected socket.  If the peer
3437 fails to respond to these messages, the connection is considered
3438 broken.  The value has type @code{int}; a nonzero value means
3439 ``yes''.
3441 @item SO_DONTROUTE
3442 @standards{BSD, sys/socket.h}
3443 This option controls whether outgoing messages bypass the normal
3444 message routing facilities.  If set, messages are sent directly to the
3445 network interface instead.  The value has type @code{int}; a nonzero
3446 value means ``yes''.
3448 @item SO_LINGER
3449 @standards{BSD, sys/socket.h}
3450 This option specifies what should happen when the socket of a type
3451 that promises reliable delivery still has untransmitted messages when
3452 it is closed; see @ref{Closing a Socket}.  The value has type
3453 @code{struct linger}.
3455 @deftp {Data Type} {struct linger}
3456 @standards{BSD, sys/socket.h}
3457 This structure type has the following members:
3459 @table @code
3460 @item int l_onoff
3461 This field is interpreted as a boolean.  If nonzero, @code{close}
3462 blocks until the data are transmitted or the timeout period has expired.
3464 @item int l_linger
3465 This specifies the timeout period, in seconds.
3466 @end table
3467 @end deftp
3469 @item SO_BROADCAST
3470 @standards{BSD, sys/socket.h}
3471 This option controls whether datagrams may be broadcast from the socket.
3472 The value has type @code{int}; a nonzero value means ``yes''.
3474 @item SO_OOBINLINE
3475 @standards{BSD, sys/socket.h}
3476 If this option is set, out-of-band data received on the socket is
3477 placed in the normal input queue.  This permits it to be read using
3478 @code{read} or @code{recv} without specifying the @code{MSG_OOB}
3479 flag.  @xref{Out-of-Band Data}.  The value has type @code{int}; a
3480 nonzero value means ``yes''.
3482 @item SO_SNDBUF
3483 @standards{BSD, sys/socket.h}
3484 This option gets or sets the size of the output buffer.  The value is a
3485 @code{size_t}, which is the size in bytes.
3487 @item SO_RCVBUF
3488 @standards{BSD, sys/socket.h}
3489 This option gets or sets the size of the input buffer.  The value is a
3490 @code{size_t}, which is the size in bytes.
3492 @item SO_STYLE
3493 @itemx SO_TYPE
3494 @standards{GNU, sys/socket.h}
3495 @standardsx{SO_TYPE, BSD, sys/socket.h}
3496 This option can be used with @code{getsockopt} only.  It is used to
3497 get the socket's communication style.  @code{SO_TYPE} is the
3498 historical name, and @code{SO_STYLE} is the preferred name in GNU.
3499 The value has type @code{int} and its value designates a communication
3500 style; see @ref{Communication Styles}.
3502 @item SO_ERROR
3503 @standards{BSD, sys/socket.h}
3504 @c Extra blank line here makes the table look better.
3506 This option can be used with @code{getsockopt} only.  It is used to reset
3507 the error status of the socket.  The value is an @code{int}, which represents
3508 the previous error status.
3509 @c !!! what is "socket error status"?  this is never defined.
3510 @end vtable
3512 @node Networks Database
3513 @section Networks Database
3514 @cindex networks database
3515 @cindex converting network number to network name
3516 @cindex converting network name to network number
3518 @pindex /etc/networks
3519 @pindex netdb.h
3520 Many systems come with a database that records a list of networks known
3521 to the system developer.  This is usually kept either in the file
3522 @file{/etc/networks} or in an equivalent from a name server.  This data
3523 base is useful for routing programs such as @code{route}, but it is not
3524 useful for programs that simply communicate over the network.  We
3525 provide functions to access this database, which are declared in
3526 @file{netdb.h}.
3528 @deftp {Data Type} {struct netent}
3529 @standards{BSD, netdb.h}
3530 This data type is used to represent information about entries in the
3531 networks database.  It has the following members:
3533 @table @code
3534 @item char *n_name
3535 This is the ``official'' name of the network.
3537 @item char **n_aliases
3538 These are alternative names for the network, represented as a vector
3539 of strings.  A null pointer terminates the array.
3541 @item int n_addrtype
3542 This is the type of the network number; this is always equal to
3543 @code{AF_INET} for Internet networks.
3545 @item unsigned long int n_net
3546 This is the network number.  Network numbers are returned in host
3547 byte order; see @ref{Byte Order}.
3548 @end table
3549 @end deftp
3551 Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search
3552 the networks database for information about a specific network.  The
3553 information is returned in a statically-allocated structure; you must
3554 copy the information if you need to save it.
3556 @deftypefun {struct netent *} getnetbyname (const char *@var{name})
3557 @standards{BSD, netdb.h}
3558 @safety{@prelim{}@mtunsafe{@mtasurace{:netbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
3559 @c getnetbyname =~ getpwuid @mtasurace:netbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3560 @c  libc_lock_lock dup @asulock @aculock
3561 @c  malloc dup @ascuheap @acsmem
3562 @c  getnetbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3563 @c  realloc dup @ascuheap @acsmem
3564 @c  free dup @ascuheap @acsmem
3565 @c  libc_lock_unlock dup @aculock
3567 @c getnetbyname_r =~ getpwuid_r @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3568 @c   no nscd support
3569 @c  res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
3570 @c  nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3571 @c  *fct.l -> _nss_*_getnetbyname_r @ascuplugin
3572 @c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3573 The @code{getnetbyname} function returns information about the network
3574 named @var{name}.  It returns a null pointer if there is no such
3575 network.
3576 @end deftypefun
3578 @deftypefun {struct netent *} getnetbyaddr (uint32_t @var{net}, int @var{type})
3579 @standards{BSD, netdb.h}
3580 @safety{@prelim{}@mtunsafe{@mtasurace{:netbyaddr} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
3581 @c getnetbyaddr =~ getpwuid @mtasurace:netbyaddr @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3582 @c  libc_lock_lock dup @asulock @aculock
3583 @c  malloc dup @ascuheap @acsmem
3584 @c  getnetbyaddr_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3585 @c  realloc dup @ascuheap @acsmem
3586 @c  free dup @ascuheap @acsmem
3587 @c  libc_lock_unlock dup @aculock
3589 @c getnetbyaddr_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3590 @c   no nscd support
3591 @c  nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3592 @c  *fct.l -> _nss_*_getnetbyaddr_r @ascuplugin
3593 @c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3594 The @code{getnetbyaddr} function returns information about the network
3595 of type @var{type} with number @var{net}.  You should specify a value of
3596 @code{AF_INET} for the @var{type} argument for Internet networks.
3598 @code{getnetbyaddr} returns a null pointer if there is no such
3599 network.
3600 @end deftypefun
3602 You can also scan the networks database using @code{setnetent},
3603 @code{getnetent} and @code{endnetent}.  Be careful when using these
3604 functions because they are not reentrant.
3606 @deftypefun void setnetent (int @var{stayopen})
3607 @standards{BSD, netdb.h}
3608 @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
3609 @c setnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3610 @c  libc_lock_lock dup @asulock @aculock
3611 @c  nss_setent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3612 @c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
3613 @c   setup(nss_networks_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3614 @c    *lookup_fct = nss_networks_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3615 @c    nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3616 @c   *fct.f @mtasurace:netent @ascuplugin
3617 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3618 @c  libc_lock_unlock dup @aculock
3619 This function opens and rewinds the networks database.
3621 If the @var{stayopen} argument is nonzero, this sets a flag so that
3622 subsequent calls to @code{getnetbyname} or @code{getnetbyaddr} will
3623 not close the database (as they usually would).  This makes for more
3624 efficiency if you call those functions several times, by avoiding
3625 reopening the database for each call.
3626 @end deftypefun
3628 @deftypefun {struct netent *} getnetent (void)
3629 @standards{BSD, netdb.h}
3630 @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtasurace{:netentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
3631 @c getnetent @mtasurace:netent @mtasurace:netentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3632 @c  libc_lock_lock dup @asulock @aculock
3633 @c  nss_getent(getnetent_r) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3634 @c   malloc dup @ascuheap @acsmem
3635 @c   *func = getnetent_r dup @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3636 @c   realloc dup @ascuheap @acsmem
3637 @c   free dup @ascuheap @acsmem
3638 @c  libc_lock_unlock dup @aculock
3640 @c getnetent_r @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3641 @c  libc_lock_lock dup @asulock @aculock
3642 @c  nss_getent_r(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3643 @c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
3644 @c   setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3645 @c   *fct.f @mtasurace:servent @ascuplugin
3646 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3647 @c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3648 @c   *sfct.f @mtasurace:netent @ascuplugin
3649 @c  libc_lock_unlock dup @aculock
3650 This function returns the next entry in the networks database.  It
3651 returns a null pointer if there are no more entries.
3652 @end deftypefun
3654 @deftypefun void endnetent (void)
3655 @standards{BSD, netdb.h}
3656 @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
3657 @c endnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3658 @c  libc_lock_lock @asulock @aculock
3659 @c  nss_endent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3660 @c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
3661 @c   setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3662 @c   *fct.f @mtasurace:netent @ascuplugin
3663 @c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
3664 @c  libc_lock_unlock @aculock
3665 This function closes the networks database.
3666 @end deftypefun