Put a @table around @include summary.out.
[kopensolaris-gnu/glibc.git] / manual / socket.texi
1 @node Sockets
2 @chapter Sockets
3
4 @cindex socket
5 @cindex interprocess communication, with sockets
6 A @dfn{socket} is a generalized interprocess communication channel.
7 Like a pipe, a socket is represented as a file descriptor.  But, unlike
8 pipes, sockets support communication between unrelated processes, and
9 even between processes running on different machines that communicate
10 over a network.
11
12 This chapter describes the GNU facilities for interprocess
13 communication.  First, we look at the functions for creating and
14 initializing sockets, and then we consider the details of how to establish
15 communications in the two most important domains --- the local domain
16 and the Internet domain.  Finally, actual operations on sockets
17 are described.
18
19 @menu
20 * Socket Creation and Naming::          Functions for creating and
21                                          initializing sockets.
22 * Domains and Protocols::               How to specify the communications
23                                          protocol for a socket.
24 * The Local Domain::                    Details about the local (Unix) domain.
25 * The Internet Domain::                 Details about the Internet domain.
26 * Types of Sockets::                    Different socket types have different
27                                          semantics for data transmission.
28 * Byte Stream Socket Operations::       Operations on sockets with connection
29                                          state.
30 * Datagram Socket Operations::          Operations on datagram sockets.
31 * Socket Options::                      Miscellaneous low-level socket options.
32 @end menu
33
34
35 @node Socket Creation and Naming
36 @section Socket Creation and Naming
37
38 This section presents the basic functions for creating and initializing
39 sockets.  These functions are fairly general, and the exact details
40 of how you call them depend on the particular communications protocol
41 you want to use.  Once the basic functions have been covered, we will
42 come back to consider these details later in the chapter.
43
44 When you create a socket, you must specify its type and the
45 communications domain and protocol you want it to use.
46
47 @cindex socket type
48 @cindex type, of a socket
49 The @dfn{socket type} defines the semantics of the communication.
50 Some socket types provide reliable, sequential byte stream communications
51 in much the same way as a pipe, while others permit messages to be
52 lost or arrive out of sequence.  Socket types are discussed in more
53 detail in @ref{Types of Sockets}.
54
55 @cindex socket domain
56 @cindex domain, for socket
57 @cindex protocol family, for socket
58 @cindex socket protocol family
59 @cindex protocol, for socket
60 @cindex socket protocol
61 The socket @dfn{domain} or @dfn{protocol family} is the low-level
62 mechanism used for communications.  For example, there is a protocol
63 family for communication between processes on the same machine, and
64 another protocol family for communication over the Internet.  Each
65 domain supports one or more specific @dfn{protocols} for communication.
66 @xref{Domains and Protocols}, for more information about this.
67
68 @cindex peer socket
69 @cindex server socket
70 @cindex client socket
71 A socket is only one end of a communications path.  Before you can
72 transfer any data through the socket, you must specify another socket to
73 be at the other end of the communications path; this is called its
74 @dfn{peer}.  A socket that accepts connections in this way is called a
75 @dfn{server}, while the socket that initiates the connection is called
76 a @dfn{client}.
77
78 @menu
79 * Creating a Socket::                   How to open a socket.
80 * Closing a Socket::                    How to close a socket.
81 * Socket Naming::                       You must associate a name with a socket
82                                          before it can receive data.
83 * Socket Pairs::                        These are created like pipes.
84 @end menu
85
86 @node Creating a Socket
87 @subsection Creating a Socket
88 @cindex creating a socket
89 @cindex socket, creating
90 @cindex opening a socket
91
92 The primitive for creating a socket is the @code{socket} function,
93 declared in @file{sys/socket.h}.
94 @pindex sys/socket.h
95
96 @comment sys/socket.h
97 @comment BSD
98 @deftypefun int socket (int @var{domain}, int @var{type}, int @var{protocol})
99 This function creates a socket of type @var{type}, which should be one
100 of the socket types listed in @ref{Types of Sockets}.  The @var{domain}
101 argument specifies the protocol family and the @var{protocol} the
102 specific communications protocol within that family; see @ref{Domains and
103 Protocols}.
104
105 The return value from @code{socket} is the file descriptor for the new
106 socket, or @code{-1} in case of error.  The following @code{errno} error
107 conditions are defined for this function:
108
109 @table @code
110 @item EPROTONOSUPPORT
111 The @var{protocol} or @var{type} is not supported by the communications
112 protocol family @var{domain}.
113
114 @item EMFILE
115 The process already has too many file descriptors open.
116
117 @item ENFILE
118 The system already has too many file descriptors open.
119
120 @item EACCESS
121 The process does not have privilege to create a socket of the specified
122 @var{type} or @var{protocol}.
123
124 @item ENOBUFS
125 The system ran out of internal buffer space.
126 @end table
127 @end deftypefun
128
129 Sockets are two-way communications channels.  That is, you can read or
130 write at either end of the connection.  Like pipes, sockets do not
131 support file positioning operations.
132
133
134 @node Closing a Socket
135 @subsection Closing a Socket
136 @cindex socket, closing
137 @cindex closing a socket
138 @cindex shutting down a socket
139
140 When you are finished using a socket, you can simply close its
141 file descriptor with @code{close}; see @ref{Opening and Closing Files}.
142 If there is still data waiting to be transmitted over the connection,
143 normally @code{close} tries to complete this transmission.  You
144 can control this behavior using the @code{SO_LINGER} socket option;
145 see @ref{Socket Options}.
146
147 To shut down a socket more cleanly, call @code{shutdown} before calling
148 @code{close}.  This function is declared in @file{sys/socket.h}.
149 @pindex sys/socket.h
150
151 @comment sys/socket.h
152 @comment BSD
153 @deftypefun int shutdown (int @var{filedes}, int @var{how})
154 The @code{shutdown} function shuts down the socket @var{filedes}.  The
155 @var{how} argument specifies what action to perform:
156
157 @table @code
158 @item 0
159 Disable further receive operations on this socket.
160
161 @item 1
162 Disable further send operations on this socket.
163
164 @item 2
165 Disable both receive and send operations.
166 @end table
167
168 The return value is @code{0} on success and @code{-1} on failure.  The
169 following @code{errno} error conditions are defined for this function:
170
171 @table @code
172 @item EBADF
173 The @var{filedes} is not a valid file descriptor.
174
175 @item ENOTSOCK
176 The @var{filedes} is not a socket.
177
178 @item ENOTCONN
179 The @var{filedes} is not connected.
180 @end table
181 @end deftypefun
182
183
184 @node Socket Naming
185 @subsection Socket Naming
186
187 @cindex binding a name to a socket
188 @cindex socket name binding
189 When a socket is created with the @code{socket} function, it initially
190 has no name assigned to it.  Before other processes can send data
191 to this socket, you must assign it a name.  This process is called
192 @dfn{binding} the name to the socket, and is performed with the @code{bind}
193 function.
194
195 Only sockets belonging to server processes need to be named.  You can
196 also call @code{bind} to establish the name of the socket on the client
197 side, but this is optional; a name is assigned automatically if you
198 don't.
199
200 The details of how sockets are named vary depending on the particular
201 domain of the socket.  @xref{The Local Domain}, or @ref{The Internet
202 Domain}, for specific information.
203
204 Here are descriptions of the functions for setting or inquiring about
205 the name of a socket.  The prototypes for these functions are in the
206 header file @file{sys/socket.h}
207 @pindex sys/socket.h
208
209 @comment sys/socket.h
210 @comment BSD
211 @deftypefun int bind (int @var{filedes}, struct sockaddr *@var{addr}, size_t @var{length})
212 The @code{bind} function assigns a name to the socket @var{filedes}.  The
213 @var{addr} and @var{length} arguments specify the name; the format of this
214 information depends on the socket domain.
215
216 The return value is @code{0} on success and @code{-1} on failure.  The
217 following @code{errno} error conditions are defined for this function:
218
219 @table @code
220 @item EBADF
221 The @var{filedes} argument is not a valid file descriptor.
222
223 @item ENOTSOCK
224 The @var{filedes} argument is not a socket.
225
226 @item EADDRNOTAVAIL
227 The specified address is not available on this machine.
228
229 @item EADDRINUSE
230 Some other socket is already using the specified address.
231
232 @item EINVAL
233 The @var{filedes} has already been bound to a name.
234
235 @item EACCESS
236 You do not have permission to access the requested address.
237 @end table
238
239 Additional errors may be detected depending on the particular domain
240 of the socket.
241 @end deftypefun
242
243 @comment sys/socket.h
244 @comment BSD
245 @deftypefun int getsockname (int @var{filedes}, struct sockaddr *@var{addr}, size_t *@var{length_ptr})
246 The @code{getsockname} information returns information about the name
247 of the socket @var{filedes} in the locations specified by the @var{addr} 
248 and @var{length_ptr} arguments.  Note that the @var{length_ptr} is a pointer;
249 you should initialize it to be the allocation size of @var{addr}, and on
250 return it contains the actual size of the name.  Again, the format of the
251 information depends on the socket domain.
252
253 The return value is @code{0} on success and @code{-1} on error.  The
254 following @code{errno} error conditions are defined for this function:
255
256 @table @code
257 @item EBADF
258 The @var{filedes} argument is not a valid file descriptor.
259
260 @item ENOTSOCK
261 The @var{filedes} argument is not a socket.
262
263 @item ENOBUFS
264 There are not enough internal buffers available for the operation.
265 @end table
266 @end deftypefun
267
268 @comment sys/socket.h
269 @comment BSD
270 @deftp {struct Type} sockaddr
271 Since the format of socket addresses varies depending on the domain of
272 the socket, the functions that deal with socket names treat them as a
273 byte vector prefixed with a code that identifies the format of the data
274 which follows.  In the function prototypes, this is declared as a
275 @code{struct sockaddr *}, but in actual practice there is a separate
276 @code{struct} type for each address family.  You just cast the pointer
277 as necessary.
278
279 The basic @code{struct sockaddr} type has the following members:
280
281 @table @code
282 @item unsigned short int sa_family
283 This is the socket address family, and identifies the format of the
284 data which follows.
285
286 @item char sa_data[14]
287 This is the actual socket address data.  
288 @end table
289 @end deftp
290
291 You can use these symbolic constants to identify the address family:
292
293 @comment sys/socket.h
294 @comment BSD
295 @deftypevr Macro int AF_UNSPEC
296 This is the unspecified address family.
297 @end deftypevr
298
299 @comment sys/socket.h
300 @comment GNU
301 @deftypevr Macro int AF_LOCAL
302 This is the address family for sockets in the local domain.  @xref{The
303 Local Domain}.
304
305 @strong{Incomplete:}  This isn't actually in the header file yet!!!
306 @end deftypevr
307
308 @comment sys/socket.h
309 @comment BSD
310 @deftypevr Macro int AF_UNIX
311 This is a synonym for @code{AF_LOCAL}.
312 @end deftypevr
313
314 @comment sys/socket.h
315 @comment BSD
316 @deftypevr Macro int AF_INET
317 This is the address family for sockets in the Internet domain.
318 @xref{The Internet Domain}.
319 @end deftypevr
320
321 @strong{Incomplete:}  There are a bunch more of these.
322
323
324 @node Socket Pairs
325 @subsection Socket Pairs
326 @cindex creating a socket pair
327 @cindex socket pair
328 @cindex opening a socket pair
329
330 A @dfn{socket pair} consists of a pair of connected (but unnamed)
331 sockets.  It is very similar to a pipe and is used in much the same way.
332 Socket pairs are created with the @code{socketpair} function, declared
333 in @file{sys/socket.h}.  (Compare this function with the @code{pipe}
334 function; see @ref{Creating a Pipe}.)
335 @pindex sys/socket.h
336
337 @comment sys/socket.h
338 @comment BSD
339 @deftypefun int socketpair (int @var{domain}, int @var{type}, int @var{protocol}, int @var{filedes}[2])
340 This function creates a socket pair, returning the file descriptors in
341 @code{@var{filedes}[0]} and @code{@var{filedes}[1]}.  The socket pair
342 is a full-duplex communications channel, so that both reading and writing
343 may be performed at either end.
344
345 The @var{domain}, @var{type}, and @var{protocol} are interpreted as for
346 the @code{socket} function; see @ref{Creating a Socket}.
347
348 The @code{socketpair} function returns @code{0} on success and @code{-1}
349 on failure.  The following @code{errno} error conditions are defined
350 for this function:
351
352 @table @code
353 @item EMFILE
354 The process has too many file descriptors open.
355
356 @item EAFNOSUPPORT
357 The specified address family is not supported.
358
359 @item EPROTONOSUPPORT
360 The specified protocol is not supported.
361
362 @item EOPNOTSUPP
363 The specified protocol does not support the creation of socket pairs.
364 @end table
365
366 @strong{Incomplete:}  The BSD manual says socket pairs are only supported
367 in the local domain.  Is this true of the GNU system also?
368 @end deftypefun
369
370
371
372 @node Domains and Protocols
373 @section Domains and Protocols
374
375 The header file @file{sys/socket.h} defines these symbolic constants
376 that name various domains (or protocol families).  You can use these
377 macros as values for the @var{domain} argument to the @code{socket} or
378 @code{socketpair} functions.
379 @pindex sys/socket.h
380
381 @comment sys/socket.h
382 @comment GNU
383 @deftypevr Macro int PF_LOCAL
384 This is the domain local to the host machine.  The local domain is
385 discussed in more detail in @ref{The Local Domain}.
386
387 @strong{Incomplete:}  This isn't actually in the header file yet!!!
388 @end deftypevr
389
390 @comment sys/socket.h
391 @comment BSD
392 @deftypevr Macro int PF_UNIX
393 This is a synonym for @code{PF_LOCAL}.
394 @end deftypevr
395
396 @comment sys/socket.h
397 @comment BSD
398 @deftypevr Macro int PF_INET
399 This is the Internet protocol (IP) family.  @xref{The Internet Domain},
400 for more information.
401 @end deftypevr
402
403 @strong{Incomplete:} These are only the most important protocol
404 families.  This chapter includes detailed information about socket
405 naming conventions and specific protocols for these domains.  There
406 are several other domains defined in @file{sys/socket.h}, but who
407 knows about the details of using them?
408
409 Each domain can support multiple protocols.  Normally, though, you can
410 just use the default protocol for the domain.  You do this by providing
411 a value of @code{0} as the @var{protocol} argument when creating a
412 socket with @code{socket} or @code{socketpair}.
413
414
415 @node The Local Domain
416 @section The Local Domain
417 @cindex local domain, for sockets
418
419 This section describes the details of the local domain, @code{PF_LOCAL}.
420 This is also known as the Unix domain, @code{PF_UNIX}.
421
422 In the local domain, socket names are file names.  This effectively
423 allows processes on hosts that share a common file system to
424 communicate.
425
426 You can specify any file name you want as the name of the socket.
427 However, you must have write permission on the directory containing the
428 file.  It's typical to put these files in the @file{/tmp} directory.
429
430 @strong{Incomplete:}  Can you fiddle with file protections to restrict
431 access to the socket?
432
433 The structure for specifying socket names in the local domain is
434 defined in the header file @file{sys/un.h}:
435 @pindex sys/un.h
436
437 @comment sys/un.h
438 @comment BSD
439 @deftp {struct Type} sockaddr_un
440 This structure is used to specify local domain socket addresses.  It has
441 the following members:
442
443 @table @code
444 @item short int sun_family
445 This identifies the address family or format of the socket address.  You
446 should assign a value of @code{AF_LOCAL} (or @code{AF_UNIX}) to this
447 member.  @xref{Socket Naming}.
448
449 @item char sun_path[108]
450 This is the file name to use.
451 @end table
452 @end deftp
453
454 The @var{length} parameter associated with socket names in the local
455 domain is computed as the sum of the size of the address family
456 component of the address structure, and the string length (@emph{not}
457 the allocation size!) of the file name string.
458
459 After you close a socket in the local domain, you should delete the file.
460 Use @code{unlink} or @code{remove} to do this; see @ref{Deleting Files}.
461
462 The default communications protocol (protocol number @code{0}) is the
463 only one supported by the local domain.
464
465 @strong{Incomplete:}  Is this correct?  I couldn't find any mention
466 of other protocols.
467
468 Here is an example showing how to create and name a socket in the local
469 domain.
470
471 @comment This example is from lsockserver.c.
472 @example
473 #include <sys/socket.h>
474 #include <stdio.h>
475 #include <sys/un.h>
476 #include <errno.h>
477 #include <stdlib.h>
478
479 int make_named_socket (const char *filename)
480 @{
481   struct sockaddr_un name;
482   int sock, status;
483   size_t size;
484
485   /* @r{Create the socket.} */
486   
487   sock = socket (PF_UNIX, SOCK_DGRAM, 0);
488   if (sock < 0) @{
489     perror ("socket");
490     exit (EXIT_FAILURE);
491   @}
492
493   /* @r{Bind a name to the socket.} */
494
495   name.sun_family = AF_UNIX;
496   strcpy (name.sun_path, filename);
497   size = strlen (name.sun_path) + sizeof (name.sun_family);
498   status = bind (sock, (struct sockaddr *)&name, size);
499   if (size < 0) @{
500     perror ("bind");
501     exit (EXIT_FAILURE);
502   @}
503
504   return sock;
505 @}
506 @end example
507
508 @node The Internet Domain
509 @section The Internet Domain
510 @cindex Internet domain, for sockets
511
512 This section describes the details the protocols and socket naming
513 conventions used in the Internet domain, @code{PF_INET}.
514
515 @menu
516 * Protocols Database::          Selecting a communications protocol.
517 * Internet Socket Naming::      How socket names are specified in the Internet
518                                  domain.
519 * Internet Host Addresses::     Hosts are assigned addresses that are numbers.
520 * Hosts Database::              A host may also have a symbolic host name.
521 * Services Database::           Ports may also have symbolic names.
522 * Networks Database::           There is also a database for network names.
523 * Byte Order Conversion::       Different hosts may use different byte
524                                  ordering conventions; you need to canonicalize
525                                  host address and port numbers.
526 * Internet Socket Example::     Putting it all together.
527 @end menu
528
529 @node Protocols Database
530 @subsection Protocols Database
531 @cindex protocols database
532
533 @cindex TCP (Internet protocol)
534 The default communications protocol for the Internet domain is TCP
535 (``transmission control protocol'').  This is adequate for just about
536 all normal purposes.  Unless you are trying to do something really
537 wizardly, just specify the default protocol @code{0} when you create the
538 socket, and don't bother with the rest of this section.
539
540 @pindex /etc/protocols
541 Internet protocols are generally specified by a name instead of a
542 number.  The network protocols that a host knows about are stored in a
543 database.  This is usually either derived from the file
544 @file{/etc/protocols}, or it may be an equivalent provided by a name
545 server.  You look up the protocol number associated with a named
546 protocol in the database using the @code{getprotobyname} function.
547
548 Here are detailed descriptions of the utilities for accessing the
549 protocols database.  These are declared in @file{netdb.h}.
550 @pindex netdb.h
551
552 @comment netdb.h
553 @comment BSD
554 @deftp {struct Type} protoent
555 This data type is used to represent entries in the network protocols
556 database.  It has the following members:
557
558 @table @code
559 @item char *p_name
560 This is the official name of the protocol.
561
562 @item char **p_aliases
563 These are alternate names for the protocol, specified as an array of
564 strings.  The last element of the array is a null pointer.
565
566 @item int p_proto
567 This is the protocol number; use this member as the @var{protocol}
568 argument to @code{socket}.
569 @end table
570 @end deftp
571
572 You can use @code{getprotobyname} and @code{getprotobynumber} to search
573 the protocols database for a specific protocol.  The information is
574 returned in a statically-allocated structure; you must copy the
575 information if you need to save it across calls.
576
577 @comment netdb.h
578 @comment BSD
579 @deftypefun {struct protoent *} getprotobyname (const char *@var{name})
580 The @code{getprotobyname} function returns information about the network
581 protocol named @var{name}.  If the lookup fails, a null pointer is
582 returned.
583 @end deftypefun
584
585 @comment netdb.h
586 @comment BSD
587 @deftypefun {struct protoent *} getprotobynumber (int @var{protocol})
588 The @code{getprotobynumber} function returns information about the
589 network protocol with number @var{protocol}.  If the lookup fails, a
590 null pointer is returned.
591 @end deftypefun
592
593 You can also scan the protocols database by using @code{setprotoent},
594 @code{getprotoent}, and @code{endprotoent}.
595
596 @comment netdb.h
597 @comment BSD
598 @deftypefun void setprotoent (int @var{stayopen})
599 This function opens and rewinds the protocols database.  If the
600 @var{stayopen} argument is true, the database stays open after calls to
601 @code{getprotobyname} or @code{getprotobynumber}.
602 @end deftypefun
603
604 @comment netdb.h
605 @comment BSD
606 @deftypefun {struct protoent *} getprotoent (void)
607 This function returns the next entry in the protocols database.  A null
608 pointer is returned if there are no more entries.
609 @end deftypefun
610
611 @comment netdb.h
612 @comment BSD
613 @deftypefun void endprotoent (void)
614 This function closes the protocols database.
615 @end deftypefun
616
617
618 @node Internet Socket Naming
619 @subsection Internet Socket Naming
620
621 In the Internet domain, socket names are a triple consisting of a
622 protocol, a host address, and a port on that host.  The protocol is
623 implicit, however; all this really means is that different protocols can
624 use the same port numbers without colliding, and you have to be careful
625 to use the right protocol that the server is expecting.
626
627 The data type for representing socket addresses in the Internet domain
628 is defined in the header file @file{netinet/in.h}.
629 @pindex netinet/in.h
630
631 @comment netinet/in.h
632 @comment BSD
633 @deftp {struct Type} sockaddr_in
634 This is the data type used to represent socket addresses in the
635 Internet domain.  It has the following members:
636
637 @table @code
638 @item short int sin_family
639 This identifies the address family or format of the socket address.  You
640 should assign a value of @code{AF_INET} to this member.  @xref{Socket Naming}.
641
642 @item unsigned short int sin_port
643 This is the port number.  @xref{Services Database}, for information about
644 what to put in this member.
645
646 @item struct in_addr sin_addr
647 This is the Internet address of the host machine.  @xref{Internet Host
648 Addresses}, and @ref{Hosts Database}, for information about how to
649 get a value to store here.
650 @end table
651 @end deftp
652
653 The @var{length} parameter associated with socket names in the Internet
654 domain is computed as @code{sizeof (struct sockaddr_in)}.
655
656
657 @node Internet Host Addresses
658 @subsection Internet Host Addresses
659
660 @cindex host address, Internet
661 @cindex Internet host address
662 The first step in building a socket name in the Internet domain is
663 determining the @dfn{host address}.  This is an identifier that
664 uniquely identifies a particular machine on the Internet.
665
666 Host addresses are represented internally as @code{struct in_addr}
667 objects, although in some situations you need to cast this to a
668 @code{unsigned long int} or just treat it as a block of memory; unfortunately,
669 the interfaces to the various functions for manipulating addresses are
670 not at all consistent about this.
671
672 Externally, host addresses are specified as strings like
673 @samp{128.52.46.32}.  A machine may also have a @dfn{host name} that is
674 a string; for example, @samp{churchy.gnu.ai.mit.edu}.  This section
675 discusses the numeric form of host addresses only.  To map a host name
676 onto an address, you need to call @code{gethostbyname}; this function is
677 discussed in @ref{Hosts Database}.
678
679 @cindex network number
680 @cindex local network address number
681 An Internet host address is a number containing of four bytes of data,
682 and consists of a @dfn{network number} and a @dfn{local network address
683 number} within that network.  Network numbers are registered with the
684 Network Information Center (NIC), and are divided into three classes ---
685 A, B, and C.  The local network address numbers of individual machines
686 are registered with the administrator of the particular network.
687
688 Class A networks have single-byte addresses in the range 0 to 127.
689 There are only a small number of Class A networks, but they can each
690 support a very large number of hosts.  Medium-sized Class B networks
691 have two-byte addresses, with the first byte in the range 128 to 191.
692 Class C networks are the smallest; they have three-byte addresses, with
693 the first byte in the range 192-255.  The remaining bytes of the
694 Internet address specify the local network address number.
695
696 The Class A network 0 is reserved for broadcast to all networks.  In
697 addition, the host number 0 within each network is reserved for broadcast 
698 to all hosts in that network.
699
700 The Class A network 127 is reserved for loopback; you can always use
701 the Internet address @samp{127.0.0.1} to refer to the host machine.
702
703 Since a single machine can be a member of multiple networks, it can have
704 multiple Internet host addresses.  However, there is never more than one
705 machine with the same host address.
706
707 @cindex standard dot notation, for Internet addresses
708 @cindex dot notation, for Internet addresses
709 There are four forms of the @dfn{standard dot notation} for Internet
710 addresses:
711
712 @table @code
713 @item @var{a}.@var{b}.@var{c}.@var{d}
714 This specifies all four bytes of the address individually.
715
716 @item @var{a}.@var{b}.@var{c}
717 The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
718 This is useful for specifying host addresses in a Class B network with
719 network address number @code{@var{a}.@var{b}}.
720
721 @item @var{a}.@var{b}
722 The last part of the address, @var{c}, is interpreted as a 3-byte quantity.
723 This is useful for specifying host addresses in a Class A network with
724 network address number @var{a}.
725
726 @item @var{a}
727 If only one part is given, this corresponds directly to the host address
728 number.
729 @end table
730
731 Within each part of the address, the usual C conventions for specifying
732 the radix apply.  In other words, a leading @samp{0x} or @samp{0X} implies
733 hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
734 radix is assumed.
735
736 The following basic definitions for Internet addresses appear in the
737 header file @file{netinet/in.h}:
738 @pindex netinet/in.h
739
740 @comment netinet/in.h
741 @comment BSD
742 @deftp {struct Type} in_addr
743 This is the data type representing an Internet host address.  You can
744 cast this structure type to a @code{unsigned long int} to get the host address
745 number.
746 @end deftp
747
748 @comment netinet/in.h
749 @comment BSD
750 @deftypevr Macro {unsigned long int} INADDR_ANY
751 This constant can be used to specify the address of the host computer;
752 it is essentially equivalent to saying that any of the host addresses of
753 the machine the program is running on may be used by connection
754 requests.
755 @end deftypevr
756
757 These additional functions for manipulating Internet addresses are
758 declared in @file{arpa/inet.h}:
759 @pindex arpa/inet.h
760
761 @comment arpa/inet.h
762 @comment BSD
763 @deftypefun {unsigned long int} inet_addr (const char *@var{name})
764 This function converts the address @var{name} from the standard dot
765 notation into a host address number.
766 @end deftypefun
767
768 @comment arpa/inet.h
769 @comment BSD
770 @deftypefun {unsigned long int} inet_network (const char *@var{name})
771 This function extracts the network address number from the address 
772 @var{name}, which is given in the standard dot notation.
773 @end deftypefun
774
775 @comment arpa/inet.h
776 @comment BSD
777 @deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
778 This function converts the Internet address @var{addr} to a string in
779 the standard dot notation.  The return value is a pointer into a
780 statically-allocated buffer; this can be overwritten on subsequent calls,
781 so you should copy the data if you need to save it.
782 @end deftypefun
783
784 @comment arpa/inet.h
785 @comment BSD
786 @deftypefun {struct in_addr} inet_makeaddr (int @var{net}, int @var{lna})
787 This function makes an Internet host address by combining the 
788 network number @var{net} with the local network address number @var{lna}.
789 @end deftypefun
790
791 @comment arpa/inet.h
792 @comment BSD
793 @deftypefun int inet_lnaof (struct in_addr @var{addr})
794 This function returns the local network address number part of the Internet
795 host address @var{addr}.
796 @end deftypefun
797
798 @comment arpa/inet.h
799 @comment BSD
800 @deftypefun int inet_netof (struct in_addr @var{addr})
801 This function returns the network address number part of the Internet host
802 address @var{addr}.
803 @end deftypefun
804
805 All of the functions listed in this section represent Internet addresses
806 in network byte order, and network numbers and local network address
807 numbers in host byte order.  @xref{Byte Order Conversion}.
808
809
810 @node Hosts Database
811 @subsection Hosts Database
812 @cindex hosts database
813 @cindex converting host name to address
814 @cindex converting host address to name
815
816 Besides the standard dot notation for Internet addresses, you can also
817 refer to a host by a symbolic name.  The advantage of a symbolic name is
818 that it is usually easier to remember.  For example, the machine with
819 Internet address @samp{128.52.46.32} is also known as
820 @samp{churchy.gnu.ai.mit.edu}; and other machines that belong to the
821 same network can reference it simply as @samp{churchy}.
822
823 @pindex /etc/hosts
824 Internally, the system uses a database to keep track of the mapping
825 between host names and host numbers.  This database is usually either
826 the file @file{/etc/hosts} or an equivalent provided by a name server.
827 The utilities for accessing this database are declared in @file{netdb.h}.
828 @pindex netdb.h
829
830 @comment netdb.h
831 @comment BSD
832 @deftp {struct Type} hostent
833 This data type is used to represent an entry in the hosts database.  It
834 has the following members:
835
836 @table @code
837 @item char *h_name
838 This is the ``official'' name of the host.
839
840 @item char **h_aliases
841 These are alternative names for the host, represented as a null-terminated
842 vector of strings.
843
844 @item int h_addrtype
845 This is the host address type; its value is always @code{AF_INET}.
846 @xref{Socket Naming}.
847
848 @item int h_length
849 This is the length, in bytes, of each address.
850
851 @item char **h_addr_list
852 This is the vector of addresses for the host.  (Recall that the host
853 might be connected to multiple networks and have different addresses on
854 each one.)  The vector is terminated by a null pointer.
855
856 @item char *h_addr
857 This is a synonym for @code{h_addr_list[0]}; in other words, it is the
858 first host address.
859 @end table
860 @end deftp
861
862 As far as the host database is concerned, each address is just a block
863 of memory @code{h_length} bytes long.  But in other contexts there is an
864 implicit assumption that you can cast this to a @code{struct in_addr} or
865 a @code{unsigned long int}.  Host addresses in a @code{struct hostent}
866 structure are always given in network byte order; see @ref{Byte Order
867 Conversion}.
868
869 You can use @code{gethostbyname} or @code{gethostbyaddr} to search the
870 hosts database for information about a particular host.  The information
871 is returned in a statically-allocated structure; you must copy the
872 information if you need to save it across calls.
873
874 @comment netdb.h
875 @comment BSD
876 @deftypefun {struct hostent *} gethostbyname (const char *@var{name})
877 The @code{gethostbyname} function returns information about the host
878 named @var{name}.  If the lookup fails, a null pointer is returned.
879 @end deftypefun
880
881 @comment netdb.h
882 @comment BSD
883 @deftypefun {struct hostent *} gethostbyaddr (const char *@var{addr}, int @var{length}, int @var{type})
884 The @code{gethostbyaddr} function returns information about the host
885 with Internet address @var{addr}.  The @var{length} argument is the size
886 (in bytes) of the @var{addr}.  The @var{type} is the type of the
887 address; for an Internet address, specify a value of @code{AF_INET}.
888
889 If the lookup fails, a null pointer is returned.
890 @end deftypefun
891
892 @vindex h_errno
893 If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
894 fails, you can get more information about the specific error code by
895 looking at the value of the variable @code{h_errno}.  If your program
896 uses this variable, you need to declare it like this:
897
898 @example
899 extern int h_errno;
900 @end example
901
902 The value of @code{h_errno} can be one of the following symbolic constants:
903
904 @comment netdb.h
905 @comment BSD
906 @deftypevr Macro int HOST_NOT_FOUND
907 No such host is known.
908 @end deftypevr
909
910 @comment netdb.h
911 @comment BSD
912 @deftypevr Macro int TRY_AGAIN
913 This condition happens when the name server could not be contacted.
914 If you trying again later, the request may succeed.
915 @end deftypevr
916
917 @comment netdb.h
918 @comment BSD 
919 @deftypevr Macro int NO_RECOVERY 
920 A non-recoverable error occurred.
921 @end deftypevr
922
923 @comment netdb.h
924 @comment BSD
925 @deftypevr Macro int NO_ADDRESS
926 The host database contains an entry for the name, but it doesn't have an
927 associated Internet address.
928 @end deftypevr
929
930 @strong{Incomplete:} Is there some similar error-reporting mechanism
931 for the other server-based databases?  
932
933 You can also scan the hosts database using @code{sethostent},
934 @code{gethostent}, and @code{endhostent}.
935
936 @comment netdb.h
937 @comment BSD
938 @deftypefun void sethostent (int @var{stayopen})
939 This function opens and rewinds the hosts database.  If the
940 @var{stayopen} argument is true, the database stays open after calls to
941 @code{gethostbyname} or @code{gethostbyaddr}.
942 @end deftypefun
943
944 @comment netdb.h
945 @comment BSD
946 @deftypefun {struct hostent *} gethostent (void)
947 This function returns the next entry in the hosts database.  A null
948 pointer is returned if there are no more entries.
949 @end deftypefun
950
951 @comment netdb.h
952 @comment BSD
953 @deftypefun void endhostent (void)
954 This function closes the hosts database.
955 @end deftypefun
956
957
958 @node Services Database
959 @subsection Services Database
960 @cindex services database
961 @cindex converting service name to port number
962 @cindex converting port number to service name
963
964 Once you have figured out the address of the host you wish to talk to,
965 the next step is to figure out which specific port on that machine to
966 use.
967
968 Port numbers less than 1024 are reserved for ``well-known'' services, or
969 system daemons such as the servers for @code{finger} and @code{telnet}.
970 Again, there is a database that keeps track of these, and you can use
971 the @code{getservbyname} function to map a service name onto a port
972 number.
973
974 Typically, only privileged system-level processes that are run
975 automatically are registered in the services database.  If you are
976 writing your own user-level server, you can simply choose an arbitrary
977 port number greater than or equal to 1024 for it to accept connections
978 on.
979
980 There aren't any built-in protection mechanisms for controlling
981 access to ports.  If you want to restrict access to your server, you
982 should have it examine the addresses associated with connection requests
983 or implement some other handshaking or identification protocol.
984
985 @pindex /etc/services
986 The database that keeps track of ``well-known'' services is usually
987 either the file @file{/etc/services} or an equivalent from a name server.
988 You can use these utilities, declared in @file{netdb.h}, to access
989 the services database.
990 @pindex netdb.h
991
992 @comment netdb.h
993 @comment BSD
994 @deftp {struct Type} servent
995 This data type holds information about entries from the services database.
996 It has the following members:
997
998 @table @code
999 @item char *s_name
1000 This is the ``official'' name of the service.
1001
1002 @item char **s_aliases
1003 These are alternate names for the service, represented as an array of
1004 strings.  A null pointer terminates the array.
1005
1006 @item int s_port
1007 This is the port number for the service.  Port numbers are given in
1008 network byte order; see @ref{Byte Order Conversion}.
1009
1010 @item char *s_proto
1011 This is the name of the protocol to use with this service.
1012 @xref{Protocols Database}.
1013 @end table
1014 @end deftp
1015
1016 To get information about a particular service, use the
1017 @code{getservbyname} or @code{getservbyport} functions.  The information
1018 is returned in a statically-allocated structure; you must copy the
1019 information if you need to save it across calls.
1020
1021 @comment netdb.h
1022 @comment BSD
1023 @deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto})
1024 The @code{getservbyname} function returns information about the service
1025 named @var{name} using protocol @var{proto}.  If the lookup fails, a
1026 null pointer is returned.
1027 @end deftypefun
1028
1029 @comment netdb.h
1030 @comment BSD
1031 @deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto})
1032 The @code{getservbyport} function returns information about the service
1033 at port @var{port} using protocol @var{proto}.  If the lookup fails, a
1034 null pointer is returned.
1035 @end deftypefun
1036
1037 You can also scan the services database using @code{setservent},
1038 @code{getservent}, and @code{endservent}.
1039
1040 @comment netdb.h
1041 @comment BSD
1042 @deftypefun void setservent (int @var{stayopen})
1043 This function opens and rewinds the services database.  If the
1044 @var{stayopen} argument is true, the database stays open after calls to
1045 @code{getservbyname} or @code{getservbyport}.
1046 @end deftypefun
1047
1048 @comment netdb.h
1049 @comment BSD
1050 @deftypefun {struct servent *} getservent (void)
1051 This function returns the next entry in the services database.  A null
1052 pointer is returned if there are no more entries.
1053 @end deftypefun
1054
1055 @comment netdb.h
1056 @comment BSD
1057 @deftypefun void endservent (void)
1058 This function closes the services database.
1059 @end deftypefun
1060
1061
1062 @node Networks Database
1063 @subsection Networks Database
1064 @cindex networks database
1065 @cindex converting network number to network name
1066 @cindex converting network name to network number
1067
1068 @pindex /etc/networks
1069 There is also a database that keeps track of all the known networks.
1070 This is usually either the file @file{/etc/networks} or an equivalent
1071 from a name server.  
1072
1073 The following utilities for accessing the networks database are declared
1074 in @file{netdb.h}.  You usually don't have to worry about the networks
1075 database to write a program that uses sockets; the information is
1076 presented here for completeness only.
1077 @pindex netdb.h
1078
1079 @comment netdb.h
1080 @comment BSD
1081 @deftp {struct Type} netent
1082 This data type is used to represent information about entries in the
1083 networks database.  It has the following members:
1084
1085 @table @code
1086 @item char *n_name
1087 This is the ``official'' name of the network.
1088
1089 @item char **n_aliases
1090 These are alternative names for the network, represented as a vector
1091 of strings.  A null pointer terminates the array.
1092
1093 @item int n_addrtype
1094 This is the type of the network number; this is always equal to
1095 @code{AF_INET} for Internet networks.
1096
1097 @item unsigned long int n_net
1098 This is the network number.  Network numbers are returned in host
1099 byte order; see @ref{Byte Order Conversion}.
1100 @end table
1101 @end deftp
1102
1103 Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search
1104 the networks database for information about a specific network.  The
1105 information is returned in a statically-allocated structure; you must
1106 copy the information if you need to save it.
1107
1108 @comment netdb.h
1109 @comment BSD
1110 @deftypefun {struct netent *} getnetbyname (const char *@var{name})
1111 The @code{getnetbyname} function returns information about the network
1112 named @var{name}.  If the lookup fails, a null pointer is returned.
1113 @end deftypefun
1114
1115 @comment netdb.h
1116 @comment BSD
1117 @deftypefun {struct netent *} getnetbyaddr (long @var{net}, int @var{type})
1118 The @code{getnetbyaddr} function returns information about the network
1119 of type @var{type} with number @var{net}.  You should specify a value of
1120 @code{AF_INET} for the @var{type} argument for Internet networks.  
1121
1122 If the lookup fails, a null pointer is returned.
1123 @end deftypefun
1124
1125 You can also scan the networks database using @code{setnetent},
1126 @code{getnetent}, and @code{endnetent}.
1127
1128 @comment netdb.h
1129 @comment BSD
1130 @deftypefun void setnetent (int @var{stayopen})
1131 This function opens and rewinds the networks database.  If the
1132 @var{stayopen} argument is true, the database stays open after calls to
1133 @code{getnetbyname} or @code{getnetbyaddr}.
1134 @end deftypefun
1135
1136 @comment netdb.h
1137 @comment BSD
1138 @deftypefun {struct netent *} getnetent (void)
1139 This function returns the next entry in the networks database.  A null
1140 pointer is returned if there are no more entries.
1141 @end deftypefun
1142
1143 @comment netdb.h
1144 @comment BSD
1145 @deftypefun void endnetent (void)
1146 This function closes the networks database.
1147 @end deftypefun
1148
1149
1150 @node Byte Order Conversion
1151 @subsection Byte Order Conversion
1152 @cindex byte order conversion, for socket
1153 @cindex converting byte order
1154
1155 @cindex network byte order
1156 Finally, there is one more wrinkle: the byte ordering of the data in the
1157 @code{sin_port} and @code{sin_addr} members of the @code{sockaddr_in}
1158 structure must be canonicalized into the @dfn{network byte order}.  This
1159 ensures that machines that use different native byte ordering conventions
1160 can still talk to each other.  If you don't do this, your program may fail
1161 when running on or talking to other kinds of machines.
1162
1163 If you use @code{getservbyname} and @code{gethostbyname} or
1164 @code{inet_addr} to get the port number and host address, the values are
1165 already in the network byte order, and you can copy them directly into
1166 the @code{sockaddr_in} structure.
1167
1168 Otherwise, you have to convert the values explicitly.  Use
1169 @code{htons} and @code{ntohs} to convert values for the @code{sin_port}
1170 member.  Use @code{htonl} and @code{ntohl} to convert values for the
1171 @code{sin_addr} member.  (Remember, @code{struct in_addr} is equivalent
1172 to @code{unsigned long int}.)  These functions are declared in
1173 @file{netinet/in.h}.
1174 @pindex netinet/in.h
1175
1176 @comment netinet/in.h
1177 @comment BSD
1178 @deftypefun {unsigned short int} htons (unsigned short int @var{hostshort})
1179 This function converts the @code{short} integer @var{hostshort} from
1180 host byte order to network byte order.
1181 @end deftypefun
1182
1183 @comment netinet/in.h
1184 @comment BSD
1185 @deftypefun {unsigned short int} ntohs (unsigned short int @var{netshort})
1186 This function converts the @code{short} integer @var{netshort} from
1187 network byte order to host byte order.
1188 @end deftypefun
1189
1190 @comment netinet/in.h
1191 @comment BSD
1192 @deftypefun {unsigned long int} htonl (unsigned long int @var{hostlong})
1193 This function converts the @code{long} integer @var{hostlong} from
1194 host byte order to network byte order.
1195 @end deftypefun
1196
1197 @comment netinet/in.h
1198 @comment BSD
1199 @deftypefun {unsigned long int} ntohl (unsigned long int @var{netlong})
1200 This function converts the @code{long} integer @var{netlong} from
1201 network byte order to host byte order.
1202 @end deftypefun
1203
1204 @node Internet Socket Example
1205 @subsection Internet Socket Example
1206
1207 Here is an example showing how to create and name a socket in the
1208 Internet domain.  Since the newly created socket exists on the local
1209 machine that the program is running on, this example uses @code{INADDR_ANY}
1210 as the host address.
1211
1212 @comment This example is from isockserver.c.
1213 @example
1214 #include <sys/socket.h>
1215 #include <netdb.h>
1216 #include <netinet/in.h>
1217 #include <sys/types.h>
1218 #include <stdio.h>
1219 #include <errno.h>
1220 #include <stdlib.h>
1221
1222 int make_socket (unsigned short int port)
1223 @{
1224   int sock, status;
1225   struct sockaddr_in name;
1226   unsigned long int addr;
1227
1228   /* @r{Create the socket.} */
1229   sock = socket (PF_INET, SOCK_STREAM, 0);
1230   if (sock < 0) @{
1231     perror ("socket");
1232     exit (EXIT_FAILURE);
1233   @}
1234
1235   /* @r{Give the socket a name.} */
1236   name.sin_family = AF_INET;
1237   name.sin_port = htons (port);
1238   addr = htonl (INADDR_ANY);
1239   memcpy (&name.sin_addr, &addr, sizeof (addr));
1240   status = bind (sock, (struct sockaddr *)&name, sizeof (name));
1241   if (status < 0) @{
1242     perror ("bind");
1243     exit (EXIT_FAILURE);
1244   @}
1245
1246   return sock;
1247 @}
1248 @end example
1249
1250 Here is another example, showing how you can fill in a @code{sockaddr_in}
1251 structure, given a host name string and a port number:
1252
1253 @comment This example is from isockclient.c.
1254 @example
1255 void init_sockaddr (struct sockaddr_in *name, const char *hostname,
1256                     unsigned short int port)
1257 @{
1258   struct hostent *hostinfo;
1259
1260   name->sin_family = AF_INET;
1261   name->sin_port = htons (PORT);
1262   hostinfo = gethostbyname (SERVERHOST);
1263   if (!hostinfo) @{
1264     fprintf (stderr, "Unknown host %s.\n", SERVERHOST);
1265     exit (EXIT_FAILURE);
1266   @}
1267   memcpy (&name->sin_addr, hostinfo->h_addr, sizeof (unsigned long int));
1268 @}
1269 @end example
1270
1271
1272 @node Types of Sockets
1273 @section Types of Sockets
1274
1275 The GNU library includes support for several different kinds of sockets,
1276 each with different characteristics.  This section describes the
1277 supported socket types.  The symbolic constants listed here are
1278 defined in @file{sys/socket.h}.
1279 @pindex sys/socket.h
1280
1281 Each socket type has a number of attributes that characterize it.
1282
1283 @itemize @bullet
1284 @cindex datagram
1285 @item
1286 Data may be organized as a byte stream, or as a @dfn{datagram} or
1287 message packet.  In the latter case, record boundaries between
1288 messages are preserved.
1289
1290 @item
1291 The socket may maintain a connection to one particular peer socket, or
1292 messages may be addressed individually.
1293
1294 @item
1295 Lost messages or messages received with errors may be retransmitted
1296 automatically, or simply ignored.  
1297
1298 @item
1299 Messages may be guaranteed to arrive in sequence, or permitted to
1300 arrive out of order or be duplicated.
1301 @end itemize
1302
1303 @comment sys/socket.h
1304 @comment BSD
1305 @deftypevr Macro int SOCK_STREAM
1306 The @code{SOCK_STREAM} socket type is similar to a pipe; it provides
1307 a byte stream based communications channel with connection state
1308 and reliable, sequential transmission of messages.
1309
1310 Operations on this type of stream are covered in detail in @ref{Byte
1311 Stream Socket Operations}.
1312 @end deftypevr
1313
1314 @comment sys/socket.h
1315 @comment BSD
1316 @deftypevr Macro int SOCK_DGRAM
1317 The @code{SOCK_DGRAM} socket type is used for sending individually-addressed
1318 datagrams.  This kind of socket does not guarantee reliable or sequential
1319 transmission of messages.  It is typically used in situations where
1320 it is acceptible to simply resend the message if no response is seen
1321 in a reasonable amount of time.
1322
1323 @ref{Datagram Socket Operations}, contains detailed information about
1324 how to use sockets of this type.
1325 @end deftypevr
1326
1327 @comment sys/socket.h
1328 @comment BSD
1329 @deftypevr Macro int SOCK_SEQPACKET
1330 This socket type is similar to @code{SOCK_STREAM}, except that messages
1331 are sent by datagrams rather than as bytes.  This socket type may not
1332 be supported by all protocols.
1333 @end deftypevr
1334
1335 @comment sys/socket.h
1336 @comment BSD
1337 @deftypevr Macro int SOCK_RDM
1338 This socket type is similar to @code{SOCK_DGRAM}, except that reliable
1339 delivery of datagrams is guaranteed.  This socket type may not be
1340 supported by all protocols.
1341 @end deftypevr
1342
1343 @comment sys/socket.h
1344 @comment BSD
1345 @deftypevr Macro int SOCK_RAW
1346 This socket type provides access to internal network protocols and
1347 interfaces.  Ordinary user programs usually have no need to use this
1348 socket type.
1349 @end deftypevr
1350
1351
1352 @node Byte Stream Socket Operations
1353 @section Byte Stream Socket Operations
1354 @cindex byte stream socket
1355
1356 This section describes operations on sockets that have connection state, 
1357 such as @code{SOCK_STREAM} sockets.
1358
1359 @iftex
1360 @itemize @bullet
1361 @item
1362 @ref{Establishing a Connection}, describes how two processes establish a
1363 connection.
1364
1365 @item
1366 @ref{Transferring Data}, describes how data is transferred through the
1367 connected socket.
1368 @end itemize
1369 @end iftex
1370
1371 @menu
1372 * Establishing a Connection::   The socket must be connected before it
1373                                  can transmit data.
1374 * Transferring Data::           How to send and receive data.
1375 * Byte Stream Socket Example::  An example program.
1376 * Out-of-Band Data::            This is an advanced feature.
1377 @end menu
1378
1379 @node Establishing a Connection
1380 @subsection Establishing a Connection
1381 @cindex connecting a socket
1382 @cindex socket, connecting
1383
1384 Before two processes can exchange data through a socket, they must
1385 establish a connection.  One process acts as a server and waits
1386 for a connection by calling the @code{listen} and @code{accept}
1387 function; the other process acts as the client and initiates the
1388 connection by calling the @code{connect} function.
1389
1390 @comment sys/socket.h
1391 @comment BSD
1392 @deftypefun int connect (int @var{filedes}, struct sockaddr *@var{addr}, size_t @var{length})
1393 The @code{connect} function initiates a connection from the socket with
1394 file descriptor @var{filedes} to the socket whose address is specified
1395 by the @var{addr} and @var{length} arguments.  @xref{Socket Naming}, for
1396 information about how these arguments are interpreted.
1397
1398 The normal return value from @code{connect} is @code{0}.  If an error
1399 occurs, @code{connect} returns @code{-1}.  The following @code{errno}
1400 error conditions are defined for this function:
1401
1402 @table @code
1403 @item EBADF
1404 The @var{filedes} is not a valid file descriptor.
1405
1406 @item ENOTSOCK
1407 The @var{filedes} is not a socket.
1408
1409 @item EADDRNOTAVAIL
1410 The specified address is not available on this machine.
1411
1412 @item EAFNOSUPPORT
1413 The address family of the @var{addr} is not supported by this socket.
1414
1415 @item EISCONN
1416 The socket is already connected.
1417
1418 @item ETIMEDOUT
1419 The attempt to establish the connection timed out.
1420
1421 @item ECONNREFUSED
1422 The attempt to establish the connection was actively refused by the peer.
1423
1424 @item ENETUNREACH
1425 The network isn't reachable from this host.
1426
1427 @item EADDRINUSE
1428 The socket address is already in use.
1429
1430 @item EINPROGRESS
1431 The socket is non-blocking and the connection could not be established
1432 immediately.
1433
1434 @item EALREADY
1435 The socket is non-blocking and already has a pending connection in progress.
1436 @end table
1437 @end deftypefun
1438
1439 @comment sys/socket.h
1440 @comment BSD
1441 @deftypefun int listen (int @var{filedes}, unsigned int @var{n})
1442 The @code{listen} function specifies that the socket @var{filedes} is
1443 willing to accept connections.  
1444
1445 The argument @var{n} specifies the length of the queue for pending
1446 connections.  If more than this many connection requests arrive without
1447 actually being accepted via a call to @code{accept}, additional
1448 @code{connect} requests to this socket are either refused with a
1449 @code{ECONNREFUSED} error or retransmitted (depending on the particular
1450 socket protocol).  The system may also impose its own internal limit on
1451 the length of this queue.
1452
1453 The @code{listen} function returns @code{0} on success and @code{-1}
1454 on failure.  The following @code{errno} error conditions are defined
1455 for this function:
1456
1457 @table @code
1458 @item EBADF
1459 The argument @var{filedes} is not a valid file descriptor.
1460
1461 @item ENOTSOCK
1462 The argument @var{filedes} is not a socket.
1463
1464 @item EOPNOTSUPP
1465 The socket @var{filedes} does not support this operation.
1466 @end table
1467 @end deftypefun
1468
1469 @comment sys/socket.h
1470 @comment BSD
1471 @deftypefun int accept (int @var{filedes}, struct sockaddr *@var{addr}, size_t *@var{length_ptr})
1472 This function is used to accept a connection to the socket @var{filedes}.
1473 You must first call @code{listen} on this socket to enable connections to
1474 be made.
1475
1476 The @code{accept} function blocks the calling process if there
1477 are no connections pending, unless the socket @var{filedes} has
1478 nonblocking mode set.  @xref{File Status Flags}.
1479
1480 The @var{sockaddr} and @var{length_ptr} arguments are used to return
1481 information about the name of the peer socket that initiated the
1482 connection.  @xref{Socket Naming}, for information about the format of
1483 the information.
1484
1485 The normal return value from @code{accept} is a newly allocated file
1486 descriptor that refers to the connection; you should use this file
1487 descriptor for transferring data.  The original socket @var{filedes}
1488 remains open, and you can pass it to @code{accept} again to make further
1489 connections.
1490
1491 If an error occurs, @code{accept} returns @code{-1}.  The following
1492 @code{errno} error conditions are defined for this function:
1493
1494 @table @code
1495 @item EBADF
1496 The @var{filedes} argument is not a valid file descriptor.
1497
1498 @item ENOTSOCK
1499 The @var{filedes} argument is not a socket.
1500
1501 @item EOPNOTSUPP
1502 The @var{filedes} does not support this operation.
1503
1504 @item EWOULDBLOCK
1505 The @var{filedes} has nonblocking mode set, and there are no pending
1506 connections immediately available.
1507 @end table
1508 @end deftypefun
1509
1510 @comment sys/socket.h
1511 @comment BSD
1512 @deftypefun int getpeername (int @var{filedes}, struct sockaddr *@var{addr}, size_t *@var{length_ptr})
1513 The @code{getpeername} function returns the address of the peer
1514 connected to the socket @var{filedes} in the locations pointed at by the
1515 @var{addr} and @var{length_ptr} arguments.  @xref{Socket Naming}, for
1516 information about the format of this information.
1517
1518 The return value is @code{0} on success and @code{-1} on error.  The
1519 following @code{errno} error conditions are defined for this function:
1520
1521 @table @code
1522 @item EBADF
1523 The argument @var{filedes} is not a valid file descriptor.
1524
1525 @item ENOTSOCK
1526 The argument @var{filedes} is not a socket.
1527
1528 @item ENOTCONN
1529 The socket @var{filedes} is not connected.
1530
1531 @item ENOBUFS
1532 There are not enough internal buffers available.
1533 @end table
1534 @end deftypefun
1535
1536
1537 @node Transferring Data
1538 @subsection Transferring Data
1539 @cindex reading from a socket
1540 @cindex writing to a socket
1541
1542 Once a socket has been connected to a peer, you can use the ordinary
1543 @code{read} and @code{write} operations (@pxref{I/O Primitives}) to
1544 transfer data.  A socket is a two-way communications channel, so read
1545 and write operations can be performed at either end.
1546
1547 You can also use the @code{send} and @code{recv} functions to perform
1548 read and write operations while specifying additional flags.  The
1549 prototypes for these functions are in the header file
1550 @file{sys/socket.h}.
1551 @pindex sys/socket.h
1552
1553 @comment sys/socket.h
1554 @comment BSD
1555 @deftypefun int send (int @var{filedes}, void *@var{buffer}, size_t @var{size}, int @var{flags})
1556 The @code{send} function is like @code{write}, but with the additional
1557 flags @var{flags}.  The possible values of the @var{flags} are described
1558 below.
1559
1560 This function returns the number of bytes transmitted, or @code{-1} on
1561 failure.  Note, however, that a successful return value merely indicates
1562 that the message has been sent without error, not necessarily that it
1563 has been received without error.
1564
1565 The following @code{errno} error conditions are defined for this function:
1566
1567 @table @code
1568 @item EBADF
1569 The @var{filedes} argument is not a valid file descriptor.
1570
1571 @item ENOTSOCK
1572 The @var{filedes} argument is not a socket.
1573
1574 @item EMSGSIZE
1575 The socket type requires that the message be sent atomically, but the
1576 message is too large for this to be possible.
1577
1578 @item EWOULDBLOCK
1579 Nonblocking mode has been set on the socket, and the write operation
1580 would block.  (Normally @code{send} blocks until the operation can be
1581 completed.)
1582
1583 @item ENOBUFS
1584 There is not enough internal buffer space available.
1585 @end table
1586 @end deftypefun
1587
1588 @comment sys/socket.h
1589 @comment BSD
1590 @deftypefun int recv (int @var{filedes}, void *@var{buffer}, size_t @var{size}, int @var{flags})
1591 The @code{recv} function is like @code{read}, but with the additional
1592 flags @var{flags}.  The possible values of the @var{flags} are described
1593 below.
1594
1595 This function returns the number of bytes received, or @code{-1} on failure.
1596 The following @code{errno} error conditions are defined for this function:
1597
1598 @table @code
1599 @item EBADF
1600 The @var{filedes} argument is not a valid file descriptor.
1601
1602 @item ENOTSOCK
1603 The @var{filedes} argument is not a socket.
1604
1605 @item EWOULDBLOCK
1606 Nonblocking mode has been set on the socket, and the read operation
1607 would block.  (Normally, @code{recv} blocks until there is input available
1608 to be read.)
1609
1610 @item EINTR
1611 The operation was interrupted by a signal before any data was read.
1612 @end table
1613 @end deftypefun
1614
1615 The @var{flags} argument to these functions is a bit mask.  You can
1616 bitwise-OR the values of the following macros together to obtain a
1617 value for this argument.
1618
1619 @comment sys/socket.h
1620 @comment BSD
1621 @deftypevr Macro int MSG_OOB
1622 Send or receive out-of-band data.  @xref{Out-of-Band Data}.
1623 @end deftypevr
1624
1625 @comment sys/socket.h
1626 @comment BSD
1627 @deftypevr Macro int MSG_PEEK
1628 Look at the data but don't remove it from the input queue.  This is
1629 only useful on read operations.
1630 @end deftypevr
1631
1632 @comment sys/socket.h
1633 @comment BSD
1634 @deftypevr Macro int MSG_DONTROUTE
1635 Don't include routing information in the message.  This is only useful
1636 on write operations, and is generally only of interest for diagnostic or
1637 routing programs.
1638 @end deftypevr
1639
1640 @node Byte Stream Socket Example
1641 @subsection Byte Stream Socket Example
1642
1643 Here are a set of example programs that show communications over a 
1644 byte stream socket in the Internet domain.  These programs use the
1645 @code{make_socket} and @code{init_sockaddr} functions that were presented
1646 in @ref{Internet Socket Example} to set up the socket names.
1647
1648 First, here is the client program.  It doesn't do anything particularly
1649 interesting once it has connected to the server; it just sends a message
1650 to the server and exits.
1651
1652 @comment This example is from isockclient.c.
1653 @example
1654 #include <sys/socket.h>
1655 #include <netdb.h>
1656 #include <netinet/in.h>
1657 #include <sys/types.h>
1658 #include <stdio.h>
1659 #include <errno.h>
1660 #include <stdlib.h>
1661
1662
1663 #define PORT 2222
1664 #define MESSAGE "Yow!!! Are we having fun yet?!?"
1665 #define SERVERHOST "churchy.gnu.ai.mit.edu"
1666
1667
1668 void write_to_server (int filedes)
1669 @{
1670   int nbytes;
1671
1672   nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1);
1673   if (nbytes < 0) @{
1674     perror ("write");
1675     exit (EXIT_FAILURE);
1676   @}
1677 @}
1678
1679
1680 void main (void)
1681 @{
1682   int sock;
1683   int status;
1684   struct sockaddr_in servername;
1685
1686   /* @r{Create the socket.}  */
1687   sock = socket (PF_INET, SOCK_STREAM, 0);
1688   if (sock < 0) @{
1689     perror ("socket (client)");
1690     exit (EXIT_FAILURE);
1691   @}
1692
1693   /* @r{Connect to the server.}  */
1694   init_sockaddr (&servername, SERVERHOST, PORT);
1695   status = connect (sock, (struct sockaddr *) &servername,
1696                     sizeof (servername));
1697   if (status < 0) @{
1698     perror ("connect (client)");
1699     exit (EXIT_FAILURE);
1700   @}
1701
1702   /* @r{Send data to the server.} */
1703   write_to_server (sock);
1704   close (sock);
1705   exit (EXIT_SUCCESS);
1706 @}
1707 @end example
1708
1709 The server end is much more complicated.  Since we want to allow
1710 multiple clients to be connected to the server at the same time, it
1711 would be incorrect to wait for input from a single client by simply
1712 calling @code{read} or @code{recv}.  Instead, the right thing to do is
1713 to use @code{select} (described in @ref{Waiting for I/O}) to wait for
1714 input on all of the open sockets.  This also allows the server to deal
1715 with additional connection requests.
1716
1717 Again, this particular program doesn't do anything very exciting once it
1718 has gotten a message from a client.  It does close the socket for that
1719 client when it detects and end-of-file condition (resulting from the
1720 client shutting down its end of the connection).
1721
1722 @comment This example is isockserver.c.
1723 @example
1724 #include <sys/socket.h>
1725 #include <netdb.h>
1726 #include <netinet/in.h>
1727 #include <sys/types.h>
1728 #include <stdio.h>
1729 #include <errno.h>
1730 #include <stdlib.h>
1731
1732 #define PORT 2222
1733 #define MAXMSG 512
1734
1735 int read_from_client (int filedes)
1736 @{
1737   char buffer[MAXMSG];
1738   int nbytes;
1739
1740   nbytes = read (filedes, buffer, MAXMSG);
1741   if (nbytes < 0) @{
1742     /* Read error. */
1743     perror ("read");
1744     exit (EXIT_FAILURE);
1745   @}
1746   else if (nbytes == 0) @{
1747     /* End-of-file. */
1748     return -1;
1749   @}
1750   else @{
1751     /* Data read. */
1752     fprintf (stderr, "Server:  got message: %s\n", buffer);
1753     return 0;
1754   @}
1755 @}
1756
1757
1758 void main (void)
1759 @{
1760   int sock;
1761   int status;
1762   fd_set active_fd_set, read_fd_set;
1763   int i;
1764   struct sockaddr_in clientname;
1765   size_t size;
1766
1767   /* @r{Create the socket and set it up to accept connections.} */
1768   sock = make_socket (PORT);
1769   status = listen (sock, 1);
1770   if (status < 0) @{
1771     perror ("listen");
1772     exit (EXIT_FAILURE);
1773   @}
1774
1775   /* @r{Initialize the set of active sockets.} */
1776   FD_ZERO (&active_fd_set);
1777   FD_SET (sock, &active_fd_set);
1778
1779   while (1) @{
1780     /* @r{Block until input arrives on one or more active sockets.} */
1781     memcpy (&read_fd_set, &active_fd_set, sizeof (active_fd_set));
1782     status = select (FD_SETSIZE, &read_fd_set, NULL, NULL, NULL);
1783     if (status < 0) @{
1784       perror ("select");
1785       exit (EXIT_FAILURE);
1786     @}
1787     /* @r{Service all the sockets with input pending.} */
1788     for (i=0; i<FD_SETSIZE; i++)  @{
1789       if (FD_ISSET (i, &read_fd_set)) @{
1790
1791         /* @r{Connection request on original socket.} */
1792         if (i == sock) @{
1793           size = sizeof (clientname);
1794           status = accept (sock, (struct sockaddr *)&clientname, &size);
1795           if (status < 0) @{
1796             perror ("accept");
1797             exit (EXIT_FAILURE);
1798           @}
1799           fprintf (stderr, "Server: connection from host %s, port %d.\n",
1800                    inet_ntoa (clientname.sin_addr),
1801                    ntohs (clientname.sin_port));
1802           FD_SET (status, &active_fd_set);
1803         @}
1804
1805         /* @r{Data arriving on an already-connected socket.} */
1806         else @{
1807           if (read_from_client (i) < 0) @{
1808             close (i);
1809             FD_CLR (i, &active_fd_set);
1810           @}
1811         @}
1812       @}
1813     @}
1814   @}
1815 @}
1816 @end example
1817
1818
1819 @node Out-of-Band Data
1820 @subsection Out-of-Band Data
1821
1822 @cindex out-of-band data
1823 @cindex urgent socket condition
1824 Streams of type @code{SOCK_STREAM} support the concept of
1825 @dfn{out-of-band} data that is transmitted in a channel in parallel with
1826 that used for ordinary data transmission.  Out-of-band data is typically
1827 used to flag exceptional conditions.
1828
1829 When out-of-band data is pending on a socket, a @code{SIGURG} signal is
1830 sent to the owner process or process group of the socket.  You establish
1831 this using the @code{F_SETOWN} command to the @code{fcntl} function;
1832 see @ref{Interrupt Input}.  You can establish a handler for this signal,
1833 as described in @ref{Signal Handling}.
1834
1835 Alternatively, you can get synchronous notification of pending
1836 out-of-band data by using the @code{select} function to wait for an
1837 exceptional condition on the socket.  @xref{Waiting for I/O}, for more
1838 information about @code{select}.
1839
1840 Receiving a @code{SIGURG} signal only means that out-of-band data is
1841 pending, not that it has arrived.  If you try to read the out-of-band
1842 data with @code{recv} when it has not yet arrived, it fails with a
1843 @code{EWOULDBLOCK} error.  You may even need to read some of the in-band
1844 data to empty out internal buffers before the out-of-band data can be
1845 delivered.
1846
1847
1848 @node Datagram Socket Operations
1849 @section Datagram Socket Operations
1850 @cindex datagram socket
1851 This section describes functions for sending messages on datagram
1852 sockets (type @code{SOCK_DGRAM}).  Unlike the byte stream sockets
1853 discussed in @ref{Byte Stream Socket Operations}, these sockets do
1854 not support any notion of connection state.  Instead, each message
1855 is addressed individually.
1856
1857 The @code{listen} and @code{accept} functions cannot be used on datagram
1858 sockets.  You can call @code{connect} on a datagram socket, but this
1859 only affects the local state of the socket.  It remembers the specified
1860 address as the default for any further data transmission on the socket.
1861 You can remove the connection by calling @code{connect} again and
1862 specifying an address family of @code{AF_UNSPEC} in the @var{addr}
1863 argument.  @xref{Establishing a Connection}, for more information about
1864 the @code{connect} function.
1865
1866 @menu
1867 * Transmitting Datagrams::      Functions for sending and receiving messages
1868                                  on a datagram socket.
1869 * Datagram Socket Example::     An example program.
1870 @end menu
1871
1872 @node Transmitting Datagrams
1873 @subsection Transmitting Datagrams
1874 @cindex sending a datagram
1875 @cindex receiving a datagram
1876 @cindex transmitting datagrams
1877 @cindex datagrams, transmitting
1878
1879 The normal way of sending data on an unconnected datagram socket is
1880 by using the @code{sendto} function.  The @code{recvfrom} function 
1881 reads data from an unconnected datagram socket.  Both of these functions
1882 are declared in @file{sys/socket.h}.
1883 @pindex sys/socket.h
1884
1885 @comment sys/socket.h
1886 @comment BSD
1887 @deftypefun int sendto (int @var{filedes}, void *@var{buffer}. size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, size_t @var{length})
1888 The @code{sendto} function transmits the data in the @var{buffer}
1889 through the socket @var{filedes} to the target socket named by the
1890 @var{addr} and @var{length} arguments.  The @var{size} argument
1891 specifies the number of bytes to be transmitted.
1892
1893 The @var{flags} are interpreted the same way as for @code{send};
1894 see @ref{Transferring Data}.  The return value and error conditions are
1895 also the same as for @code{send}.
1896 @end deftypefun
1897
1898 @comment sys/socket.h
1899 @comment BSD
1900 @deftypefun int recvfrom (int @var{filedes}, void *@var{buffer}. size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, size_t *@var{length_ptr})
1901 The @code{recvfrom} function reads data from the socket @var{filedes} into
1902 the buffer @var{buffer}.  The @var{size} argument specifies the maximum
1903 number of bytes to be read.
1904
1905 The @var{addr} and @var{length_ptr} arguments are used to return information
1906 about the peer socket that sent the information.  @xref{Socket Naming}.
1907 You can specify a null pointer as the @var{addr} argument if you are not
1908 interested in this information.
1909
1910 The @var{flags} are interpreted the same way as for @code{recv};
1911 see @ref{Transferring Data}.  The return value and error conditions are
1912 also the same as for @code{recv}.
1913 @end deftypefun
1914
1915 @ignore
1916 @strong{Incomplete:}  I am not sure what this is for.  It seems to be
1917 related to @code{readv}, which I don't understand either.
1918
1919 @comment sys/socket.h
1920 @comment BSD
1921 @deftp {struct Type} msghdr
1922 @end deftp
1923
1924 @comment sys/socket.h
1925 @comment BSD
1926 @deftypefun int sendmsg (int @var{filedes}, const struct msghdr *@var{message}, int @var{flags})
1927 @end deftypefun
1928
1929 @comment sys/socket.h
1930 @comment BSD
1931 @deftypefun int recvmsg (int @var{filedes}, struct msghdr *@var{message}, int @var{flags})
1932 @end deftypefun
1933 @end ignore
1934
1935 @node Datagram Socket Example
1936 @subsection Datagram Socket Example
1937
1938 Here is a set of example programs that send messages over a datagram
1939 stream in the local domain.  Both the client and server programs use the
1940 @code{make_named_socket} function that was presented in @ref{The Local
1941 Domain} to create and name their sockets.
1942
1943 First, here is the server program.  It sits in a loop waiting for
1944 messages to arrive, bouncing each message back to the sender.
1945 Obviously, this isn't a particularly useful program, but it does show
1946 the general ideas involved.
1947
1948 @comment This example is from lsockserver.c.
1949
1950 @example
1951 #include <sys/socket.h>
1952 #include <sys/un.h>
1953 #include <stdio.h>
1954 #include <errno.h>
1955 #include <stdlib.h>
1956
1957 #define SERVER "/tmp/serversocket"
1958 #define MAXMSG 512
1959
1960 void main (void)
1961 @{
1962   int sock;
1963   char message[MAXMSG];
1964   struct sockaddr_un name;
1965   size_t size;
1966   int nbytes;
1967
1968   /* @r{Make the socket, then loop endlessly.} */
1969
1970   sock = make_named_socket (SERVER);
1971   while (1) @{
1972
1973     /* @r{Wait for a datagram.} */
1974     size = sizeof (name);
1975     nbytes = recvfrom (sock, message, MAXMSG, 0,
1976                        (struct sockaddr *)&name, &size);
1977     if (nbytes < 0) @{
1978       perror ("recfrom (server)");
1979       exit (EXIT_FAILURE);
1980     @}
1981
1982     /* @r{Give a diagnostic message.} */
1983     fprintf (stderr, "Server: got message: %s\n", message);
1984
1985     /* @r{Bounce the message back to the sender.} */
1986     nbytes = sendto (sock, message, nbytes, 0,
1987                      (struct sockaddr *)&name, size);
1988     if (nbytes < 0) @{
1989       perror ("sendto (server)");
1990       exit (EXIT_FAILURE);
1991     @}
1992   @}
1993 @}
1994 @end example
1995
1996 Next, here is the client program.  It sends a datagram to the server
1997 and then waits for a reply.  Notice that the socket for the client (as
1998 well as for the server) in this example has to be given a name.  This is 
1999 so that the server can direct a message back to the client.  Since the
2000 socket has no associated connection state, the only way the server can
2001 do this is by referencing the name of the client.
2002
2003 @comment This example is from lsockclient.c.
2004
2005 @example
2006 #include <sys/socket.h>
2007 #include <sys/un.h>
2008 #include <stdio.h>
2009 #include <errno.h>
2010 #include <stdlib.h>
2011
2012 #define SERVER "/tmp/serversocket"
2013 #define CLIENT "/tmp/mysocket"
2014 #define MAXMSG 512
2015 #define MESSAGE "Yow!!! Are we having fun yet?!?"
2016
2017 void main (void)
2018 @{
2019   int sock;
2020   char message[MAXMSG];
2021   struct sockaddr_un name;
2022   size_t size;
2023   int nbytes;
2024
2025   /* @r{Make the socket.} */
2026   sock = make_named_socket (CLIENT);
2027
2028   /* @r{Initialize the server socket address.} */
2029   name.sun_family = AF_UNIX;
2030   strcpy (name.sun_path, SERVER);
2031   size = strlen (name.sun_path) + sizeof (name.sun_family);
2032
2033   /* @r{Send the datagram.} */
2034   nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0,
2035                    (struct sockaddr *)&name, size);
2036   if (nbytes < 0) @{
2037     perror ("sendto (client)");
2038     exit (EXIT_FAILURE);
2039   @}
2040
2041   /* @r{Wait for a reply.} */   
2042   nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0);
2043   if (nbytes < 0) @{
2044     perror ("recfrom (client)");
2045     exit (EXIT_FAILURE);
2046   @}
2047
2048   /* @r{Print a diagnostic message.} */
2049   fprintf (stderr, "Client: got message: %s\n", message);
2050
2051   /* @r{Clean up.} */
2052   close (sock);
2053   remove (CLIENT);
2054 @}
2055 @end example
2056
2057 Finally, remember that datagram socket communications are unreliable.
2058 In this example, the client program simply blocks indefinitely if the
2059 message is not delivered to the server; it's left up to the user of the
2060 program to kill it off and restart it interactively, if necessary.  A
2061 better solution would be to use @code{select} (@pxref{Waiting for I/O})
2062 to establish a timeout period for the reply, and either resend the
2063 message or shut down the socket cleanly before exiting if the connection
2064 appears to be dead.
2065
2066
2067 @node Socket Options
2068 @section Socket Options
2069 @cindex socket options
2070
2071 This section describes how you can set or inquire about various options
2072 pertaining to sockets and their underlying communications protocols.
2073
2074 @cindex level, for socket options
2075 @cindex socket option level
2076 When you are manipulating a socket option, you must specify which @dfn{level}
2077 the option pertains to.  This describes whether the option applies to
2078 the socket interface, or to a lower-level communications protocol interface.
2079
2080 @menu
2081 * Socket Option Functions::     The basic functions for setting and getting
2082                                  socket options.
2083 * Socket-Level Options::        Details of the options at the socket level.
2084 @end menu
2085
2086 @node Socket Option Functions
2087 @subsection Socket Option Functions
2088
2089 Here are the functions for inquiring about and modifying socket options.
2090 These functions are declared in @file{sys/socket.h}.
2091 @pindex sys/socket.h
2092
2093 @comment sys/socket.h
2094 @comment BSD
2095 @deftypefun int getsockopt (int @var{filedes}, int @var{level}, int @var{optname}, void *@var{optval}, size_t *@var{optlen_ptr})
2096 The @code{getsockopt} function gets information about the value of
2097 option @var{optname} at level @var{level} for socket @var{filedes}.  The
2098 information is stored at the location pointed at by @var{optval}.  You
2099 should initialize the value at @var{optlen_ptr} to contain the size of
2100 this buffer, and on return it contains the actual number of bytes of
2101 information stored.  Most options interpret the @var{optval} buffer as a
2102 single @code{int} value.
2103
2104 The return value is @code{0} on success and @code{-1} on failure.  The
2105 following @code{errno} error conditions are defined for this function:
2106
2107 @table @code
2108 @item EBADF
2109 The @var{filedes} argument is not a valid file descriptor.
2110
2111 @item ENOTSOCK
2112 The @var{filedes} argument is not a socket.
2113
2114 @item ENOPROTOOPT
2115 The @var{optname} doesn't make sense for the given @var{level}.
2116 @end table
2117 @end deftypefun
2118
2119 @comment sys/socket.h
2120 @comment BSD
2121 @deftypefun int setsockopt (int @var{filedes}, int @var{level}, int @var{optname}, void *@var{optval}, size_t @var{optlen})
2122 This function is used to set the socket option @var{optname} at level
2123 @var{level} for socket @var{filedes}.  The value of the option is passed
2124 in the buffer @var{optval}, which has size @var{optlen}.
2125
2126 The return value and error codes are the same as for @code{getsockopt}.
2127 @end deftypefun
2128
2129
2130 @node Socket-Level Options
2131 @subsection Socket-Level Options
2132
2133 The flags for socket-level options are defined in the header file
2134 @file{sys/socket.h}.
2135 @pindex sys/socket.h
2136
2137 @comment sys/socket.h
2138 @comment BSD
2139 @deftypevr Macro int SOL_SOCKET
2140 You should use this macro as the @var{level} argument to @code{getsockopt}
2141 or @code{setsockopt} to manipulate the socket-level options described
2142 in this section.
2143 @end deftypevr
2144
2145 @comment sys/socket.h
2146 @comment BSD
2147 @deftypevr Macro int SO_DEBUG
2148 This option toggles recording of debugging information in the underlying
2149 protocol modules.  The value is an @code{int}, interpreted as a boolean.
2150 @end deftypevr
2151
2152 @comment sys/socket.h
2153 @comment BSD
2154 @deftypevr Macro int SO_REUSEADDR
2155 This option controls whether @code{bind} should permit reuse of local
2156 addresses for this socket.  The value is an @code{int}, interpreted as a
2157 boolean.
2158 @end deftypevr
2159
2160 @comment sys/socket.h
2161 @comment BSD
2162 @deftypevr Macro int SO_KEEPALIVE
2163 This option controls whether the underlying protocol should periodically
2164 transmit messages on a connected socket.  If the peer fails to respond
2165 to these messages, the connection is considered broken.  The value is an
2166 @code{int}, interpreted as a boolean.
2167 @end deftypevr
2168
2169 @comment sys/socket.h
2170 @comment BSD
2171 @deftypevr Macro int SO_DONTROUTE
2172 This option controls whether outgoing messages bypass the normal message
2173 routing facilities.  If set, messages are sent directly to the network
2174 interface instead.  The value is an @code{int}, interpreted as a boolean.
2175 @end deftypevr
2176
2177 @comment sys/socket.h
2178 @comment BSD
2179 @deftypevr Macro int SO_LINGER
2180 This option specifies what should happen when the socket of a type that
2181 promises reliable delivery still has untransmitted messages when it is
2182 closed; see @ref{Closing a Socket}.  The value is a @code{struct linger}
2183 object.
2184 @end deftypevr
2185
2186 @comment sys/socket.h
2187 @comment BSD
2188 @deftp {struct Type} linger
2189 This data type is used to supply a value for the @code{SO_LINGER} socket
2190 option.  It has the following members:
2191
2192 @table @code
2193 @item int l_onoff
2194 This field is interpreted as a boolean.  If nonzero, @code{close}
2195 blocks until the data is transmitted or the timeout period has expired.
2196
2197 @item int l_linger
2198 This specifies the timeout period, in seconds.
2199 @end table
2200 @end deftp
2201
2202 @comment sys/socket.h
2203 @comment BSD
2204 @deftypevr Macro int SO_BROADCAST
2205 This option controls whether datagrams may be broadcast from the socket.
2206 The value is an @code{int}, interpreted as a boolean.
2207 @end deftypevr
2208
2209 @comment sys/socket.h
2210 @comment BSD
2211 @deftypevr Macro int SO_OOBINLINE
2212 If this option is set, out-of-band data received on the socket is placed
2213 in the normal input queue.  This permits it to be read using @code{read}
2214 or @code{recv} without specifying the @code{MSG_OOB} flag.
2215 @xref{Out-of-Band Data}.  The value is an @code{int}, interpreted as a boolean.
2216 @end deftypevr
2217
2218 @comment sys/socket.h
2219 @comment BSD
2220 @deftypevr Macro int SO_SNDBUF
2221 This option gets or sets the size of the output buffer.  The value is an
2222 @code{int}, which is the size in bytes.
2223 @end deftypevr
2224
2225 @comment sys/socket.h
2226 @comment BSD
2227 @deftypevr Macro int SO_RCVBUF
2228 This option gets or sets the size of the input buffer.  The value is an
2229 @code{int}, which is the size in bytes.
2230 @end deftypevr
2231
2232 @comment sys/socket.h
2233 @comment BSD 
2234 @deftypevr Macro int SO_TYPE
2235 This option can be used with @code{getsockopt} only.  It is used to return
2236 the socket type.  The value is an @code{int}.
2237 @end deftypevr
2238
2239 @comment sys/socket.h
2240 @comment BSD 
2241 @deftypevr Macro int SO_ERROR
2242 This option can be used with @code{getsockopt} only.  It is used to reset
2243 the error status of the socket.  The value is an @code{int}, which represents
2244 the previous error status.
2245 @end deftypevr
2246