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