Update gethostbyname2_r documentation. Fixes bug #156.
[platform/upstream/glibc.git] / manual / socket.texi
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
4
5 This chapter describes the GNU facilities for interprocess
6 communication using sockets.
7
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.
17
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.
22
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.
27
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
45
46 @node Socket Concepts
47 @section Socket Concepts
48
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:
56
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}).
66
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.
75
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.
79
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
87
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.
100
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_}.
111
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:
116
117 @itemize @bullet
118 @item
119 In order to have communication between two sockets, they must specify
120 the @emph{same} protocol.
121
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.
127
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
133
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.
141
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.
146
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.
153
154
155 @node Communication Styles
156 @section Communication Styles
157
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
163
164 @comment sys/socket.h
165 @comment BSD
166 @deftypevr Macro int SOCK_STREAM
167 The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}).
168 It operates over a connection with a particular remote socket and
169 transmits data reliably as a stream of bytes.
170
171 Use of this style is covered in detail in @ref{Connections}.
172 @end deftypevr
173
174 @comment sys/socket.h
175 @comment BSD
176 @deftypevr Macro int SOCK_DGRAM
177 The @code{SOCK_DGRAM} style is used for sending
178 individually-addressed packets unreliably.
179 It is the diametrical opposite of @code{SOCK_STREAM}.
180
181 Each time you write data to a socket of this kind, that data becomes
182 one packet.  Since @code{SOCK_DGRAM} sockets do not have connections,
183 you must specify the recipient address with each packet.
184
185 The only guarantee that the system makes about your requests to
186 transmit data is that it will try its best to deliver each packet you
187 send.  It may succeed with the sixth packet after failing with the
188 fourth and fifth packets; the seventh packet may arrive before the
189 sixth, and may arrive a second time after the sixth.
190
191 The typical use for @code{SOCK_DGRAM} is in situations where it is
192 acceptable to simply re-send a packet if no response is seen in a
193 reasonable amount of time.
194
195 @xref{Datagrams}, for detailed information about how to use datagram
196 sockets.
197 @end deftypevr
198
199 @ignore
200 @c This appears to be only for the NS domain, which we aren't
201 @c discussing and probably won't support either.
202 @comment sys/socket.h
203 @comment BSD
204 @deftypevr Macro int SOCK_SEQPACKET
205 This style is like @code{SOCK_STREAM} except that the data are
206 structured into packets.
207
208 A program that receives data over a @code{SOCK_SEQPACKET} socket
209 should be prepared to read the entire message packet in a single call
210 to @code{read}; if it only reads part of the message, the remainder of
211 the message is simply discarded instead of being available for
212 subsequent calls to @code{read}.
213
214 Many protocols do not support this communication style.
215 @end deftypevr
216 @end ignore
217
218 @ignore
219 @comment sys/socket.h
220 @comment BSD
221 @deftypevr Macro int SOCK_RDM
222 This style is a reliable version of @code{SOCK_DGRAM}: it sends
223 individually addressed packets, but guarantees that each packet sent
224 arrives exactly once.
225
226 @strong{Warning:} It is not clear this is actually supported
227 by any operating system.
228 @end deftypevr
229 @end ignore
230
231 @comment sys/socket.h
232 @comment BSD
233 @deftypevr Macro int SOCK_RAW
234 This style provides access to low-level network protocols and
235 interfaces.  Ordinary user programs usually have no need to use this
236 style.
237 @end deftypevr
238
239 @node Socket Addresses
240 @section Socket Addresses
241
242 @cindex address of socket
243 @cindex name of socket
244 @cindex binding a socket address
245 @cindex socket address (name) binding
246 The name of a socket is normally called an @dfn{address}.  The
247 functions and symbols for dealing with socket addresses were named
248 inconsistently, sometimes using the term ``name'' and sometimes using
249 ``address''.  You can regard these terms as synonymous where sockets
250 are concerned.
251
252 A socket newly created with the @code{socket} function has no
253 address.  Other processes can find it for communication only if you
254 give it an address.  We call this @dfn{binding} the address to the
255 socket, and the way to do it is with the @code{bind} function.
256
257 You need be concerned with the address of a socket if other processes
258 are to find it and start communicating with it.  You can specify an
259 address for other sockets, but this is usually pointless; the first time
260 you send data from a socket, or use it to initiate a connection, the
261 system assigns an address automatically if you have not specified one.
262
263 Occasionally a client needs to specify an address because the server
264 discriminates based on address; for example, the rsh and rlogin
265 protocols look at the client's socket address and only bypass password
266 checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
267
268 The details of socket addresses vary depending on what namespace you are
269 using.  @xref{Local Namespace}, or @ref{Internet Namespace}, for specific
270 information.
271
272 Regardless of the namespace, you use the same functions @code{bind} and
273 @code{getsockname} to set and examine a socket's address.  These
274 functions use a phony data type, @code{struct sockaddr *}, to accept the
275 address.  In practice, the address lives in a structure of some other
276 data type appropriate to the address format you are using, but you cast
277 its address to @code{struct sockaddr *} when you pass it to
278 @code{bind}.
279
280 @menu
281 * Address Formats::             About @code{struct sockaddr}.
282 * Setting Address::             Binding an address to a socket.
283 * Reading Address::             Reading the address of a socket.
284 @end menu
285
286 @node Address Formats
287 @subsection Address Formats
288
289 The functions @code{bind} and @code{getsockname} use the generic data
290 type @code{struct sockaddr *} to represent a pointer to a socket
291 address.  You can't use this data type effectively to interpret an
292 address or construct one; for that, you must use the proper data type
293 for the socket's namespace.
294
295 Thus, the usual practice is to construct an address of the proper
296 namespace-specific type, then cast a pointer to @code{struct sockaddr *}
297 when you call @code{bind} or @code{getsockname}.
298
299 The one piece of information that you can get from the @code{struct
300 sockaddr} data type is the @dfn{address format designator}.  This tells
301 you which data type to use to understand the address fully.
302
303 @pindex sys/socket.h
304 The symbols in this section are defined in the header file
305 @file{sys/socket.h}.
306
307 @comment sys/socket.h
308 @comment BSD
309 @deftp {Data Type} {struct sockaddr}
310 The @code{struct sockaddr} type itself has the following members:
311
312 @table @code
313 @item short int sa_family
314 This is the code for the address format of this address.  It
315 identifies the format of the data which follows.
316
317 @item char sa_data[14]
318 This is the actual socket address data, which is format-dependent.  Its
319 length also depends on the format, and may well be more than 14.  The
320 length 14 of @code{sa_data} is essentially arbitrary.
321 @end table
322 @end deftp
323
324 Each address format has a symbolic name which starts with @samp{AF_}.
325 Each of them corresponds to a @samp{PF_} symbol which designates the
326 corresponding namespace.  Here is a list of address format names:
327
328 @table @code
329 @comment sys/socket.h
330 @comment POSIX
331 @item AF_LOCAL
332 @vindex AF_LOCAL
333 This designates the address format that goes with the local namespace.
334 (@code{PF_LOCAL} is the name of that namespace.)  @xref{Local Namespace
335 Details}, for information about this address format.
336
337 @comment sys/socket.h
338 @comment BSD, Unix98
339 @item AF_UNIX
340 @vindex AF_UNIX
341 This is a synonym for @code{AF_LOCAL}.  Although @code{AF_LOCAL} is
342 mandated by POSIX.1g, @code{AF_UNIX} is portable to more systems.
343 @code{AF_UNIX} was the traditional name stemming from BSD, so even most
344 POSIX systems support it.  It is also the name of choice in the Unix98
345 specification. (The same is true for @code{PF_UNIX}
346 vs. @code{PF_LOCAL}).
347
348 @comment sys/socket.h
349 @comment GNU
350 @item AF_FILE
351 @vindex AF_FILE
352 This is another synonym for @code{AF_LOCAL}, for compatibility.
353 (@code{PF_FILE} is likewise a synonym for @code{PF_LOCAL}.)
354
355 @comment sys/socket.h
356 @comment BSD
357 @item AF_INET
358 @vindex AF_INET
359 This designates the address format that goes with the Internet
360 namespace.  (@code{PF_INET} is the name of that namespace.)
361 @xref{Internet Address Formats}.
362
363 @comment sys/socket.h
364 @comment IPv6 Basic API
365 @item AF_INET6
366 This is similar to @code{AF_INET}, but refers to the IPv6 protocol.
367 (@code{PF_INET6} is the name of the corresponding namespace.)
368
369 @comment sys/socket.h
370 @comment BSD
371 @item AF_UNSPEC
372 @vindex AF_UNSPEC
373 This designates no particular address format.  It is used only in rare
374 cases, such as to clear out the default destination address of a
375 ``connected'' datagram socket.  @xref{Sending Datagrams}.
376
377 The corresponding namespace designator symbol @code{PF_UNSPEC} exists
378 for completeness, but there is no reason to use it in a program.
379 @end table
380
381 @file{sys/socket.h} defines symbols starting with @samp{AF_} for many
382 different kinds of networks, most or all of which are not actually
383 implemented.  We will document those that really work as we receive
384 information about how to use them.
385
386 @node Setting Address
387 @subsection Setting the Address of a Socket
388
389 @pindex sys/socket.h
390 Use the @code{bind} function to assign an address to a socket.  The
391 prototype for @code{bind} is in the header file @file{sys/socket.h}.
392 For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}.
393
394 @comment sys/socket.h
395 @comment BSD
396 @deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
397 The @code{bind} function assigns an address to the socket
398 @var{socket}.  The @var{addr} and @var{length} arguments specify the
399 address; the detailed format of the address depends on the namespace.
400 The first part of the address is always the format designator, which
401 specifies a namespace, and says that the address is in the format of
402 that namespace.
403
404 The return value is @code{0} on success and @code{-1} on failure.  The
405 following @code{errno} error conditions are defined for this function:
406
407 @table @code
408 @item EBADF
409 The @var{socket} argument is not a valid file descriptor.
410
411 @item ENOTSOCK
412 The descriptor @var{socket} is not a socket.
413
414 @item EADDRNOTAVAIL
415 The specified address is not available on this machine.
416
417 @item EADDRINUSE
418 Some other socket is already using the specified address.
419
420 @item EINVAL
421 The socket @var{socket} already has an address.
422
423 @item EACCES
424 You do not have permission to access the requested address.  (In the
425 Internet domain, only the super-user is allowed to specify a port number
426 in the range 0 through @code{IPPORT_RESERVED} minus one; see
427 @ref{Ports}.)
428 @end table
429
430 Additional conditions may be possible depending on the particular namespace
431 of the socket.
432 @end deftypefun
433
434 @node Reading Address
435 @subsection Reading the Address of a Socket
436
437 @pindex sys/socket.h
438 Use the function @code{getsockname} to examine the address of an
439 Internet socket.  The prototype for this function is in the header file
440 @file{sys/socket.h}.
441
442 @comment sys/socket.h
443 @comment BSD
444 @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
445 The @code{getsockname} function returns information about the
446 address of the socket @var{socket} in the locations specified by the
447 @var{addr} and @var{length-ptr} arguments.  Note that the
448 @var{length-ptr} is a pointer; you should initialize it to be the
449 allocation size of @var{addr}, and on return it contains the actual
450 size of the address data.
451
452 The format of the address data depends on the socket namespace.  The
453 length of the information is usually fixed for a given namespace, so
454 normally you can know exactly how much space is needed and can provide
455 that much.  The usual practice is to allocate a place for the value
456 using the proper data type for the socket's namespace, then cast its
457 address to @code{struct sockaddr *} to pass it to @code{getsockname}.
458
459 The return value is @code{0} on success and @code{-1} on error.  The
460 following @code{errno} error conditions are defined for this function:
461
462 @table @code
463 @item EBADF
464 The @var{socket} argument is not a valid file descriptor.
465
466 @item ENOTSOCK
467 The descriptor @var{socket} is not a socket.
468
469 @item ENOBUFS
470 There are not enough internal buffers available for the operation.
471 @end table
472 @end deftypefun
473
474 You can't read the address of a socket in the file namespace.  This is
475 consistent with the rest of the system; in general, there's no way to
476 find a file's name from a descriptor for that file.
477
478 @node Interface Naming
479 @section Interface Naming
480
481 Each network interface has a name.  This usually consists of a few
482 letters that relate to the type of interface, which may be followed by a
483 number if there is more than one interface of that type.  Examples
484 might be @code{lo} (the loopback interface) and @code{eth0} (the first
485 Ethernet interface).
486
487 Although such names are convenient for humans, it would be clumsy to
488 have to use them whenever a program needs to refer to an interface.  In
489 such situations an interface is referred to by its @dfn{index}, which is
490 an arbitrarily-assigned small positive integer.
491
492 The following functions, constants and data types are declared in the
493 header file @file{net/if.h}.
494
495 @comment net/if.h
496 @deftypevr Constant size_t IFNAMSIZ
497 This constant defines the maximum buffer size needed to hold an
498 interface name, including its terminating zero byte.
499 @end deftypevr
500
501 @comment net/if.h
502 @comment IPv6 basic API
503 @deftypefun {unsigned int} if_nametoindex (const char *@var{ifname})
504 This function yields the interface index corresponding to a particular
505 name.  If no interface exists with the name given, it returns 0.
506 @end deftypefun
507
508 @comment net/if.h
509 @comment IPv6 basic API
510 @deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname})
511 This function maps an interface index to its corresponding name.  The
512 returned name is placed in the buffer pointed to by @code{ifname}, which
513 must be at least @code{IFNAMSIZ} bytes in length.  If the index was
514 invalid, the function's return value is a null pointer, otherwise it is
515 @code{ifname}.
516 @end deftypefun
517
518 @comment net/if.h
519 @comment IPv6 basic API
520 @deftp {Data Type} {struct if_nameindex}
521 This data type is used to hold the information about a single
522 interface.  It has the following members:
523
524 @table @code
525 @item unsigned int if_index;
526 This is the interface index.
527
528 @item char *if_name
529 This is the null-terminated index name.
530
531 @end table
532 @end deftp
533
534 @comment net/if.h
535 @comment IPv6 basic API
536 @deftypefun {struct if_nameindex *} if_nameindex (void)
537 This function returns an array of @code{if_nameindex} structures, one
538 for every interface that is present.  The end of the list is indicated
539 by a structure with an interface of 0 and a null name pointer.  If an
540 error occurs, this function returns a null pointer.
541
542 The returned structure must be freed with @code{if_freenameindex} after
543 use.
544 @end deftypefun
545
546 @comment net/if.h
547 @comment IPv6 basic API
548 @deftypefun void if_freenameindex (struct if_nameindex *@var{ptr})
549 This function frees the structure returned by an earlier call to
550 @code{if_nameindex}.
551 @end deftypefun
552
553 @node Local Namespace
554 @section The Local Namespace
555 @cindex local namespace, for sockets
556
557 This section describes the details of the local namespace, whose
558 symbolic name (required when you create a socket) is @code{PF_LOCAL}.
559 The local namespace is also known as ``Unix domain sockets''.  Another
560 name is file namespace since socket addresses are normally implemented
561 as file names.
562
563 @menu
564 * Concepts: Local Namespace Concepts. What you need to understand.
565 * Details: Local Namespace Details.   Address format, symbolic names, etc.
566 * Example: Local Socket Example.      Example of creating a socket.
567 @end menu
568
569 @node Local Namespace Concepts
570 @subsection Local Namespace Concepts
571
572 In the local namespace socket addresses are file names.  You can specify
573 any file name you want as the address of the socket, but you must have
574 write permission on the directory containing it.
575 @c XXX The following was said to be wrong.
576 @c In order to connect to a socket you must have read permission for it.
577 It's common to put these files in the @file{/tmp} directory.
578
579 One peculiarity of the local namespace is that the name is only used
580 when opening the connection; once open the address is not meaningful and
581 may not exist.
582
583 Another peculiarity is that you cannot connect to such a socket from
584 another machine--not even if the other machine shares the file system
585 which contains the name of the socket.  You can see the socket in a
586 directory listing, but connecting to it never succeeds.  Some programs
587 take advantage of this, such as by asking the client to send its own
588 process ID, and using the process IDs to distinguish between clients.
589 However, we recommend you not use this method in protocols you design,
590 as we might someday permit connections from other machines that mount
591 the same file systems.  Instead, send each new client an identifying
592 number if you want it to have one.
593
594 After you close a socket in the local namespace, you should delete the
595 file name from the file system.  Use @code{unlink} or @code{remove} to
596 do this; see @ref{Deleting Files}.
597
598 The local namespace supports just one protocol for any communication
599 style; it is protocol number @code{0}.
600
601 @node Local Namespace Details
602 @subsection Details of Local Namespace
603
604 @pindex sys/socket.h
605 To create a socket in the local namespace, use the constant
606 @code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or
607 @code{socketpair}.  This constant is defined in @file{sys/socket.h}.
608
609 @comment sys/socket.h
610 @comment POSIX
611 @deftypevr Macro int PF_LOCAL
612 This designates the local namespace, in which socket addresses are local
613 names, and its associated family of protocols.  @code{PF_Local} is the
614 macro used by Posix.1g.
615 @end deftypevr
616
617 @comment sys/socket.h
618 @comment BSD
619 @deftypevr Macro int PF_UNIX
620 This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
621 @end deftypevr
622
623 @comment sys/socket.h
624 @comment GNU
625 @deftypevr Macro int PF_FILE
626 This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
627 @end deftypevr
628
629 The structure for specifying socket names in the local namespace is
630 defined in the header file @file{sys/un.h}:
631 @pindex sys/un.h
632
633 @comment sys/un.h
634 @comment BSD
635 @deftp {Data Type} {struct sockaddr_un}
636 This structure is used to specify local namespace socket addresses.  It has
637 the following members:
638
639 @table @code
640 @item short int sun_family
641 This identifies the address family or format of the socket address.
642 You should store the value @code{AF_LOCAL} to designate the local
643 namespace.  @xref{Socket Addresses}.
644
645 @item char sun_path[108]
646 This is the file name to use.
647
648 @strong{Incomplete:}  Why is 108 a magic number?  RMS suggests making
649 this a zero-length array and tweaking the following example to use
650 @code{alloca} to allocate an appropriate amount of storage based on
651 the length of the filename.
652 @end table
653 @end deftp
654
655 You should compute the @var{length} parameter for a socket address in
656 the local namespace as the sum of the size of the @code{sun_family}
657 component and the string length (@emph{not} the allocation size!) of
658 the file name string.  This can be done using the macro @code{SUN_LEN}:
659
660 @comment sys/un.h
661 @comment BSD
662 @deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr})
663 The macro computes the length of socket address in the local namespace.
664 @end deftypefn
665
666 @node Local Socket Example
667 @subsection Example of Local-Namespace Sockets
668
669 Here is an example showing how to create and name a socket in the local
670 namespace.
671
672 @smallexample
673 @include mkfsock.c.texi
674 @end smallexample
675
676 @node Internet Namespace
677 @section The Internet Namespace
678 @cindex Internet namespace, for sockets
679
680 This section describes the details of the protocols and socket naming
681 conventions used in the Internet namespace.
682
683 Originally the Internet namespace used only IP version 4 (IPv4).  With
684 the growing number of hosts on the Internet, a new protocol with a
685 larger address space was necessary: IP version 6 (IPv6).  IPv6
686 introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
687 features, and will eventually replace IPv4.
688
689 To create a socket in the IPv4 Internet namespace, use the symbolic name
690 @code{PF_INET} of this namespace as the @var{namespace} argument to
691 @code{socket} or @code{socketpair}.  For IPv6 addresses you need the
692 macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}.
693 @pindex sys/socket.h
694
695 @comment sys/socket.h
696 @comment BSD
697 @deftypevr Macro int PF_INET
698 This designates the IPv4 Internet namespace and associated family of
699 protocols.
700 @end deftypevr
701
702 @comment sys/socket.h
703 @comment X/Open
704 @deftypevr Macro int PF_INET6
705 This designates the IPv6 Internet namespace and associated family of
706 protocols.
707 @end deftypevr
708
709 A socket address for the Internet namespace includes the following components:
710
711 @itemize @bullet
712 @item
713 The address of the machine you want to connect to.  Internet addresses
714 can be specified in several ways; these are discussed in @ref{Internet
715 Address Formats}, @ref{Host Addresses} and @ref{Host Names}.
716
717 @item
718 A port number for that machine.  @xref{Ports}.
719 @end itemize
720
721 You must ensure that the address and port number are represented in a
722 canonical format called @dfn{network byte order}.  @xref{Byte Order},
723 for information about this.
724
725 @menu
726 * Internet Address Formats::    How socket addresses are specified in the
727                                  Internet namespace.
728 * Host Addresses::              All about host addresses of Internet host.
729 * Ports::                       Internet port numbers.
730 * Services Database::           Ports may have symbolic names.
731 * Byte Order::                  Different hosts may use different byte
732                                  ordering conventions; you need to
733                                  canonicalize host address and port number.
734 * Protocols Database::          Referring to protocols by name.
735 * Inet Example::                Putting it all together.
736 @end menu
737
738 @node Internet Address Formats
739 @subsection Internet Socket Address Formats
740
741 In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6
742 (@code{AF_INET6}), a socket address consists of a host address
743 and a port on that host.  In addition, the protocol you choose serves
744 effectively as a part of the address because local port numbers are
745 meaningful only within a particular protocol.
746
747 The data types for representing socket addresses in the Internet namespace
748 are defined in the header file @file{netinet/in.h}.
749 @pindex netinet/in.h
750
751 @comment netinet/in.h
752 @comment BSD
753 @deftp {Data Type} {struct sockaddr_in}
754 This is the data type used to represent socket addresses in the
755 Internet namespace.  It has the following members:
756
757 @table @code
758 @item sa_family_t sin_family
759 This identifies the address family or format of the socket address.
760 You should store the value @code{AF_INET} in this member.
761 @xref{Socket Addresses}.
762
763 @item struct in_addr sin_addr
764 This is the Internet address of the host machine.  @xref{Host
765 Addresses}, and @ref{Host Names}, for how to get a value to store
766 here.
767
768 @item unsigned short int sin_port
769 This is the port number.  @xref{Ports}.
770 @end table
771 @end deftp
772
773 When you call @code{bind} or @code{getsockname}, you should specify
774 @code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
775 you are using an IPv4 Internet namespace socket address.
776
777 @deftp {Data Type} {struct sockaddr_in6}
778 This is the data type used to represent socket addresses in the IPv6
779 namespace.  It has the following members:
780
781 @table @code
782 @item sa_family_t sin6_family
783 This identifies the address family or format of the socket address.
784 You should store the value of @code{AF_INET6} in this member.
785 @xref{Socket Addresses}.
786
787 @item struct in6_addr sin6_addr
788 This is the IPv6 address of the host machine.  @xref{Host
789 Addresses}, and @ref{Host Names}, for how to get a value to store
790 here.
791
792 @item uint32_t sin6_flowinfo
793 This is a currently unimplemented field.
794
795 @item uint16_t sin6_port
796 This is the port number.  @xref{Ports}.
797
798 @end table
799 @end deftp
800
801 @node Host Addresses
802 @subsection Host Addresses
803
804 Each computer on the Internet has one or more @dfn{Internet addresses},
805 numbers which identify that computer among all those on the Internet.
806 Users typically write IPv4 numeric host addresses as sequences of four
807 numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6
808 numeric host addresses as sequences of up to eight numbers separated by
809 colons, as in @samp{5f03:1200:836f:c100::1}.
810
811 Each computer also has one or more @dfn{host names}, which are strings
812 of words separated by periods, as in @samp{www.gnu.org}.
813
814 Programs that let the user specify a host typically accept both numeric
815 addresses and host names.  To open a connection a program needs a
816 numeric address, and so must convert a host name to the numeric address
817 it stands for.
818
819 @menu
820 * Abstract Host Addresses::     What a host number consists of.
821 * Data type: Host Address Data Type.    Data type for a host number.
822 * Functions: Host Address Functions.    Functions to operate on them.
823 * Names: Host Names.            Translating host names to host numbers.
824 @end menu
825
826 @node Abstract Host Addresses
827 @subsubsection Internet Host Addresses
828 @cindex host address, Internet
829 @cindex Internet host address
830
831 @ifinfo
832 Each computer on the Internet has one or more Internet addresses,
833 numbers which identify that computer among all those on the Internet.
834 @end ifinfo
835
836 @cindex network number
837 @cindex local network address number
838 An IPv4 Internet host address is a number containing four bytes of data.
839 Historically these are divided into two parts, a @dfn{network number} and a
840 @dfn{local network address number} within that network.  In the
841 mid-1990s classless addresses were introduced which changed this
842 behavior.  Since some functions implicitly expect the old definitions,
843 we first describe the class-based network and will then describe
844 classless addresses.  IPv6 uses only classless addresses and therefore
845 the following paragraphs don't apply.
846
847 The class-based IPv4 network number consists of the first one, two or
848 three bytes; the rest of the bytes are the local address.
849
850 IPv4 network numbers are registered with the Network Information Center
851 (NIC), and are divided into three classes---A, B and C.  The local
852 network address numbers of individual machines are registered with the
853 administrator of the particular network.
854
855 Class A networks have single-byte numbers in the range 0 to 127.  There
856 are only a small number of Class A networks, but they can each support a
857 very large number of hosts.  Medium-sized Class B networks have two-byte
858 network numbers, with the first byte in the range 128 to 191.  Class C
859 networks are the smallest; they have three-byte network numbers, with
860 the first byte in the range 192-255.  Thus, the first 1, 2, or 3 bytes
861 of an Internet address specify a network.  The remaining bytes of the
862 Internet address specify the address within that network.
863
864 The Class A network 0 is reserved for broadcast to all networks.  In
865 addition, the host number 0 within each network is reserved for broadcast
866 to all hosts in that network.  These uses are obsolete now but for
867 compatibility reasons you shouldn't use network 0 and host number 0.
868
869 The Class A network 127 is reserved for loopback; you can always use
870 the Internet address @samp{127.0.0.1} to refer to the host machine.
871
872 Since a single machine can be a member of multiple networks, it can
873 have multiple Internet host addresses.  However, there is never
874 supposed to be more than one machine with the same host address.
875
876 @c !!! this section could document the IN_CLASS* macros in <netinet/in.h>.
877 @c No, it shouldn't since they're obsolete.
878
879 @cindex standard dot notation, for Internet addresses
880 @cindex dot notation, for Internet addresses
881 There are four forms of the @dfn{standard numbers-and-dots notation}
882 for Internet addresses:
883
884 @table @code
885 @item @var{a}.@var{b}.@var{c}.@var{d}
886 This specifies all four bytes of the address individually and is the
887 commonly used representation.
888
889 @item @var{a}.@var{b}.@var{c}
890 The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
891 This is useful for specifying host addresses in a Class B network with
892 network address number @code{@var{a}.@var{b}}.
893
894 @item @var{a}.@var{b}
895 The last part of the address, @var{b}, is interpreted as a 3-byte quantity.
896 This is useful for specifying host addresses in a Class A network with
897 network address number @var{a}.
898
899 @item @var{a}
900 If only one part is given, this corresponds directly to the host address
901 number.
902 @end table
903
904 Within each part of the address, the usual C conventions for specifying
905 the radix apply.  In other words, a leading @samp{0x} or @samp{0X} implies
906 hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
907 radix is assumed.
908
909 @subsubheading Classless Addresses
910
911 IPv4 addresses (and IPv6 addresses also) are now considered classless;
912 the distinction between classes A, B and C can be ignored.  Instead an
913 IPv4 host address consists of a 32-bit address and a 32-bit mask.  The
914 mask contains set bits for the network part and cleared bits for the
915 host part.  The network part is contiguous from the left, with the
916 remaining bits representing the host.  As a consequence, the netmask can
917 simply be specified as the number of set bits.  Classes A, B and C are
918 just special cases of this general rule.  For example, class A addresses
919 have a netmask of @samp{255.0.0.0} or a prefix length of 8.
920
921 Classless IPv4 network addresses are written in numbers-and-dots
922 notation with the prefix length appended and a slash as separator.  For
923 example the class A network 10 is written as @samp{10.0.0.0/8}.
924
925 @subsubheading IPv6 Addresses
926
927 IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data.  A host
928 address is usually written as eight 16-bit hexadecimal numbers that are
929 separated by colons.  Two colons are used to abbreviate strings of
930 consecutive zeros.  For example, the IPv6 loopback address
931 @samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}.
932
933 @node Host Address Data Type
934 @subsubsection Host Address Data Type
935
936 IPv4 Internet host addresses are represented in some contexts as integers
937 (type @code{uint32_t}).  In other contexts, the integer is
938 packaged inside a structure of type @code{struct in_addr}.  It would
939 be better if the usage were made consistent, but it is not hard to extract
940 the integer from the structure or put the integer into a structure.
941
942 You will find older code that uses @code{unsigned long int} for
943 IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct
944 in_addr}.  Historically @code{unsigned long int} was a 32-bit number but
945 with 64-bit machines this has changed.  Using @code{unsigned long int}
946 might break the code if it is used on machines where this type doesn't
947 have 32 bits.  @code{uint32_t} is specified by Unix98 and guaranteed to have
948 32 bits.
949
950 IPv6 Internet host addresses have 128 bits and are packaged inside a
951 structure of type @code{struct in6_addr}.
952
953 The following basic definitions for Internet addresses are declared in
954 the header file @file{netinet/in.h}:
955 @pindex netinet/in.h
956
957 @comment netinet/in.h
958 @comment BSD
959 @deftp {Data Type} {struct in_addr}
960 This data type is used in certain contexts to contain an IPv4 Internet
961 host address.  It has just one field, named @code{s_addr}, which records
962 the host address number as an @code{uint32_t}.
963 @end deftp
964
965 @comment netinet/in.h
966 @comment BSD
967 @deftypevr Macro {uint32_t} INADDR_LOOPBACK
968 You can use this constant to stand for ``the address of this machine,''
969 instead of finding its actual address.  It is the IPv4 Internet address
970 @samp{127.0.0.1}, which is usually called @samp{localhost}.  This
971 special constant saves you the trouble of looking up the address of your
972 own machine.  Also, the system usually implements @code{INADDR_LOOPBACK}
973 specially, avoiding any network traffic for the case of one machine
974 talking to itself.
975 @end deftypevr
976
977 @comment netinet/in.h
978 @comment BSD
979 @deftypevr Macro {uint32_t} INADDR_ANY
980 You can use this constant to stand for ``any incoming address'' when
981 binding to an address.  @xref{Setting Address}.  This is the usual
982 address to give in the @code{sin_addr} member of @w{@code{struct
983 sockaddr_in}} when you want to accept Internet connections.
984 @end deftypevr
985
986 @comment netinet/in.h
987 @comment BSD
988 @deftypevr Macro {uint32_t} INADDR_BROADCAST
989 This constant is the address you use to send a broadcast message.
990 @c !!! broadcast needs further documented
991 @end deftypevr
992
993 @comment netinet/in.h
994 @comment BSD
995 @deftypevr Macro {uint32_t} INADDR_NONE
996 This constant is returned by some functions to indicate an error.
997 @end deftypevr
998
999 @comment netinet/in.h
1000 @comment IPv6 basic API
1001 @deftp {Data Type} {struct in6_addr}
1002 This data type is used to store an IPv6 address.  It stores 128 bits of
1003 data, which can be accessed (via a union) in a variety of ways.
1004 @end deftp
1005
1006 @comment netinet/in.h
1007 @comment IPv6 basic API
1008 @deftypevr Constant {struct in6_addr} in6addr_loopback
1009 This constant is the IPv6 address @samp{::1}, the loopback address.  See
1010 above for a description of what this means.  The macro
1011 @code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your
1012 own variables to this value.
1013 @end deftypevr
1014
1015 @comment netinet/in.h
1016 @comment IPv6 basic API
1017 @deftypevr Constant {struct in6_addr} in6addr_any
1018 This constant is the IPv6 address @samp{::}, the unspecified address.  See
1019 above for a description of what this means.  The macro
1020 @code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your
1021 own variables to this value.
1022 @end deftypevr
1023
1024 @node Host Address Functions
1025 @subsubsection Host Address Functions
1026
1027 @pindex arpa/inet.h
1028 @noindent
1029 These additional functions for manipulating Internet addresses are
1030 declared in the header file @file{arpa/inet.h}.  They represent Internet
1031 addresses in network byte order, and network numbers and
1032 local-address-within-network numbers in host byte order.  @xref{Byte
1033 Order}, for an explanation of network and host byte order.
1034
1035 @comment arpa/inet.h
1036 @comment BSD
1037 @deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr})
1038 This function converts the IPv4 Internet host address @var{name}
1039 from the standard numbers-and-dots notation into binary data and stores
1040 it in the @code{struct in_addr} that @var{addr} points to.
1041 @code{inet_aton} returns nonzero if the address is valid, zero if not.
1042 @end deftypefun
1043
1044 @comment arpa/inet.h
1045 @comment BSD
1046 @deftypefun {uint32_t} inet_addr (const char *@var{name})
1047 This function converts the IPv4 Internet host address @var{name} from the
1048 standard numbers-and-dots notation into binary data.  If the input is
1049 not valid, @code{inet_addr} returns @code{INADDR_NONE}.  This is an
1050 obsolete interface to @code{inet_aton}, described immediately above. It
1051 is obsolete because @code{INADDR_NONE} is a valid address
1052 (255.255.255.255), and @code{inet_aton} provides a cleaner way to
1053 indicate error return.
1054 @end deftypefun
1055
1056 @comment arpa/inet.h
1057 @comment BSD
1058 @deftypefun {uint32_t} inet_network (const char *@var{name})
1059 This function extracts the network number from the address @var{name},
1060 given in the standard numbers-and-dots notation. The returned address is
1061 in host order. If the input is not valid, @code{inet_network} returns
1062 @code{-1}.
1063
1064 The function works only with traditional IPv4 class A, B and C network
1065 types.  It doesn't work with classless addresses and shouldn't be used
1066 anymore.
1067 @end deftypefun
1068
1069 @comment arpa/inet.h
1070 @comment BSD
1071 @deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
1072 This function converts the IPv4 Internet host address @var{addr} to a
1073 string in the standard numbers-and-dots notation.  The return value is
1074 a pointer into a statically-allocated buffer.  Subsequent calls will
1075 overwrite the same buffer, so you should copy the string if you need
1076 to save it.
1077
1078 In multi-threaded programs each thread has an own statically-allocated
1079 buffer.  But still subsequent calls of @code{inet_ntoa} in the same
1080 thread will overwrite the result of the last call.
1081
1082 Instead of @code{inet_ntoa} the newer function @code{inet_ntop} which is
1083 described below should be used since it handles both IPv4 and IPv6
1084 addresses.
1085 @end deftypefun
1086
1087 @comment arpa/inet.h
1088 @comment BSD
1089 @deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local})
1090 This function makes an IPv4 Internet host address by combining the network
1091 number @var{net} with the local-address-within-network number
1092 @var{local}.
1093 @end deftypefun
1094
1095 @comment arpa/inet.h
1096 @comment BSD
1097 @deftypefun uint32_t inet_lnaof (struct in_addr @var{addr})
1098 This function returns the local-address-within-network part of the
1099 Internet host address @var{addr}.
1100
1101 The function works only with traditional IPv4 class A, B and C network
1102 types.  It doesn't work with classless addresses and shouldn't be used
1103 anymore.
1104 @end deftypefun
1105
1106 @comment arpa/inet.h
1107 @comment BSD
1108 @deftypefun uint32_t inet_netof (struct in_addr @var{addr})
1109 This function returns the network number part of the Internet host
1110 address @var{addr}.
1111
1112 The function works only with traditional IPv4 class A, B and C network
1113 types.  It doesn't work with classless addresses and shouldn't be used
1114 anymore.
1115 @end deftypefun
1116
1117 @comment arpa/inet.h
1118 @comment IPv6 basic API
1119 @deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf})
1120 This function converts an Internet address (either IPv4 or IPv6) from
1121 presentation (textual) to network (binary) format.  @var{af} should be
1122 either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of
1123 address being converted.  @var{cp} is a pointer to the input string, and
1124 @var{buf} is a pointer to a buffer for the result.  It is the caller's
1125 responsibility to make sure the buffer is large enough.
1126 @end deftypefun
1127
1128 @comment arpa/inet.h
1129 @comment IPv6 basic API
1130 @deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len})
1131 This function converts an Internet address (either IPv4 or IPv6) from
1132 network (binary) to presentation (textual) form.  @var{af} should be
1133 either @code{AF_INET} or @code{AF_INET6}, as appropriate.  @var{cp} is a
1134 pointer to the address to be converted.  @var{buf} should be a pointer
1135 to a buffer to hold the result, and @var{len} is the length of this
1136 buffer.  The return value from the function will be this buffer address.
1137 @end deftypefun
1138
1139 @node Host Names
1140 @subsubsection Host Names
1141 @cindex hosts database
1142 @cindex converting host name to address
1143 @cindex converting host address to name
1144
1145 Besides the standard numbers-and-dots notation for Internet addresses,
1146 you can also refer to a host by a symbolic name.  The advantage of a
1147 symbolic name is that it is usually easier to remember.  For example,
1148 the machine with Internet address @samp{158.121.106.19} is also known as
1149 @samp{alpha.gnu.org}; and other machines in the @samp{gnu.org}
1150 domain can refer to it simply as @samp{alpha}.
1151
1152 @pindex /etc/hosts
1153 @pindex netdb.h
1154 Internally, the system uses a database to keep track of the mapping
1155 between host names and host numbers.  This database is usually either
1156 the file @file{/etc/hosts} or an equivalent provided by a name server.
1157 The functions and other symbols for accessing this database are declared
1158 in @file{netdb.h}.  They are BSD features, defined unconditionally if
1159 you include @file{netdb.h}.
1160
1161 @comment netdb.h
1162 @comment BSD
1163 @deftp {Data Type} {struct hostent}
1164 This data type is used to represent an entry in the hosts database.  It
1165 has the following members:
1166
1167 @table @code
1168 @item char *h_name
1169 This is the ``official'' name of the host.
1170
1171 @item char **h_aliases
1172 These are alternative names for the host, represented as a null-terminated
1173 vector of strings.
1174
1175 @item int h_addrtype
1176 This is the host address type; in practice, its value is always either
1177 @code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6
1178 hosts.  In principle other kinds of addresses could be represented in
1179 the database as well as Internet addresses; if this were done, you
1180 might find a value in this field other than @code{AF_INET} or
1181 @code{AF_INET6}.  @xref{Socket Addresses}.
1182
1183 @item int h_length
1184 This is the length, in bytes, of each address.
1185
1186 @item char **h_addr_list
1187 This is the vector of addresses for the host.  (Recall that the host
1188 might be connected to multiple networks and have different addresses on
1189 each one.)  The vector is terminated by a null pointer.
1190
1191 @item char *h_addr
1192 This is a synonym for @code{h_addr_list[0]}; in other words, it is the
1193 first host address.
1194 @end table
1195 @end deftp
1196
1197 As far as the host database is concerned, each address is just a block
1198 of memory @code{h_length} bytes long.  But in other contexts there is an
1199 implicit assumption that you can convert IPv4 addresses to a
1200 @code{struct in_addr} or an @code{uint32_t}.  Host addresses in
1201 a @code{struct hostent} structure are always given in network byte
1202 order; see @ref{Byte Order}.
1203
1204 You can use @code{gethostbyname}, @code{gethostbyname2} or
1205 @code{gethostbyaddr} to search the hosts database for information about
1206 a particular host.  The information is returned in a
1207 statically-allocated structure; you must copy the information if you
1208 need to save it across calls.  You can also use @code{getaddrinfo} and
1209 @code{getnameinfo} to obtain this information.
1210
1211 @comment netdb.h
1212 @comment BSD
1213 @deftypefun {struct hostent *} gethostbyname (const char *@var{name})
1214 The @code{gethostbyname} function returns information about the host
1215 named @var{name}.  If the lookup fails, it returns a null pointer.
1216 @end deftypefun
1217
1218 @comment netdb.h
1219 @comment IPv6 Basic API
1220 @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
1221 The @code{gethostbyname2} function is like @code{gethostbyname}, but
1222 allows the caller to specify the desired address family (e.g.@:
1223 @code{AF_INET} or @code{AF_INET6}) of the result.
1224 @end deftypefun
1225
1226 @comment netdb.h
1227 @comment BSD
1228 @deftypefun {struct hostent *} gethostbyaddr (const void *@var{addr}, socklen_t @var{length}, int @var{format})
1229 The @code{gethostbyaddr} function returns information about the host
1230 with Internet address @var{addr}.  The parameter @var{addr} is not
1231 really a pointer to char - it can be a pointer to an IPv4 or an IPv6
1232 address. The @var{length} argument is the size (in bytes) of the address
1233 at @var{addr}.  @var{format} specifies the address format; for an IPv4
1234 Internet address, specify a value of @code{AF_INET}; for an IPv6
1235 Internet address, use @code{AF_INET6}.
1236
1237 If the lookup fails, @code{gethostbyaddr} returns a null pointer.
1238 @end deftypefun
1239
1240 @vindex h_errno
1241 If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
1242 fails, you can find out the reason by looking at the value of the
1243 variable @code{h_errno}.  (It would be cleaner design for these
1244 functions to set @code{errno}, but use of @code{h_errno} is compatible
1245 with other systems.)
1246
1247 Here are the error codes that you may find in @code{h_errno}:
1248
1249 @table @code
1250 @comment netdb.h
1251 @comment BSD
1252 @item HOST_NOT_FOUND
1253 @vindex HOST_NOT_FOUND
1254 No such host is known in the database.
1255
1256 @comment netdb.h
1257 @comment BSD
1258 @item TRY_AGAIN
1259 @vindex TRY_AGAIN
1260 This condition happens when the name server could not be contacted.  If
1261 you try again later, you may succeed then.
1262
1263 @comment netdb.h
1264 @comment BSD
1265 @item NO_RECOVERY
1266 @vindex NO_RECOVERY
1267 A non-recoverable error occurred.
1268
1269 @comment netdb.h
1270 @comment BSD
1271 @item NO_ADDRESS
1272 @vindex NO_ADDRESS
1273 The host database contains an entry for the name, but it doesn't have an
1274 associated Internet address.
1275 @end table
1276
1277 The lookup functions above all have one in common: they are not
1278 reentrant and therefore unusable in multi-threaded applications.
1279 Therefore provides @theglibc{} a new set of functions which can be
1280 used in this context.
1281
1282 @comment netdb.h
1283 @comment GNU
1284 @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})
1285 The @code{gethostbyname_r} function returns information about the host
1286 named @var{name}.  The caller must pass a pointer to an object of type
1287 @code{struct hostent} in the @var{result_buf} parameter.  In addition
1288 the function may need extra buffer space and the caller must pass an
1289 pointer and the size of the buffer in the @var{buf} and @var{buflen}
1290 parameters.
1291
1292 A pointer to the buffer, in which the result is stored, is available in
1293 @code{*@var{result}} after the function call successfully returned. The
1294 buffer passed as the @var{buf} parameter can be freed only once the caller
1295 has finished with the result hostent struct, or has copied it including all
1296 the other memory that it points to. If an error occurs or if no entry is
1297 found, the pointer @code{*@var{result}} is a null pointer. Success is
1298 signalled by a zero return value.  If the function failed the return value
1299 is an error number.  In addition to the errors defined for
1300 @code{gethostbyname} it can also be @code{ERANGE}. In this case the call
1301 should be repeated with a larger buffer. Additional error information is
1302 not stored in the global variable @code{h_errno} but instead in the object
1303 pointed to by @var{h_errnop}.
1304
1305 Here's a small example:
1306 @smallexample
1307 struct hostent *
1308 gethostname (char *host)
1309 @{
1310   struct hostent hostbuf, *hp;
1311   size_t hstbuflen;
1312   char *tmphstbuf;
1313   int res;
1314   int herr;
1315
1316   hstbuflen = 1024;
1317   /* Allocate buffer, remember to free it to avoid memory leakage.  */
1318   tmphstbuf = malloc (hstbuflen);
1319
1320   while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen,
1321                                  &hp, &herr)) == ERANGE)
1322     @{
1323       /* Enlarge the buffer.  */
1324       hstbuflen *= 2;
1325       tmphstbuf = realloc (tmphstbuf, hstbuflen);
1326     @}
1327   /*  Check for errors.  */
1328   if (res || hp == NULL)
1329     return NULL;
1330   return hp;
1331 @}
1332 @end smallexample
1333 @end deftypefun
1334
1335 @comment netdb.h
1336 @comment GNU
1337 @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})
1338 The @code{gethostbyname2_r} function is like @code{gethostbyname_r}, but
1339 allows the caller to specify the desired address family (e.g.@:
1340 @code{AF_INET} or @code{AF_INET6}) for the result.
1341 @end deftypefun
1342
1343 @comment netdb.h
1344 @comment GNU
1345 @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})
1346 The @code{gethostbyaddr_r} function returns information about the host
1347 with Internet address @var{addr}.  The parameter @var{addr} is not
1348 really a pointer to char - it can be a pointer to an IPv4 or an IPv6
1349 address. The @var{length} argument is the size (in bytes) of the address
1350 at @var{addr}.  @var{format} specifies the address format; for an IPv4
1351 Internet address, specify a value of @code{AF_INET}; for an IPv6
1352 Internet address, use @code{AF_INET6}.
1353
1354 Similar to the @code{gethostbyname_r} function, the caller must provide
1355 buffers for the result and memory used internally.  In case of success
1356 the function returns zero.  Otherwise the value is an error number where
1357 @code{ERANGE} has the special meaning that the caller-provided buffer is
1358 too small.
1359 @end deftypefun
1360
1361 You can also scan the entire hosts database one entry at a time using
1362 @code{sethostent}, @code{gethostent} and @code{endhostent}.  Be careful
1363 when using these functions because they are not reentrant.
1364
1365 @comment netdb.h
1366 @comment BSD
1367 @deftypefun void sethostent (int @var{stayopen})
1368 This function opens the hosts database to begin scanning it.  You can
1369 then call @code{gethostent} to read the entries.
1370
1371 @c There was a rumor that this flag has different meaning if using the DNS,
1372 @c but it appears this description is accurate in that case also.
1373 If the @var{stayopen} argument is nonzero, this sets a flag so that
1374 subsequent calls to @code{gethostbyname} or @code{gethostbyaddr} will
1375 not close the database (as they usually would).  This makes for more
1376 efficiency if you call those functions several times, by avoiding
1377 reopening the database for each call.
1378 @end deftypefun
1379
1380 @comment netdb.h
1381 @comment BSD
1382 @deftypefun {struct hostent *} gethostent (void)
1383 This function returns the next entry in the hosts database.  It
1384 returns a null pointer if there are no more entries.
1385 @end deftypefun
1386
1387 @comment netdb.h
1388 @comment BSD
1389 @deftypefun void endhostent (void)
1390 This function closes the hosts database.
1391 @end deftypefun
1392
1393 @node Ports
1394 @subsection Internet Ports
1395 @cindex port number
1396
1397 A socket address in the Internet namespace consists of a machine's
1398 Internet address plus a @dfn{port number} which distinguishes the
1399 sockets on a given machine (for a given protocol).  Port numbers range
1400 from 0 to 65,535.
1401
1402 Port numbers less than @code{IPPORT_RESERVED} are reserved for standard
1403 servers, such as @code{finger} and @code{telnet}.  There is a database
1404 that keeps track of these, and you can use the @code{getservbyname}
1405 function to map a service name onto a port number; see @ref{Services
1406 Database}.
1407
1408 If you write a server that is not one of the standard ones defined in
1409 the database, you must choose a port number for it.  Use a number
1410 greater than @code{IPPORT_USERRESERVED}; such numbers are reserved for
1411 servers and won't ever be generated automatically by the system.
1412 Avoiding conflicts with servers being run by other users is up to you.
1413
1414 When you use a socket without specifying its address, the system
1415 generates a port number for it.  This number is between
1416 @code{IPPORT_RESERVED} and @code{IPPORT_USERRESERVED}.
1417
1418 On the Internet, it is actually legitimate to have two different
1419 sockets with the same port number, as long as they never both try to
1420 communicate with the same socket address (host address plus port
1421 number).  You shouldn't duplicate a port number except in special
1422 circumstances where a higher-level protocol requires it.  Normally,
1423 the system won't let you do it; @code{bind} normally insists on
1424 distinct port numbers.  To reuse a port number, you must set the
1425 socket option @code{SO_REUSEADDR}.  @xref{Socket-Level Options}.
1426
1427 @pindex netinet/in.h
1428 These macros are defined in the header file @file{netinet/in.h}.
1429
1430 @comment netinet/in.h
1431 @comment BSD
1432 @deftypevr Macro int IPPORT_RESERVED
1433 Port numbers less than @code{IPPORT_RESERVED} are reserved for
1434 superuser use.
1435 @end deftypevr
1436
1437 @comment netinet/in.h
1438 @comment BSD
1439 @deftypevr Macro int IPPORT_USERRESERVED
1440 Port numbers greater than or equal to @code{IPPORT_USERRESERVED} are
1441 reserved for explicit use; they will never be allocated automatically.
1442 @end deftypevr
1443
1444 @node Services Database
1445 @subsection The Services Database
1446 @cindex services database
1447 @cindex converting service name to port number
1448 @cindex converting port number to service name
1449
1450 @pindex /etc/services
1451 The database that keeps track of ``well-known'' services is usually
1452 either the file @file{/etc/services} or an equivalent from a name server.
1453 You can use these utilities, declared in @file{netdb.h}, to access
1454 the services database.
1455 @pindex netdb.h
1456
1457 @comment netdb.h
1458 @comment BSD
1459 @deftp {Data Type} {struct servent}
1460 This data type holds information about entries from the services database.
1461 It has the following members:
1462
1463 @table @code
1464 @item char *s_name
1465 This is the ``official'' name of the service.
1466
1467 @item char **s_aliases
1468 These are alternate names for the service, represented as an array of
1469 strings.  A null pointer terminates the array.
1470
1471 @item int s_port
1472 This is the port number for the service.  Port numbers are given in
1473 network byte order; see @ref{Byte Order}.
1474
1475 @item char *s_proto
1476 This is the name of the protocol to use with this service.
1477 @xref{Protocols Database}.
1478 @end table
1479 @end deftp
1480
1481 To get information about a particular service, use the
1482 @code{getservbyname} or @code{getservbyport} functions.  The information
1483 is returned in a statically-allocated structure; you must copy the
1484 information if you need to save it across calls.
1485
1486 @comment netdb.h
1487 @comment BSD
1488 @deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto})
1489 The @code{getservbyname} function returns information about the
1490 service named @var{name} using protocol @var{proto}.  If it can't find
1491 such a service, it returns a null pointer.
1492
1493 This function is useful for servers as well as for clients; servers
1494 use it to determine which port they should listen on (@pxref{Listening}).
1495 @end deftypefun
1496
1497 @comment netdb.h
1498 @comment BSD
1499 @deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto})
1500 The @code{getservbyport} function returns information about the
1501 service at port @var{port} using protocol @var{proto}.  If it can't
1502 find such a service, it returns a null pointer.
1503 @end deftypefun
1504
1505 @noindent
1506 You can also scan the services database using @code{setservent},
1507 @code{getservent} and @code{endservent}.  Be careful when using these
1508 functions because they are not reentrant.
1509
1510 @comment netdb.h
1511 @comment BSD
1512 @deftypefun void setservent (int @var{stayopen})
1513 This function opens the services database to begin scanning it.
1514
1515 If the @var{stayopen} argument is nonzero, this sets a flag so that
1516 subsequent calls to @code{getservbyname} or @code{getservbyport} will
1517 not close the database (as they usually would).  This makes for more
1518 efficiency if you call those functions several times, by avoiding
1519 reopening the database for each call.
1520 @end deftypefun
1521
1522 @comment netdb.h
1523 @comment BSD
1524 @deftypefun {struct servent *} getservent (void)
1525 This function returns the next entry in the services database.  If
1526 there are no more entries, it returns a null pointer.
1527 @end deftypefun
1528
1529 @comment netdb.h
1530 @comment BSD
1531 @deftypefun void endservent (void)
1532 This function closes the services database.
1533 @end deftypefun
1534
1535 @node Byte Order
1536 @subsection Byte Order Conversion
1537 @cindex byte order conversion, for socket
1538 @cindex converting byte order
1539
1540 @cindex big-endian
1541 @cindex little-endian
1542 Different kinds of computers use different conventions for the
1543 ordering of bytes within a word.  Some computers put the most
1544 significant byte within a word first (this is called ``big-endian''
1545 order), and others put it last (``little-endian'' order).
1546
1547 @cindex network byte order
1548 So that machines with different byte order conventions can
1549 communicate, the Internet protocols specify a canonical byte order
1550 convention for data transmitted over the network.  This is known
1551 as @dfn{network byte order}.
1552
1553 When establishing an Internet socket connection, you must make sure that
1554 the data in the @code{sin_port} and @code{sin_addr} members of the
1555 @code{sockaddr_in} structure are represented in network byte order.
1556 If you are encoding integer data in the messages sent through the
1557 socket, you should convert this to network byte order too.  If you don't
1558 do this, your program may fail when running on or talking to other kinds
1559 of machines.
1560
1561 If you use @code{getservbyname} and @code{gethostbyname} or
1562 @code{inet_addr} to get the port number and host address, the values are
1563 already in network byte order, and you can copy them directly into
1564 the @code{sockaddr_in} structure.
1565
1566 Otherwise, you have to convert the values explicitly.  Use @code{htons}
1567 and @code{ntohs} to convert values for the @code{sin_port} member.  Use
1568 @code{htonl} and @code{ntohl} to convert IPv4 addresses for the
1569 @code{sin_addr} member.  (Remember, @code{struct in_addr} is equivalent
1570 to @code{uint32_t}.)  These functions are declared in
1571 @file{netinet/in.h}.
1572 @pindex netinet/in.h
1573
1574 @comment netinet/in.h
1575 @comment BSD
1576 @deftypefun {uint16_t} htons (uint16_t @var{hostshort})
1577 This function converts the @code{uint16_t} integer @var{hostshort} from
1578 host byte order to network byte order.
1579 @end deftypefun
1580
1581 @comment netinet/in.h
1582 @comment BSD
1583 @deftypefun {uint16_t} ntohs (uint16_t @var{netshort})
1584 This function converts the @code{uint16_t} integer @var{netshort} from
1585 network byte order to host byte order.
1586 @end deftypefun
1587
1588 @comment netinet/in.h
1589 @comment BSD
1590 @deftypefun {uint32_t} htonl (uint32_t @var{hostlong})
1591 This function converts the @code{uint32_t} integer @var{hostlong} from
1592 host byte order to network byte order.
1593
1594 This is used for IPv4 Internet addresses.
1595 @end deftypefun
1596
1597 @comment netinet/in.h
1598 @comment BSD
1599 @deftypefun {uint32_t} ntohl (uint32_t @var{netlong})
1600 This function converts the @code{uint32_t} integer @var{netlong} from
1601 network byte order to host byte order.
1602
1603 This is used for IPv4 Internet addresses.
1604 @end deftypefun
1605
1606 @node Protocols Database
1607 @subsection Protocols Database
1608 @cindex protocols database
1609
1610 The communications protocol used with a socket controls low-level
1611 details of how data are exchanged.  For example, the protocol implements
1612 things like checksums to detect errors in transmissions, and routing
1613 instructions for messages.  Normal user programs have little reason to
1614 mess with these details directly.
1615
1616 @cindex TCP (Internet protocol)
1617 The default communications protocol for the Internet namespace depends on
1618 the communication style.  For stream communication, the default is TCP
1619 (``transmission control protocol'').  For datagram communication, the
1620 default is UDP (``user datagram protocol'').  For reliable datagram
1621 communication, the default is RDP (``reliable datagram protocol'').
1622 You should nearly always use the default.
1623
1624 @pindex /etc/protocols
1625 Internet protocols are generally specified by a name instead of a
1626 number.  The network protocols that a host knows about are stored in a
1627 database.  This is usually either derived from the file
1628 @file{/etc/protocols}, or it may be an equivalent provided by a name
1629 server.  You look up the protocol number associated with a named
1630 protocol in the database using the @code{getprotobyname} function.
1631
1632 Here are detailed descriptions of the utilities for accessing the
1633 protocols database.  These are declared in @file{netdb.h}.
1634 @pindex netdb.h
1635
1636 @comment netdb.h
1637 @comment BSD
1638 @deftp {Data Type} {struct protoent}
1639 This data type is used to represent entries in the network protocols
1640 database.  It has the following members:
1641
1642 @table @code
1643 @item char *p_name
1644 This is the official name of the protocol.
1645
1646 @item char **p_aliases
1647 These are alternate names for the protocol, specified as an array of
1648 strings.  The last element of the array is a null pointer.
1649
1650 @item int p_proto
1651 This is the protocol number (in host byte order); use this member as the
1652 @var{protocol} argument to @code{socket}.
1653 @end table
1654 @end deftp
1655
1656 You can use @code{getprotobyname} and @code{getprotobynumber} to search
1657 the protocols database for a specific protocol.  The information is
1658 returned in a statically-allocated structure; you must copy the
1659 information if you need to save it across calls.
1660
1661 @comment netdb.h
1662 @comment BSD
1663 @deftypefun {struct protoent *} getprotobyname (const char *@var{name})
1664 The @code{getprotobyname} function returns information about the
1665 network protocol named @var{name}.  If there is no such protocol, it
1666 returns a null pointer.
1667 @end deftypefun
1668
1669 @comment netdb.h
1670 @comment BSD
1671 @deftypefun {struct protoent *} getprotobynumber (int @var{protocol})
1672 The @code{getprotobynumber} function returns information about the
1673 network protocol with number @var{protocol}.  If there is no such
1674 protocol, it returns a null pointer.
1675 @end deftypefun
1676
1677 You can also scan the whole protocols database one protocol at a time by
1678 using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}.
1679 Be careful when using these functions because they are not reentrant.
1680
1681 @comment netdb.h
1682 @comment BSD
1683 @deftypefun void setprotoent (int @var{stayopen})
1684 This function opens the protocols database to begin scanning it.
1685
1686 If the @var{stayopen} argument is nonzero, this sets a flag so that
1687 subsequent calls to @code{getprotobyname} or @code{getprotobynumber} will
1688 not close the database (as they usually would).  This makes for more
1689 efficiency if you call those functions several times, by avoiding
1690 reopening the database for each call.
1691 @end deftypefun
1692
1693 @comment netdb.h
1694 @comment BSD
1695 @deftypefun {struct protoent *} getprotoent (void)
1696 This function returns the next entry in the protocols database.  It
1697 returns a null pointer if there are no more entries.
1698 @end deftypefun
1699
1700 @comment netdb.h
1701 @comment BSD
1702 @deftypefun void endprotoent (void)
1703 This function closes the protocols database.
1704 @end deftypefun
1705
1706 @node Inet Example
1707 @subsection Internet Socket Example
1708
1709 Here is an example showing how to create and name a socket in the
1710 Internet namespace.  The newly created socket exists on the machine that
1711 the program is running on.  Rather than finding and using the machine's
1712 Internet address, this example specifies @code{INADDR_ANY} as the host
1713 address; the system replaces that with the machine's actual address.
1714
1715 @smallexample
1716 @include mkisock.c.texi
1717 @end smallexample
1718
1719 Here is another example, showing how you can fill in a @code{sockaddr_in}
1720 structure, given a host name string and a port number:
1721
1722 @smallexample
1723 @include isockad.c.texi
1724 @end smallexample
1725
1726 @node Misc Namespaces
1727 @section Other Namespaces
1728
1729 @vindex PF_NS
1730 @vindex PF_ISO
1731 @vindex PF_CCITT
1732 @vindex PF_IMPLINK
1733 @vindex PF_ROUTE
1734 Certain other namespaces and associated protocol families are supported
1735 but not documented yet because they are not often used.  @code{PF_NS}
1736 refers to the Xerox Network Software protocols.  @code{PF_ISO} stands
1737 for Open Systems Interconnect.  @code{PF_CCITT} refers to protocols from
1738 CCITT.  @file{socket.h} defines these symbols and others naming protocols
1739 not actually implemented.
1740
1741 @code{PF_IMPLINK} is used for communicating between hosts and Internet
1742 Message Processors.  For information on this and @code{PF_ROUTE}, an
1743 occasionally-used local area routing protocol, see the GNU Hurd Manual
1744 (to appear in the future).
1745
1746 @node Open/Close Sockets
1747 @section Opening and Closing Sockets
1748
1749 This section describes the actual library functions for opening and
1750 closing sockets.  The same functions work for all namespaces and
1751 connection styles.
1752
1753 @menu
1754 * Creating a Socket::           How to open a socket.
1755 * Closing a Socket::            How to close a socket.
1756 * Socket Pairs::                These are created like pipes.
1757 @end menu
1758
1759 @node Creating a Socket
1760 @subsection Creating a Socket
1761 @cindex creating a socket
1762 @cindex socket, creating
1763 @cindex opening a socket
1764
1765 The primitive for creating a socket is the @code{socket} function,
1766 declared in @file{sys/socket.h}.
1767 @pindex sys/socket.h
1768
1769 @comment sys/socket.h
1770 @comment BSD
1771 @deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol})
1772 This function creates a socket and specifies communication style
1773 @var{style}, which should be one of the socket styles listed in
1774 @ref{Communication Styles}.  The @var{namespace} argument specifies
1775 the namespace; it must be @code{PF_LOCAL} (@pxref{Local Namespace}) or
1776 @code{PF_INET} (@pxref{Internet Namespace}).  @var{protocol}
1777 designates the specific protocol (@pxref{Socket Concepts}); zero is
1778 usually right for @var{protocol}.
1779
1780 The return value from @code{socket} is the file descriptor for the new
1781 socket, or @code{-1} in case of error.  The following @code{errno} error
1782 conditions are defined for this function:
1783
1784 @table @code
1785 @item EPROTONOSUPPORT
1786 The @var{protocol} or @var{style} is not supported by the
1787 @var{namespace} specified.
1788
1789 @item EMFILE
1790 The process already has too many file descriptors open.
1791
1792 @item ENFILE
1793 The system already has too many file descriptors open.
1794
1795 @item EACCES
1796 The process does not have the privilege to create a socket of the specified
1797 @var{style} or @var{protocol}.
1798
1799 @item ENOBUFS
1800 The system ran out of internal buffer space.
1801 @end table
1802
1803 The file descriptor returned by the @code{socket} function supports both
1804 read and write operations.  However, like pipes, sockets do not support file
1805 positioning operations.
1806 @end deftypefun
1807
1808 For examples of how to call the @code{socket} function,
1809 see @ref{Local Socket Example}, or @ref{Inet Example}.
1810
1811
1812 @node Closing a Socket
1813 @subsection Closing a Socket
1814 @cindex socket, closing
1815 @cindex closing a socket
1816 @cindex shutting down a socket
1817 @cindex socket shutdown
1818
1819 When you have finished using a socket, you can simply close its
1820 file descriptor with @code{close}; see @ref{Opening and Closing Files}.
1821 If there is still data waiting to be transmitted over the connection,
1822 normally @code{close} tries to complete this transmission.  You
1823 can control this behavior using the @code{SO_LINGER} socket option to
1824 specify a timeout period; see @ref{Socket Options}.
1825
1826 @pindex sys/socket.h
1827 You can also shut down only reception or transmission on a
1828 connection by calling @code{shutdown}, which is declared in
1829 @file{sys/socket.h}.
1830
1831 @comment sys/socket.h
1832 @comment BSD
1833 @deftypefun int shutdown (int @var{socket}, int @var{how})
1834 The @code{shutdown} function shuts down the connection of socket
1835 @var{socket}.  The argument @var{how} specifies what action to
1836 perform:
1837
1838 @table @code
1839 @item 0
1840 Stop receiving data for this socket.  If further data arrives,
1841 reject it.
1842
1843 @item 1
1844 Stop trying to transmit data from this socket.  Discard any data
1845 waiting to be sent.  Stop looking for acknowledgement of data already
1846 sent; don't retransmit it if it is lost.
1847
1848 @item 2
1849 Stop both reception and transmission.
1850 @end table
1851
1852 The return value is @code{0} on success and @code{-1} on failure.  The
1853 following @code{errno} error conditions are defined for this function:
1854
1855 @table @code
1856 @item EBADF
1857 @var{socket} is not a valid file descriptor.
1858
1859 @item ENOTSOCK
1860 @var{socket} is not a socket.
1861
1862 @item ENOTCONN
1863 @var{socket} is not connected.
1864 @end table
1865 @end deftypefun
1866
1867 @node Socket Pairs
1868 @subsection Socket Pairs
1869 @cindex creating a socket pair
1870 @cindex socket pair
1871 @cindex opening a socket pair
1872
1873 @pindex sys/socket.h
1874 A @dfn{socket pair} consists of a pair of connected (but unnamed)
1875 sockets.  It is very similar to a pipe and is used in much the same
1876 way.  Socket pairs are created with the @code{socketpair} function,
1877 declared in @file{sys/socket.h}.  A socket pair is much like a pipe; the
1878 main difference is that the socket pair is bidirectional, whereas the
1879 pipe has one input-only end and one output-only end (@pxref{Pipes and
1880 FIFOs}).
1881
1882 @comment sys/socket.h
1883 @comment BSD
1884 @deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]})
1885 This function creates a socket pair, returning the file descriptors in
1886 @code{@var{filedes}[0]} and @code{@var{filedes}[1]}.  The socket pair
1887 is a full-duplex communications channel, so that both reading and writing
1888 may be performed at either end.
1889
1890 The @var{namespace}, @var{style} and @var{protocol} arguments are
1891 interpreted as for the @code{socket} function.  @var{style} should be
1892 one of the communication styles listed in @ref{Communication Styles}.
1893 The @var{namespace} argument specifies the namespace, which must be
1894 @code{AF_LOCAL} (@pxref{Local Namespace}); @var{protocol} specifies the
1895 communications protocol, but zero is the only meaningful value.
1896
1897 If @var{style} specifies a connectionless communication style, then
1898 the two sockets you get are not @emph{connected}, strictly speaking,
1899 but each of them knows the other as the default destination address,
1900 so they can send packets to each other.
1901
1902 The @code{socketpair} function returns @code{0} on success and @code{-1}
1903 on failure.  The following @code{errno} error conditions are defined
1904 for this function:
1905
1906 @table @code
1907 @item EMFILE
1908 The process has too many file descriptors open.
1909
1910 @item EAFNOSUPPORT
1911 The specified namespace is not supported.
1912
1913 @item EPROTONOSUPPORT
1914 The specified protocol is not supported.
1915
1916 @item EOPNOTSUPP
1917 The specified protocol does not support the creation of socket pairs.
1918 @end table
1919 @end deftypefun
1920
1921 @node Connections
1922 @section Using Sockets with Connections
1923
1924 @cindex connection
1925 @cindex client
1926 @cindex server
1927 The most common communication styles involve making a connection to a
1928 particular other socket, and then exchanging data with that socket
1929 over and over.  Making a connection is asymmetric; one side (the
1930 @dfn{client}) acts to request a connection, while the other side (the
1931 @dfn{server}) makes a socket and waits for the connection request.
1932
1933 @iftex
1934 @itemize @bullet
1935 @item
1936 @ref{Connecting}, describes what the client program must do to
1937 initiate a connection with a server.
1938
1939 @item
1940 @ref{Listening} and @ref{Accepting Connections} describe what the
1941 server program must do to wait for and act upon connection requests
1942 from clients.
1943
1944 @item
1945 @ref{Transferring Data}, describes how data are transferred through the
1946 connected socket.
1947 @end itemize
1948 @end iftex
1949
1950 @menu
1951 * Connecting::               What the client program must do.
1952 * Listening::                How a server program waits for requests.
1953 * Accepting Connections::    What the server does when it gets a request.
1954 * Who is Connected::         Getting the address of the
1955                                 other side of a connection.
1956 * Transferring Data::        How to send and receive data.
1957 * Byte Stream Example::      An example program: a client for communicating
1958                               over a byte stream socket in the Internet namespace.
1959 * Server Example::           A corresponding server program.
1960 * Out-of-Band Data::         This is an advanced feature.
1961 @end menu
1962
1963 @node Connecting
1964 @subsection Making a Connection
1965 @cindex connecting a socket
1966 @cindex socket, connecting
1967 @cindex socket, initiating a connection
1968 @cindex socket, client actions
1969
1970 In making a connection, the client makes a connection while the server
1971 waits for and accepts the connection.  Here we discuss what the client
1972 program must do with the @code{connect} function, which is declared in
1973 @file{sys/socket.h}.
1974
1975 @comment sys/socket.h
1976 @comment BSD
1977 @deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
1978 The @code{connect} function initiates a connection from the socket
1979 with file descriptor @var{socket} to the socket whose address is
1980 specified by the @var{addr} and @var{length} arguments.  (This socket
1981 is typically on another machine, and it must be already set up as a
1982 server.)  @xref{Socket Addresses}, for information about how these
1983 arguments are interpreted.
1984
1985 Normally, @code{connect} waits until the server responds to the request
1986 before it returns.  You can set nonblocking mode on the socket
1987 @var{socket} to make @code{connect} return immediately without waiting
1988 for the response.  @xref{File Status Flags}, for information about
1989 nonblocking mode.
1990 @c !!! how do you tell when it has finished connecting?  I suspect the
1991 @c way you do it is select for writing.
1992
1993 The normal return value from @code{connect} is @code{0}.  If an error
1994 occurs, @code{connect} returns @code{-1}.  The following @code{errno}
1995 error conditions are defined for this function:
1996
1997 @table @code
1998 @item EBADF
1999 The socket @var{socket} is not a valid file descriptor.
2000
2001 @item ENOTSOCK
2002 File descriptor @var{socket} is not a socket.
2003
2004 @item EADDRNOTAVAIL
2005 The specified address is not available on the remote machine.
2006
2007 @item EAFNOSUPPORT
2008 The namespace of the @var{addr} is not supported by this socket.
2009
2010 @item EISCONN
2011 The socket @var{socket} is already connected.
2012
2013 @item ETIMEDOUT
2014 The attempt to establish the connection timed out.
2015
2016 @item ECONNREFUSED
2017 The server has actively refused to establish the connection.
2018
2019 @item ENETUNREACH
2020 The network of the given @var{addr} isn't reachable from this host.
2021
2022 @item EADDRINUSE
2023 The socket address of the given @var{addr} is already in use.
2024
2025 @item EINPROGRESS
2026 The socket @var{socket} is non-blocking and the connection could not be
2027 established immediately.  You can determine when the connection is
2028 completely established with @code{select}; @pxref{Waiting for I/O}.
2029 Another @code{connect} call on the same socket, before the connection is
2030 completely established, will fail with @code{EALREADY}.
2031
2032 @item EALREADY
2033 The socket @var{socket} is non-blocking and already has a pending
2034 connection in progress (see @code{EINPROGRESS} above).
2035 @end table
2036
2037 This function is defined as a cancellation point in multi-threaded
2038 programs, so one has to be prepared for this and make sure that
2039 allocated resources (like memory, files descriptors, semaphores or
2040 whatever) are freed even if the thread is canceled.
2041 @c @xref{pthread_cleanup_push}, for a method how to do this.
2042 @end deftypefun
2043
2044 @node Listening
2045 @subsection Listening for Connections
2046 @cindex listening (sockets)
2047 @cindex sockets, server actions
2048 @cindex sockets, listening
2049
2050 Now let us consider what the server process must do to accept
2051 connections on a socket.  First it must use the @code{listen} function
2052 to enable connection requests on the socket, and then accept each
2053 incoming connection with a call to @code{accept} (@pxref{Accepting
2054 Connections}).  Once connection requests are enabled on a server socket,
2055 the @code{select} function reports when the socket has a connection
2056 ready to be accepted (@pxref{Waiting for I/O}).
2057
2058 The @code{listen} function is not allowed for sockets using
2059 connectionless communication styles.
2060
2061 You can write a network server that does not even start running until a
2062 connection to it is requested.  @xref{Inetd Servers}.
2063
2064 In the Internet namespace, there are no special protection mechanisms
2065 for controlling access to a port; any process on any machine
2066 can make a connection to your server.  If you want to restrict access to
2067 your server, make it examine the addresses associated with connection
2068 requests or implement some other handshaking or identification
2069 protocol.
2070
2071 In the local namespace, the ordinary file protection bits control who has
2072 access to connect to the socket.
2073
2074 @comment sys/socket.h
2075 @comment BSD
2076 @deftypefun int listen (int @var{socket}, int @var{n})
2077 The @code{listen} function enables the socket @var{socket} to accept
2078 connections, thus making it a server socket.
2079
2080 The argument @var{n} specifies the length of the queue for pending
2081 connections.  When the queue fills, new clients attempting to connect
2082 fail with @code{ECONNREFUSED} until the server calls @code{accept} to
2083 accept a connection from the queue.
2084
2085 The @code{listen} function returns @code{0} on success and @code{-1}
2086 on failure.  The following @code{errno} error conditions are defined
2087 for this function:
2088
2089 @table @code
2090 @item EBADF
2091 The argument @var{socket} is not a valid file descriptor.
2092
2093 @item ENOTSOCK
2094 The argument @var{socket} is not a socket.
2095
2096 @item EOPNOTSUPP
2097 The socket @var{socket} does not support this operation.
2098 @end table
2099 @end deftypefun
2100
2101 @node Accepting Connections
2102 @subsection Accepting Connections
2103 @cindex sockets, accepting connections
2104 @cindex accepting connections
2105
2106 When a server receives a connection request, it can complete the
2107 connection by accepting the request.  Use the function @code{accept}
2108 to do this.
2109
2110 A socket that has been established as a server can accept connection
2111 requests from multiple clients.  The server's original socket
2112 @emph{does not become part of the connection}; instead, @code{accept}
2113 makes a new socket which participates in the connection.
2114 @code{accept} returns the descriptor for this socket.  The server's
2115 original socket remains available for listening for further connection
2116 requests.
2117
2118 The number of pending connection requests on a server socket is finite.
2119 If connection requests arrive from clients faster than the server can
2120 act upon them, the queue can fill up and additional requests are refused
2121 with an @code{ECONNREFUSED} error.  You can specify the maximum length of
2122 this queue as an argument to the @code{listen} function, although the
2123 system may also impose its own internal limit on the length of this
2124 queue.
2125
2126 @comment sys/socket.h
2127 @comment BSD
2128 @deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length_ptr})
2129 This function is used to accept a connection request on the server
2130 socket @var{socket}.
2131
2132 The @code{accept} function waits if there are no connections pending,
2133 unless the socket @var{socket} has nonblocking mode set.  (You can use
2134 @code{select} to wait for a pending connection, with a nonblocking
2135 socket.)  @xref{File Status Flags}, for information about nonblocking
2136 mode.
2137
2138 The @var{addr} and @var{length-ptr} arguments are used to return
2139 information about the name of the client socket that initiated the
2140 connection.  @xref{Socket Addresses}, for information about the format
2141 of the information.
2142
2143 Accepting a connection does not make @var{socket} part of the
2144 connection.  Instead, it creates a new socket which becomes
2145 connected.  The normal return value of @code{accept} is the file
2146 descriptor for the new socket.
2147
2148 After @code{accept}, the original socket @var{socket} remains open and
2149 unconnected, and continues listening until you close it.  You can
2150 accept further connections with @var{socket} by calling @code{accept}
2151 again.
2152
2153 If an error occurs, @code{accept} returns @code{-1}.  The following
2154 @code{errno} error conditions are defined for this function:
2155
2156 @table @code
2157 @item EBADF
2158 The @var{socket} argument is not a valid file descriptor.
2159
2160 @item ENOTSOCK
2161 The descriptor @var{socket} argument is not a socket.
2162
2163 @item EOPNOTSUPP
2164 The descriptor @var{socket} does not support this operation.
2165
2166 @item EWOULDBLOCK
2167 @var{socket} has nonblocking mode set, and there are no pending
2168 connections immediately available.
2169 @end table
2170
2171 This function is defined as a cancellation point in multi-threaded
2172 programs, so one has to be prepared for this and make sure that
2173 allocated resources (like memory, files descriptors, semaphores or
2174 whatever) are freed even if the thread is canceled.
2175 @c @xref{pthread_cleanup_push}, for a method how to do this.
2176 @end deftypefun
2177
2178 The @code{accept} function is not allowed for sockets using
2179 connectionless communication styles.
2180
2181 @node Who is Connected
2182 @subsection Who is Connected to Me?
2183
2184 @comment sys/socket.h
2185 @comment BSD
2186 @deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
2187 The @code{getpeername} function returns the address of the socket that
2188 @var{socket} is connected to; it stores the address in the memory space
2189 specified by @var{addr} and @var{length-ptr}.  It stores the length of
2190 the address in @code{*@var{length-ptr}}.
2191
2192 @xref{Socket Addresses}, for information about the format of the
2193 address.  In some operating systems, @code{getpeername} works only for
2194 sockets in the Internet domain.
2195
2196 The return value is @code{0} on success and @code{-1} on error.  The
2197 following @code{errno} error conditions are defined for this function:
2198
2199 @table @code
2200 @item EBADF
2201 The argument @var{socket} is not a valid file descriptor.
2202
2203 @item ENOTSOCK
2204 The descriptor @var{socket} is not a socket.
2205
2206 @item ENOTCONN
2207 The socket @var{socket} is not connected.
2208
2209 @item ENOBUFS
2210 There are not enough internal buffers available.
2211 @end table
2212 @end deftypefun
2213
2214
2215 @node Transferring Data
2216 @subsection Transferring Data
2217 @cindex reading from a socket
2218 @cindex writing to a socket
2219
2220 Once a socket has been connected to a peer, you can use the ordinary
2221 @code{read} and @code{write} operations (@pxref{I/O Primitives}) to
2222 transfer data.  A socket is a two-way communications channel, so read
2223 and write operations can be performed at either end.
2224
2225 There are also some I/O modes that are specific to socket operations.
2226 In order to specify these modes, you must use the @code{recv} and
2227 @code{send} functions instead of the more generic @code{read} and
2228 @code{write} functions.  The @code{recv} and @code{send} functions take
2229 an additional argument which you can use to specify various flags to
2230 control special I/O modes.  For example, you can specify the
2231 @code{MSG_OOB} flag to read or write out-of-band data, the
2232 @code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag
2233 to control inclusion of routing information on output.
2234
2235 @menu
2236 * Sending Data::                Sending data with @code{send}.
2237 * Receiving Data::              Reading data with @code{recv}.
2238 * Socket Data Options::         Using @code{send} and @code{recv}.
2239 @end menu
2240
2241 @node Sending Data
2242 @subsubsection Sending Data
2243
2244 @pindex sys/socket.h
2245 The @code{send} function is declared in the header file
2246 @file{sys/socket.h}.  If your @var{flags} argument is zero, you can just
2247 as well use @code{write} instead of @code{send}; see @ref{I/O
2248 Primitives}.  If the socket was connected but the connection has broken,
2249 you get a @code{SIGPIPE} signal for any use of @code{send} or
2250 @code{write} (@pxref{Miscellaneous Signals}).
2251
2252 @comment sys/socket.h
2253 @comment BSD
2254 @deftypefun ssize_t send (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags})
2255 The @code{send} function is like @code{write}, but with the additional
2256 flags @var{flags}.  The possible values of @var{flags} are described
2257 in @ref{Socket Data Options}.
2258
2259 This function returns the number of bytes transmitted, or @code{-1} on
2260 failure.  If the socket is nonblocking, then @code{send} (like
2261 @code{write}) can return after sending just part of the data.
2262 @xref{File Status Flags}, for information about nonblocking mode.
2263
2264 Note, however, that a successful return value merely indicates that
2265 the message has been sent without error, not necessarily that it has
2266 been received without error.
2267
2268 The following @code{errno} error conditions are defined for this function:
2269
2270 @table @code
2271 @item EBADF
2272 The @var{socket} argument is not a valid file descriptor.
2273
2274 @item EINTR
2275 The operation was interrupted by a signal before any data was sent.
2276 @xref{Interrupted Primitives}.
2277
2278 @item ENOTSOCK
2279 The descriptor @var{socket} is not a socket.
2280
2281 @item EMSGSIZE
2282 The socket type requires that the message be sent atomically, but the
2283 message is too large for this to be possible.
2284
2285 @item EWOULDBLOCK
2286 Nonblocking mode has been set on the socket, and the write operation
2287 would block.  (Normally @code{send} blocks until the operation can be
2288 completed.)
2289
2290 @item ENOBUFS
2291 There is not enough internal buffer space available.
2292
2293 @item ENOTCONN
2294 You never connected this socket.
2295
2296 @item EPIPE
2297 This socket was connected but the connection is now broken.  In this
2298 case, @code{send} generates a @code{SIGPIPE} signal first; if that
2299 signal is ignored or blocked, or if its handler returns, then
2300 @code{send} fails with @code{EPIPE}.
2301 @end table
2302
2303 This function is defined as a cancellation point in multi-threaded
2304 programs, so one has to be prepared for this and make sure that
2305 allocated resources (like memory, files descriptors, semaphores or
2306 whatever) are freed even if the thread is canceled.
2307 @c @xref{pthread_cleanup_push}, for a method how to do this.
2308 @end deftypefun
2309
2310 @node Receiving Data
2311 @subsubsection Receiving Data
2312
2313 @pindex sys/socket.h
2314 The @code{recv} function is declared in the header file
2315 @file{sys/socket.h}.  If your @var{flags} argument is zero, you can
2316 just as well use @code{read} instead of @code{recv}; see @ref{I/O
2317 Primitives}.
2318
2319 @comment sys/socket.h
2320 @comment BSD
2321 @deftypefun ssize_t recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags})
2322 The @code{recv} function is like @code{read}, but with the additional
2323 flags @var{flags}.  The possible values of @var{flags} are described
2324 in @ref{Socket Data Options}.
2325
2326 If nonblocking mode is set for @var{socket}, and no data are available to
2327 be read, @code{recv} fails immediately rather than waiting.  @xref{File
2328 Status Flags}, for information about nonblocking mode.
2329
2330 This function returns the number of bytes received, or @code{-1} on failure.
2331 The following @code{errno} error conditions are defined for this function:
2332
2333 @table @code
2334 @item EBADF
2335 The @var{socket} argument is not a valid file descriptor.
2336
2337 @item ENOTSOCK
2338 The descriptor @var{socket} is not a socket.
2339
2340 @item EWOULDBLOCK
2341 Nonblocking mode has been set on the socket, and the read operation
2342 would block.  (Normally, @code{recv} blocks until there is input
2343 available to be read.)
2344
2345 @item EINTR
2346 The operation was interrupted by a signal before any data was read.
2347 @xref{Interrupted Primitives}.
2348
2349 @item ENOTCONN
2350 You never connected this socket.
2351 @end table
2352
2353 This function is defined as a cancellation point in multi-threaded
2354 programs, so one has to be prepared for this and make sure that
2355 allocated resources (like memory, files descriptors, semaphores or
2356 whatever) are freed even if the thread is canceled.
2357 @c @xref{pthread_cleanup_push}, for a method how to do this.
2358 @end deftypefun
2359
2360 @node Socket Data Options
2361 @subsubsection Socket Data Options
2362
2363 @pindex sys/socket.h
2364 The @var{flags} argument to @code{send} and @code{recv} is a bit
2365 mask.  You can bitwise-OR the values of the following macros together
2366 to obtain a value for this argument.  All are defined in the header
2367 file @file{sys/socket.h}.
2368
2369 @comment sys/socket.h
2370 @comment BSD
2371 @deftypevr Macro int MSG_OOB
2372 Send or receive out-of-band data.  @xref{Out-of-Band Data}.
2373 @end deftypevr
2374
2375 @comment sys/socket.h
2376 @comment BSD
2377 @deftypevr Macro int MSG_PEEK
2378 Look at the data but don't remove it from the input queue.  This is
2379 only meaningful with input functions such as @code{recv}, not with
2380 @code{send}.
2381 @end deftypevr
2382
2383 @comment sys/socket.h
2384 @comment BSD
2385 @deftypevr Macro int MSG_DONTROUTE
2386 Don't include routing information in the message.  This is only
2387 meaningful with output operations, and is usually only of interest for
2388 diagnostic or routing programs.  We don't try to explain it here.
2389 @end deftypevr
2390
2391 @node Byte Stream Example
2392 @subsection Byte Stream Socket Example
2393
2394 Here is an example client program that makes a connection for a byte
2395 stream socket in the Internet namespace.  It doesn't do anything
2396 particularly interesting once it has connected to the server; it just
2397 sends a text string to the server and exits.
2398
2399 This program uses @code{init_sockaddr} to set up the socket address; see
2400 @ref{Inet Example}.
2401
2402 @smallexample
2403 @include inetcli.c.texi
2404 @end smallexample
2405
2406 @node Server Example
2407 @subsection Byte Stream Connection Server Example
2408
2409 The server end is much more complicated.  Since we want to allow
2410 multiple clients to be connected to the server at the same time, it
2411 would be incorrect to wait for input from a single client by simply
2412 calling @code{read} or @code{recv}.  Instead, the right thing to do is
2413 to use @code{select} (@pxref{Waiting for I/O}) to wait for input on
2414 all of the open sockets.  This also allows the server to deal with
2415 additional connection requests.
2416
2417 This particular server doesn't do anything interesting once it has
2418 gotten a message from a client.  It does close the socket for that
2419 client when it detects an end-of-file condition (resulting from the
2420 client shutting down its end of the connection).
2421
2422 This program uses @code{make_socket} to set up the socket address; see
2423 @ref{Inet Example}.
2424
2425 @smallexample
2426 @include inetsrv.c.texi
2427 @end smallexample
2428
2429 @node Out-of-Band Data
2430 @subsection Out-of-Band Data
2431
2432 @cindex out-of-band data
2433 @cindex high-priority data
2434 Streams with connections permit @dfn{out-of-band} data that is
2435 delivered with higher priority than ordinary data.  Typically the
2436 reason for sending out-of-band data is to send notice of an
2437 exceptional condition.  To send out-of-band data use
2438 @code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending
2439 Data}).
2440
2441 Out-of-band data are received with higher priority because the
2442 receiving process need not read it in sequence; to read the next
2443 available out-of-band data, use @code{recv} with the @code{MSG_OOB}
2444 flag (@pxref{Receiving Data}).  Ordinary read operations do not read
2445 out-of-band data; they read only ordinary data.
2446
2447 @cindex urgent socket condition
2448 When a socket finds that out-of-band data are on their way, it sends a
2449 @code{SIGURG} signal to the owner process or process group of the
2450 socket.  You can specify the owner using the @code{F_SETOWN} command
2451 to the @code{fcntl} function; see @ref{Interrupt Input}.  You must
2452 also establish a handler for this signal, as described in @ref{Signal
2453 Handling}, in order to take appropriate action such as reading the
2454 out-of-band data.
2455
2456 Alternatively, you can test for pending out-of-band data, or wait
2457 until there is out-of-band data, using the @code{select} function; it
2458 can wait for an exceptional condition on the socket.  @xref{Waiting
2459 for I/O}, for more information about @code{select}.
2460
2461 Notification of out-of-band data (whether with @code{SIGURG} or with
2462 @code{select}) indicates that out-of-band data are on the way; the data
2463 may not actually arrive until later.  If you try to read the
2464 out-of-band data before it arrives, @code{recv} fails with an
2465 @code{EWOULDBLOCK} error.
2466
2467 Sending out-of-band data automatically places a ``mark'' in the stream
2468 of ordinary data, showing where in the sequence the out-of-band data
2469 ``would have been''.  This is useful when the meaning of out-of-band
2470 data is ``cancel everything sent so far''.  Here is how you can test,
2471 in the receiving process, whether any ordinary data was sent before
2472 the mark:
2473
2474 @smallexample
2475 success = ioctl (socket, SIOCATMARK, &atmark);
2476 @end smallexample
2477
2478 The @code{integer} variable @var{atmark} is set to a nonzero value if
2479 the socket's read pointer has reached the ``mark''.
2480
2481 @c Posix  1.g specifies sockatmark for this ioctl.  sockatmark is not
2482 @c implemented yet.
2483
2484 Here's a function to discard any ordinary data preceding the
2485 out-of-band mark:
2486
2487 @smallexample
2488 int
2489 discard_until_mark (int socket)
2490 @{
2491   while (1)
2492     @{
2493       /* @r{This is not an arbitrary limit; any size will do.}  */
2494       char buffer[1024];
2495       int atmark, success;
2496
2497       /* @r{If we have reached the mark, return.}  */
2498       success = ioctl (socket, SIOCATMARK, &atmark);
2499       if (success < 0)
2500         perror ("ioctl");
2501       if (result)
2502         return;
2503
2504       /* @r{Otherwise, read a bunch of ordinary data and discard it.}
2505          @r{This is guaranteed not to read past the mark}
2506          @r{if it starts before the mark.}  */
2507       success = read (socket, buffer, sizeof buffer);
2508       if (success < 0)
2509         perror ("read");
2510     @}
2511 @}
2512 @end smallexample
2513
2514 If you don't want to discard the ordinary data preceding the mark, you
2515 may need to read some of it anyway, to make room in internal system
2516 buffers for the out-of-band data.  If you try to read out-of-band data
2517 and get an @code{EWOULDBLOCK} error, try reading some ordinary data
2518 (saving it so that you can use it when you want it) and see if that
2519 makes room.  Here is an example:
2520
2521 @smallexample
2522 struct buffer
2523 @{
2524   char *buf;
2525   int size;
2526   struct buffer *next;
2527 @};
2528
2529 /* @r{Read the out-of-band data from SOCKET and return it}
2530    @r{as a `struct buffer', which records the address of the data}
2531    @r{and its size.}
2532
2533    @r{It may be necessary to read some ordinary data}
2534    @r{in order to make room for the out-of-band data.}
2535    @r{If so, the ordinary data are saved as a chain of buffers}
2536    @r{found in the `next' field of the value.}  */
2537
2538 struct buffer *
2539 read_oob (int socket)
2540 @{
2541   struct buffer *tail = 0;
2542   struct buffer *list = 0;
2543
2544   while (1)
2545     @{
2546       /* @r{This is an arbitrary limit.}
2547          @r{Does anyone know how to do this without a limit?}  */
2548 #define BUF_SZ 1024
2549       char *buf = (char *) xmalloc (BUF_SZ);
2550       int success;
2551       int atmark;
2552
2553       /* @r{Try again to read the out-of-band data.}  */
2554       success = recv (socket, buf, BUF_SZ, MSG_OOB);
2555       if (success >= 0)
2556         @{
2557           /* @r{We got it, so return it.}  */
2558           struct buffer *link
2559             = (struct buffer *) xmalloc (sizeof (struct buffer));
2560           link->buf = buf;
2561           link->size = success;
2562           link->next = list;
2563           return link;
2564         @}
2565
2566       /* @r{If we fail, see if we are at the mark.}  */
2567       success = ioctl (socket, SIOCATMARK, &atmark);
2568       if (success < 0)
2569         perror ("ioctl");
2570       if (atmark)
2571         @{
2572           /* @r{At the mark; skipping past more ordinary data cannot help.}
2573              @r{So just wait a while.}  */
2574           sleep (1);
2575           continue;
2576         @}
2577
2578       /* @r{Otherwise, read a bunch of ordinary data and save it.}
2579          @r{This is guaranteed not to read past the mark}
2580          @r{if it starts before the mark.}  */
2581       success = read (socket, buf, BUF_SZ);
2582       if (success < 0)
2583         perror ("read");
2584
2585       /* @r{Save this data in the buffer list.}  */
2586       @{
2587         struct buffer *link
2588           = (struct buffer *) xmalloc (sizeof (struct buffer));
2589         link->buf = buf;
2590         link->size = success;
2591
2592         /* @r{Add the new link to the end of the list.}  */
2593         if (tail)
2594           tail->next = link;
2595         else
2596           list = link;
2597         tail = link;
2598       @}
2599     @}
2600 @}
2601 @end smallexample
2602
2603 @node Datagrams
2604 @section Datagram Socket Operations
2605
2606 @cindex datagram socket
2607 This section describes how to use communication styles that don't use
2608 connections (styles @code{SOCK_DGRAM} and @code{SOCK_RDM}).  Using
2609 these styles, you group data into packets and each packet is an
2610 independent communication.  You specify the destination for each
2611 packet individually.
2612
2613 Datagram packets are like letters: you send each one independently
2614 with its own destination address, and they may arrive in the wrong
2615 order or not at all.
2616
2617 The @code{listen} and @code{accept} functions are not allowed for
2618 sockets using connectionless communication styles.
2619
2620 @menu
2621 * Sending Datagrams::    Sending packets on a datagram socket.
2622 * Receiving Datagrams::  Receiving packets on a datagram socket.
2623 * Datagram Example::     An example program: packets sent over a
2624                            datagram socket in the local namespace.
2625 * Example Receiver::     Another program, that receives those packets.
2626 @end menu
2627
2628 @node Sending Datagrams
2629 @subsection Sending Datagrams
2630 @cindex sending a datagram
2631 @cindex transmitting datagrams
2632 @cindex datagrams, transmitting
2633
2634 @pindex sys/socket.h
2635 The normal way of sending data on a datagram socket is by using the
2636 @code{sendto} function, declared in @file{sys/socket.h}.
2637
2638 You can call @code{connect} on a datagram socket, but this only
2639 specifies a default destination for further data transmission on the
2640 socket.  When a socket has a default destination you can use
2641 @code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O
2642 Primitives}) to send a packet there.  You can cancel the default
2643 destination by calling @code{connect} using an address format of
2644 @code{AF_UNSPEC} in the @var{addr} argument.  @xref{Connecting}, for
2645 more information about the @code{connect} function.
2646
2647 @comment sys/socket.h
2648 @comment BSD
2649 @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})
2650 The @code{sendto} function transmits the data in the @var{buffer}
2651 through the socket @var{socket} to the destination address specified
2652 by the @var{addr} and @var{length} arguments.  The @var{size} argument
2653 specifies the number of bytes to be transmitted.
2654
2655 The @var{flags} are interpreted the same way as for @code{send}; see
2656 @ref{Socket Data Options}.
2657
2658 The return value and error conditions are also the same as for
2659 @code{send}, but you cannot rely on the system to detect errors and
2660 report them; the most common error is that the packet is lost or there
2661 is no-one at the specified address to receive it, and the operating
2662 system on your machine usually does not know this.
2663
2664 It is also possible for one call to @code{sendto} to report an error
2665 owing to a problem related to a previous call.
2666
2667 This function is defined as a cancellation point in multi-threaded
2668 programs, so one has to be prepared for this and make sure that
2669 allocated resources (like memory, files descriptors, semaphores or
2670 whatever) are freed even if the thread is canceled.
2671 @c @xref{pthread_cleanup_push}, for a method how to do this.
2672 @end deftypefun
2673
2674 @node Receiving Datagrams
2675 @subsection Receiving Datagrams
2676 @cindex receiving datagrams
2677
2678 The @code{recvfrom} function reads a packet from a datagram socket and
2679 also tells you where it was sent from.  This function is declared in
2680 @file{sys/socket.h}.
2681
2682 @comment sys/socket.h
2683 @comment BSD
2684 @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})
2685 The @code{recvfrom} function reads one packet from the socket
2686 @var{socket} into the buffer @var{buffer}.  The @var{size} argument
2687 specifies the maximum number of bytes to be read.
2688
2689 If the packet is longer than @var{size} bytes, then you get the first
2690 @var{size} bytes of the packet and the rest of the packet is lost.
2691 There's no way to read the rest of the packet.  Thus, when you use a
2692 packet protocol, you must always know how long a packet to expect.
2693
2694 The @var{addr} and @var{length-ptr} arguments are used to return the
2695 address where the packet came from.  @xref{Socket Addresses}.  For a
2696 socket in the local domain the address information won't be meaningful,
2697 since you can't read the address of such a socket (@pxref{Local
2698 Namespace}).  You can specify a null pointer as the @var{addr} argument
2699 if you are not interested in this information.
2700
2701 The @var{flags} are interpreted the same way as for @code{recv}
2702 (@pxref{Socket Data Options}).  The return value and error conditions
2703 are also the same as for @code{recv}.
2704
2705 This function is defined as a cancellation point in multi-threaded
2706 programs, so one has to be prepared for this and make sure that
2707 allocated resources (like memory, files descriptors, semaphores or
2708 whatever) are freed even if the thread is canceled.
2709 @c @xref{pthread_cleanup_push}, for a method how to do this.
2710 @end deftypefun
2711
2712 You can use plain @code{recv} (@pxref{Receiving Data}) instead of
2713 @code{recvfrom} if you don't need to find out who sent the packet
2714 (either because you know where it should come from or because you
2715 treat all possible senders alike).  Even @code{read} can be used if
2716 you don't want to specify @var{flags} (@pxref{I/O Primitives}).
2717
2718 @ignore
2719 @c sendmsg and recvmsg are like readv and writev in that they
2720 @c use a series of buffers.  It's not clear this is worth
2721 @c supporting or that we support them.
2722 @c !!! they can do more; it is hairy
2723
2724 @comment sys/socket.h
2725 @comment BSD
2726 @deftp {Data Type} {struct msghdr}
2727 @end deftp
2728
2729 @comment sys/socket.h
2730 @comment BSD
2731 @deftypefun ssize_t sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags})
2732
2733 This function is defined as a cancellation point in multi-threaded
2734 programs, so one has to be prepared for this and make sure that
2735 allocated resources (like memory, files descriptors, semaphores or
2736 whatever) are freed even if the thread is cancel.
2737 @c @xref{pthread_cleanup_push}, for a method how to do this.
2738 @end deftypefun
2739
2740 @comment sys/socket.h
2741 @comment BSD
2742 @deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
2743
2744 This function is defined as a cancellation point in multi-threaded
2745 programs, so one has to be prepared for this and make sure that
2746 allocated resources (like memory, files descriptors, semaphores or
2747 whatever) are freed even if the thread is canceled.
2748 @c @xref{pthread_cleanup_push}, for a method how to do this.
2749 @end deftypefun
2750 @end ignore
2751
2752 @node Datagram Example
2753 @subsection Datagram Socket Example
2754
2755 Here is a set of example programs that send messages over a datagram
2756 stream in the local namespace.  Both the client and server programs use
2757 the @code{make_named_socket} function that was presented in @ref{Local
2758 Socket Example}, to create and name their sockets.
2759
2760 First, here is the server program.  It sits in a loop waiting for
2761 messages to arrive, bouncing each message back to the sender.
2762 Obviously this isn't a particularly useful program, but it does show
2763 the general ideas involved.
2764
2765 @smallexample
2766 @include filesrv.c.texi
2767 @end smallexample
2768
2769 @node Example Receiver
2770 @subsection Example of Reading Datagrams
2771
2772 Here is the client program corresponding to the server above.
2773
2774 It sends a datagram to the server and then waits for a reply.  Notice
2775 that the socket for the client (as well as for the server) in this
2776 example has to be given a name.  This is so that the server can direct
2777 a message back to the client.  Since the socket has no associated
2778 connection state, the only way the server can do this is by
2779 referencing the name of the client.
2780
2781 @smallexample
2782 @include filecli.c.texi
2783 @end smallexample
2784
2785 Keep in mind that datagram socket communications are unreliable.  In
2786 this example, the client program waits indefinitely if the message
2787 never reaches the server or if the server's response never comes
2788 back.  It's up to the user running the program to kill and restart
2789 it if desired.  A more automatic solution could be to use
2790 @code{select} (@pxref{Waiting for I/O}) to establish a timeout period
2791 for the reply, and in case of timeout either re-send the message or
2792 shut down the socket and exit.
2793
2794 @node Inetd
2795 @section The @code{inetd} Daemon
2796
2797 We've explained above how to write a server program that does its own
2798 listening.  Such a server must already be running in order for anyone
2799 to connect to it.
2800
2801 Another way to provide a service on an Internet port is to let the daemon
2802 program @code{inetd} do the listening.  @code{inetd} is a program that
2803 runs all the time and waits (using @code{select}) for messages on a
2804 specified set of ports.  When it receives a message, it accepts the
2805 connection (if the socket style calls for connections) and then forks a
2806 child process to run the corresponding server program.  You specify the
2807 ports and their programs in the file @file{/etc/inetd.conf}.
2808
2809 @menu
2810 * Inetd Servers::
2811 * Configuring Inetd::
2812 @end menu
2813
2814 @node Inetd Servers
2815 @subsection @code{inetd} Servers
2816
2817 Writing a server program to be run by @code{inetd} is very simple.  Each time
2818 someone requests a connection to the appropriate port, a new server
2819 process starts.  The connection already exists at this time; the
2820 socket is available as the standard input descriptor and as the
2821 standard output descriptor (descriptors 0 and 1) in the server
2822 process.  Thus the server program can begin reading and writing data
2823 right away.  Often the program needs only the ordinary I/O facilities;
2824 in fact, a general-purpose filter program that knows nothing about
2825 sockets can work as a byte stream server run by @code{inetd}.
2826
2827 You can also use @code{inetd} for servers that use connectionless
2828 communication styles.  For these servers, @code{inetd} does not try to accept
2829 a connection since no connection is possible.  It just starts the
2830 server program, which can read the incoming datagram packet from
2831 descriptor 0.  The server program can handle one request and then
2832 exit, or you can choose to write it to keep reading more requests
2833 until no more arrive, and then exit.  You must specify which of these
2834 two techniques the server uses when you configure @code{inetd}.
2835
2836 @node Configuring Inetd
2837 @subsection Configuring @code{inetd}
2838
2839 The file @file{/etc/inetd.conf} tells @code{inetd} which ports to listen to
2840 and what server programs to run for them.  Normally each entry in the
2841 file is one line, but you can split it onto multiple lines provided
2842 all but the first line of the entry start with whitespace.  Lines that
2843 start with @samp{#} are comments.
2844
2845 Here are two standard entries in @file{/etc/inetd.conf}:
2846
2847 @smallexample
2848 ftp     stream  tcp     nowait  root    /libexec/ftpd   ftpd
2849 talk    dgram   udp     wait    root    /libexec/talkd  talkd
2850 @end smallexample
2851
2852 An entry has this format:
2853
2854 @smallexample
2855 @var{service} @var{style} @var{protocol} @var{wait} @var{username} @var{program} @var{arguments}
2856 @end smallexample
2857
2858 The @var{service} field says which service this program provides.  It
2859 should be the name of a service defined in @file{/etc/services}.
2860 @code{inetd} uses @var{service} to decide which port to listen on for
2861 this entry.
2862
2863 The fields @var{style} and @var{protocol} specify the communication
2864 style and the protocol to use for the listening socket.  The style
2865 should be the name of a communication style, converted to lower case
2866 and with @samp{SOCK_} deleted---for example, @samp{stream} or
2867 @samp{dgram}.  @var{protocol} should be one of the protocols listed in
2868 @file{/etc/protocols}.  The typical protocol names are @samp{tcp} for
2869 byte stream connections and @samp{udp} for unreliable datagrams.
2870
2871 The @var{wait} field should be either @samp{wait} or @samp{nowait}.
2872 Use @samp{wait} if @var{style} is a connectionless style and the
2873 server, once started, handles multiple requests as they come in.
2874 Use @samp{nowait} if @code{inetd} should start a new process for each message
2875 or request that comes in.  If @var{style} uses connections, then
2876 @var{wait} @strong{must} be @samp{nowait}.
2877
2878 @var{user} is the user name that the server should run as.  @code{inetd} runs
2879 as root, so it can set the user ID of its children arbitrarily.  It's
2880 best to avoid using @samp{root} for @var{user} if you can; but some
2881 servers, such as Telnet and FTP, read a username and password
2882 themselves.  These servers need to be root initially so they can log
2883 in as commanded by the data coming over the network.
2884
2885 @var{program} together with @var{arguments} specifies the command to
2886 run to start the server.  @var{program} should be an absolute file
2887 name specifying the executable file to run.  @var{arguments} consists
2888 of any number of whitespace-separated words, which become the
2889 command-line arguments of @var{program}.  The first word in
2890 @var{arguments} is argument zero, which should by convention be the
2891 program name itself (sans directories).
2892
2893 If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the
2894 file and obey its new contents by sending the @code{inetd} process the
2895 @code{SIGHUP} signal.  You'll have to use @code{ps} to determine the
2896 process ID of the @code{inetd} process as it is not fixed.
2897
2898 @c !!! could document /etc/inetd.sec
2899
2900 @node Socket Options
2901 @section Socket Options
2902 @cindex socket options
2903
2904 This section describes how to read or set various options that modify
2905 the behavior of sockets and their underlying communications protocols.
2906
2907 @cindex level, for socket options
2908 @cindex socket option level
2909 When you are manipulating a socket option, you must specify which
2910 @dfn{level} the option pertains to.  This describes whether the option
2911 applies to the socket interface, or to a lower-level communications
2912 protocol interface.
2913
2914 @menu
2915 * Socket Option Functions::     The basic functions for setting and getting
2916                                  socket options.
2917 * Socket-Level Options::        Details of the options at the socket level.
2918 @end menu
2919
2920 @node Socket Option Functions
2921 @subsection Socket Option Functions
2922
2923 @pindex sys/socket.h
2924 Here are the functions for examining and modifying socket options.
2925 They are declared in @file{sys/socket.h}.
2926
2927 @comment sys/socket.h
2928 @comment BSD
2929 @deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr})
2930 The @code{getsockopt} function gets information about the value of
2931 option @var{optname} at level @var{level} for socket @var{socket}.
2932
2933 The option value is stored in a buffer that @var{optval} points to.
2934 Before the call, you should supply in @code{*@var{optlen-ptr}} the
2935 size of this buffer; on return, it contains the number of bytes of
2936 information actually stored in the buffer.
2937
2938 Most options interpret the @var{optval} buffer as a single @code{int}
2939 value.
2940
2941 The actual return value of @code{getsockopt} is @code{0} on success
2942 and @code{-1} on failure.  The following @code{errno} error conditions
2943 are defined:
2944
2945 @table @code
2946 @item EBADF
2947 The @var{socket} argument is not a valid file descriptor.
2948
2949 @item ENOTSOCK
2950 The descriptor @var{socket} is not a socket.
2951
2952 @item ENOPROTOOPT
2953 The @var{optname} doesn't make sense for the given @var{level}.
2954 @end table
2955 @end deftypefun
2956
2957 @comment sys/socket.h
2958 @comment BSD
2959 @deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, const void *@var{optval}, socklen_t @var{optlen})
2960 This function is used to set the socket option @var{optname} at level
2961 @var{level} for socket @var{socket}.  The value of the option is passed
2962 in the buffer @var{optval} of size @var{optlen}.
2963
2964 @c Argh. -zw
2965 @iftex
2966 @hfuzz 6pt
2967 The return value and error codes for @code{setsockopt} are the same as
2968 for @code{getsockopt}.
2969 @end iftex
2970 @ifinfo
2971 The return value and error codes for @code{setsockopt} are the same as
2972 for @code{getsockopt}.
2973 @end ifinfo
2974
2975 @end deftypefun
2976
2977 @node Socket-Level Options
2978 @subsection Socket-Level Options
2979
2980 @comment sys/socket.h
2981 @comment BSD
2982 @deftypevr Constant int SOL_SOCKET
2983 Use this constant as the @var{level} argument to @code{getsockopt} or
2984 @code{setsockopt} to manipulate the socket-level options described in
2985 this section.
2986 @end deftypevr
2987
2988 @pindex sys/socket.h
2989 @noindent
2990 Here is a table of socket-level option names; all are defined in the
2991 header file @file{sys/socket.h}.
2992
2993 @table @code
2994 @comment sys/socket.h
2995 @comment BSD
2996 @item SO_DEBUG
2997 @c Extra blank line here makes the table look better.
2998
2999 This option toggles recording of debugging information in the underlying
3000 protocol modules.  The value has type @code{int}; a nonzero value means
3001 ``yes''.
3002 @c !!! should say how this is used
3003 @c OK, anyone who knows, please explain.
3004
3005 @comment sys/socket.h
3006 @comment BSD
3007 @item SO_REUSEADDR
3008 This option controls whether @code{bind} (@pxref{Setting Address})
3009 should permit reuse of local addresses for this socket.  If you enable
3010 this option, you can actually have two sockets with the same Internet
3011 port number; but the system won't allow you to use the two
3012 identically-named sockets in a way that would confuse the Internet.  The
3013 reason for this option is that some higher-level Internet protocols,
3014 including FTP, require you to keep reusing the same port number.
3015
3016 The value has type @code{int}; a nonzero value means ``yes''.
3017
3018 @comment sys/socket.h
3019 @comment BSD
3020 @item SO_KEEPALIVE
3021 This option controls whether the underlying protocol should
3022 periodically transmit messages on a connected socket.  If the peer
3023 fails to respond to these messages, the connection is considered
3024 broken.  The value has type @code{int}; a nonzero value means
3025 ``yes''.
3026
3027 @comment sys/socket.h
3028 @comment BSD
3029 @item SO_DONTROUTE
3030 This option controls whether outgoing messages bypass the normal
3031 message routing facilities.  If set, messages are sent directly to the
3032 network interface instead.  The value has type @code{int}; a nonzero
3033 value means ``yes''.
3034
3035 @comment sys/socket.h
3036 @comment BSD
3037 @item SO_LINGER
3038 This option specifies what should happen when the socket of a type
3039 that promises reliable delivery still has untransmitted messages when
3040 it is closed; see @ref{Closing a Socket}.  The value has type
3041 @code{struct linger}.
3042
3043 @comment sys/socket.h
3044 @comment BSD
3045 @deftp {Data Type} {struct linger}
3046 This structure type has the following members:
3047
3048 @table @code
3049 @item int l_onoff
3050 This field is interpreted as a boolean.  If nonzero, @code{close}
3051 blocks until the data are transmitted or the timeout period has expired.
3052
3053 @item int l_linger
3054 This specifies the timeout period, in seconds.
3055 @end table
3056 @end deftp
3057
3058 @comment sys/socket.h
3059 @comment BSD
3060 @item SO_BROADCAST
3061 This option controls whether datagrams may be broadcast from the socket.
3062 The value has type @code{int}; a nonzero value means ``yes''.
3063
3064 @comment sys/socket.h
3065 @comment BSD
3066 @item SO_OOBINLINE
3067 If this option is set, out-of-band data received on the socket is
3068 placed in the normal input queue.  This permits it to be read using
3069 @code{read} or @code{recv} without specifying the @code{MSG_OOB}
3070 flag.  @xref{Out-of-Band Data}.  The value has type @code{int}; a
3071 nonzero value means ``yes''.
3072
3073 @comment sys/socket.h
3074 @comment BSD
3075 @item SO_SNDBUF
3076 This option gets or sets the size of the output buffer.  The value is a
3077 @code{size_t}, which is the size in bytes.
3078
3079 @comment sys/socket.h
3080 @comment BSD
3081 @item SO_RCVBUF
3082 This option gets or sets the size of the input buffer.  The value is a
3083 @code{size_t}, which is the size in bytes.
3084
3085 @comment sys/socket.h
3086 @comment GNU
3087 @item SO_STYLE
3088 @comment sys/socket.h
3089 @comment BSD
3090 @itemx SO_TYPE
3091 This option can be used with @code{getsockopt} only.  It is used to
3092 get the socket's communication style.  @code{SO_TYPE} is the
3093 historical name, and @code{SO_STYLE} is the preferred name in GNU.
3094 The value has type @code{int} and its value designates a communication
3095 style; see @ref{Communication Styles}.
3096
3097 @comment sys/socket.h
3098 @comment BSD
3099 @item SO_ERROR
3100 @c Extra blank line here makes the table look better.
3101
3102 This option can be used with @code{getsockopt} only.  It is used to reset
3103 the error status of the socket.  The value is an @code{int}, which represents
3104 the previous error status.
3105 @c !!! what is "socket error status"?  this is never defined.
3106 @end table
3107
3108 @node Networks Database
3109 @section Networks Database
3110 @cindex networks database
3111 @cindex converting network number to network name
3112 @cindex converting network name to network number
3113
3114 @pindex /etc/networks
3115 @pindex netdb.h
3116 Many systems come with a database that records a list of networks known
3117 to the system developer.  This is usually kept either in the file
3118 @file{/etc/networks} or in an equivalent from a name server.  This data
3119 base is useful for routing programs such as @code{route}, but it is not
3120 useful for programs that simply communicate over the network.  We
3121 provide functions to access this database, which are declared in
3122 @file{netdb.h}.
3123
3124 @comment netdb.h
3125 @comment BSD
3126 @deftp {Data Type} {struct netent}
3127 This data type is used to represent information about entries in the
3128 networks database.  It has the following members:
3129
3130 @table @code
3131 @item char *n_name
3132 This is the ``official'' name of the network.
3133
3134 @item char **n_aliases
3135 These are alternative names for the network, represented as a vector
3136 of strings.  A null pointer terminates the array.
3137
3138 @item int n_addrtype
3139 This is the type of the network number; this is always equal to
3140 @code{AF_INET} for Internet networks.
3141
3142 @item unsigned long int n_net
3143 This is the network number.  Network numbers are returned in host
3144 byte order; see @ref{Byte Order}.
3145 @end table
3146 @end deftp
3147
3148 Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search
3149 the networks database for information about a specific network.  The
3150 information is returned in a statically-allocated structure; you must
3151 copy the information if you need to save it.
3152
3153 @comment netdb.h
3154 @comment BSD
3155 @deftypefun {struct netent *} getnetbyname (const char *@var{name})
3156 The @code{getnetbyname} function returns information about the network
3157 named @var{name}.  It returns a null pointer if there is no such
3158 network.
3159 @end deftypefun
3160
3161 @comment netdb.h
3162 @comment BSD
3163 @deftypefun {struct netent *} getnetbyaddr (uint32_t @var{net}, int @var{type})
3164 The @code{getnetbyaddr} function returns information about the network
3165 of type @var{type} with number @var{net}.  You should specify a value of
3166 @code{AF_INET} for the @var{type} argument for Internet networks.
3167
3168 @code{getnetbyaddr} returns a null pointer if there is no such
3169 network.
3170 @end deftypefun
3171
3172 You can also scan the networks database using @code{setnetent},
3173 @code{getnetent} and @code{endnetent}.  Be careful when using these
3174 functions because they are not reentrant.
3175
3176 @comment netdb.h
3177 @comment BSD
3178 @deftypefun void setnetent (int @var{stayopen})
3179 This function opens and rewinds the networks database.
3180
3181 If the @var{stayopen} argument is nonzero, this sets a flag so that
3182 subsequent calls to @code{getnetbyname} or @code{getnetbyaddr} will
3183 not close the database (as they usually would).  This makes for more
3184 efficiency if you call those functions several times, by avoiding
3185 reopening the database for each call.
3186 @end deftypefun
3187
3188 @comment netdb.h
3189 @comment BSD
3190 @deftypefun {struct netent *} getnetent (void)
3191 This function returns the next entry in the networks database.  It
3192 returns a null pointer if there are no more entries.
3193 @end deftypefun
3194
3195 @comment netdb.h
3196 @comment BSD
3197 @deftypefun void endnetent (void)
3198 This function closes the networks database.
3199 @end deftypefun