Fix dashes.
[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
685 classes---A, B, and C.  The local network address numbers of individual
686 machines are registered with the administrator of the particular
687 network.
688
689 Class A networks have single-byte addresses in the range 0 to 127.
690 There are only a small number of Class A networks, but they can each
691 support a very large number of hosts.  Medium-sized Class B networks
692 have two-byte addresses, with the first byte in the range 128 to 191.
693 Class C networks are the smallest; they have three-byte addresses, with
694 the first byte in the range 192-255.  The remaining bytes of the
695 Internet address specify the local network address number.
696
697 The Class A network 0 is reserved for broadcast to all networks.  In
698 addition, the host number 0 within each network is reserved for broadcast 
699 to all hosts in that network.
700
701 The Class A network 127 is reserved for loopback; you can always use
702 the Internet address @samp{127.0.0.1} to refer to the host machine.
703
704 Since a single machine can be a member of multiple networks, it can have
705 multiple Internet host addresses.  However, there is never more than one
706 machine with the same host address.
707
708 @cindex standard dot notation, for Internet addresses
709 @cindex dot notation, for Internet addresses
710 There are four forms of the @dfn{standard dot notation} for Internet
711 addresses:
712
713 @table @code
714 @item @var{a}.@var{b}.@var{c}.@var{d}
715 This specifies all four bytes of the address individually.
716
717 @item @var{a}.@var{b}.@var{c}
718 The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
719 This is useful for specifying host addresses in a Class B network with
720 network address number @code{@var{a}.@var{b}}.
721
722 @item @var{a}.@var{b}
723 The last part of the address, @var{c}, is interpreted as a 3-byte quantity.
724 This is useful for specifying host addresses in a Class A network with
725 network address number @var{a}.
726
727 @item @var{a}
728 If only one part is given, this corresponds directly to the host address
729 number.
730 @end table
731
732 Within each part of the address, the usual C conventions for specifying
733 the radix apply.  In other words, a leading @samp{0x} or @samp{0X} implies
734 hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
735 radix is assumed.
736
737 The following basic definitions for Internet addresses appear in the
738 header file @file{netinet/in.h}:
739 @pindex netinet/in.h
740
741 @comment netinet/in.h
742 @comment BSD
743 @deftp {struct Type} in_addr
744 This is the data type representing an Internet host address.  You can
745 cast this structure type to a @code{unsigned long int} to get the host address
746 number.
747 @end deftp
748
749 @comment netinet/in.h
750 @comment BSD
751 @deftypevr Macro {unsigned long int} INADDR_ANY
752 This constant can be used to specify the address of the host computer;
753 it is essentially equivalent to saying that any of the host addresses of
754 the machine the program is running on may be used by connection
755 requests.
756 @end deftypevr
757
758 These additional functions for manipulating Internet addresses are
759 declared in @file{arpa/inet.h}:
760 @pindex arpa/inet.h
761
762 @comment arpa/inet.h
763 @comment BSD
764 @deftypefun {unsigned long int} inet_addr (const char *@var{name})
765 This function converts the address @var{name} from the standard dot
766 notation into a host address number.
767 @end deftypefun
768
769 @comment arpa/inet.h
770 @comment BSD
771 @deftypefun {unsigned long int} inet_network (const char *@var{name})
772 This function extracts the network address number from the address 
773 @var{name}, which is given in the standard dot notation.
774 @end deftypefun
775
776 @comment arpa/inet.h
777 @comment BSD
778 @deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
779 This function converts the Internet address @var{addr} to a string in
780 the standard dot notation.  The return value is a pointer into a
781 statically-allocated buffer; this can be overwritten on subsequent calls,
782 so you should copy the data if you need to save it.
783 @end deftypefun
784
785 @comment arpa/inet.h
786 @comment BSD
787 @deftypefun {struct in_addr} inet_makeaddr (int @var{net}, int @var{lna})
788 This function makes an Internet host address by combining the 
789 network number @var{net} with the local network address number @var{lna}.
790 @end deftypefun
791
792 @comment arpa/inet.h
793 @comment BSD
794 @deftypefun int inet_lnaof (struct in_addr @var{addr})
795 This function returns the local network address number part of the Internet
796 host address @var{addr}.
797 @end deftypefun
798
799 @comment arpa/inet.h
800 @comment BSD
801 @deftypefun int inet_netof (struct in_addr @var{addr})
802 This function returns the network address number part of the Internet host
803 address @var{addr}.
804 @end deftypefun
805
806 All of the functions listed in this section represent Internet addresses
807 in network byte order, and network numbers and local network address
808 numbers in host byte order.  @xref{Byte Order Conversion}.
809
810
811 @node Hosts Database
812 @subsection Hosts Database
813 @cindex hosts database
814 @cindex converting host name to address
815 @cindex converting host address to name
816
817 Besides the standard dot notation for Internet addresses, you can also
818 refer to a host by a symbolic name.  The advantage of a symbolic name is
819 that it is usually easier to remember.  For example, the machine with
820 Internet address @samp{128.52.46.32} is also known as
821 @samp{churchy.gnu.ai.mit.edu}; and other machines that belong to the
822 same network can reference it simply as @samp{churchy}.
823
824 @pindex /etc/hosts
825 Internally, the system uses a database to keep track of the mapping
826 between host names and host numbers.  This database is usually either
827 the file @file{/etc/hosts} or an equivalent provided by a name server.
828 The utilities for accessing this database are declared in @file{netdb.h}.
829 @pindex netdb.h
830
831 @comment netdb.h
832 @comment BSD
833 @deftp {struct Type} hostent
834 This data type is used to represent an entry in the hosts database.  It
835 has the following members:
836
837 @table @code
838 @item char *h_name
839 This is the ``official'' name of the host.
840
841 @item char **h_aliases
842 These are alternative names for the host, represented as a null-terminated
843 vector of strings.
844
845 @item int h_addrtype
846 This is the host address type; its value is always @code{AF_INET}.
847 @xref{Socket Naming}.
848
849 @item int h_length
850 This is the length, in bytes, of each address.
851
852 @item char **h_addr_list
853 This is the vector of addresses for the host.  (Recall that the host
854 might be connected to multiple networks and have different addresses on
855 each one.)  The vector is terminated by a null pointer.
856
857 @item char *h_addr
858 This is a synonym for @code{h_addr_list[0]}; in other words, it is the
859 first host address.
860 @end table
861 @end deftp
862
863 As far as the host database is concerned, each address is just a block
864 of memory @code{h_length} bytes long.  But in other contexts there is an
865 implicit assumption that you can cast this to a @code{struct in_addr} or
866 a @code{unsigned long int}.  Host addresses in a @code{struct hostent}
867 structure are always given in network byte order; see @ref{Byte Order
868 Conversion}.
869
870 You can use @code{gethostbyname} or @code{gethostbyaddr} to search the
871 hosts database for information about a particular host.  The information
872 is returned in a statically-allocated structure; you must copy the
873 information if you need to save it across calls.
874
875 @comment netdb.h
876 @comment BSD
877 @deftypefun {struct hostent *} gethostbyname (const char *@var{name})
878 The @code{gethostbyname} function returns information about the host
879 named @var{name}.  If the lookup fails, a null pointer is returned.
880 @end deftypefun
881
882 @comment netdb.h
883 @comment BSD
884 @deftypefun {struct hostent *} gethostbyaddr (const char *@var{addr}, int @var{length}, int @var{type})
885 The @code{gethostbyaddr} function returns information about the host
886 with Internet address @var{addr}.  The @var{length} argument is the size
887 (in bytes) of the @var{addr}.  The @var{type} is the type of the
888 address; for an Internet address, specify a value of @code{AF_INET}.
889
890 If the lookup fails, a null pointer is returned.
891 @end deftypefun
892
893 @vindex h_errno
894 If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
895 fails, you can get more information about the specific error code by
896 looking at the value of the variable @code{h_errno}.  If your program
897 uses this variable, you need to declare it like this:
898
899 @example
900 extern int h_errno;
901 @end example
902
903 The value of @code{h_errno} can be one of the following symbolic constants:
904
905 @comment netdb.h
906 @comment BSD
907 @deftypevr Macro int HOST_NOT_FOUND
908 No such host is known.
909 @end deftypevr
910
911 @comment netdb.h
912 @comment BSD
913 @deftypevr Macro int TRY_AGAIN
914 This condition happens when the name server could not be contacted.
915 If you trying again later, the request may succeed.
916 @end deftypevr
917
918 @comment netdb.h
919 @comment BSD 
920 @deftypevr Macro int NO_RECOVERY 
921 A non-recoverable error occurred.
922 @end deftypevr
923
924 @comment netdb.h
925 @comment BSD
926 @deftypevr Macro int NO_ADDRESS
927 The host database contains an entry for the name, but it doesn't have an
928 associated Internet address.
929 @end deftypevr
930
931 @strong{Incomplete:} Is there some similar error-reporting mechanism
932 for the other server-based databases?  
933
934 You can also scan the hosts database using @code{sethostent},
935 @code{gethostent}, and @code{endhostent}.
936
937 @comment netdb.h
938 @comment BSD
939 @deftypefun void sethostent (int @var{stayopen})
940 This function opens and rewinds the hosts database.  If the
941 @var{stayopen} argument is true, the database stays open after calls to
942 @code{gethostbyname} or @code{gethostbyaddr}.
943 @end deftypefun
944
945 @comment netdb.h
946 @comment BSD
947 @deftypefun {struct hostent *} gethostent (void)
948 This function returns the next entry in the hosts database.  A null
949 pointer is returned if there are no more entries.
950 @end deftypefun
951
952 @comment netdb.h
953 @comment BSD
954 @deftypefun void endhostent (void)
955 This function closes the hosts database.
956 @end deftypefun
957
958
959 @node Services Database
960 @subsection Services Database
961 @cindex services database
962 @cindex converting service name to port number
963 @cindex converting port number to service name
964
965 Once you have figured out the address of the host you wish to talk to,
966 the next step is to figure out which specific port on that machine to
967 use.
968
969 Port numbers less than 1024 are reserved for ``well-known'' services, or
970 system daemons such as the servers for @code{finger} and @code{telnet}.
971 Again, there is a database that keeps track of these, and you can use
972 the @code{getservbyname} function to map a service name onto a port
973 number.
974
975 Typically, only privileged system-level processes that are run
976 automatically are registered in the services database.  If you are
977 writing your own user-level server, you can simply choose an arbitrary
978 port number greater than or equal to 1024 for it to accept connections
979 on.
980
981 There aren't any built-in protection mechanisms for controlling
982 access to ports.  If you want to restrict access to your server, you
983 should have it examine the addresses associated with connection requests
984 or implement some other handshaking or identification protocol.
985
986 @pindex /etc/services
987 The database that keeps track of ``well-known'' services is usually
988 either the file @file{/etc/services} or an equivalent from a name server.
989 You can use these utilities, declared in @file{netdb.h}, to access
990 the services database.
991 @pindex netdb.h
992
993 @comment netdb.h
994 @comment BSD
995 @deftp {struct Type} servent
996 This data type holds information about entries from the services database.
997 It has the following members:
998
999 @table @code
1000 @item char *s_name
1001 This is the ``official'' name of the service.
1002
1003 @item char **s_aliases
1004 These are alternate names for the service, represented as an array of
1005 strings.  A null pointer terminates the array.
1006
1007 @item int s_port
1008 This is the port number for the service.  Port numbers are given in
1009 network byte order; see @ref{Byte Order Conversion}.
1010
1011 @item char *s_proto
1012 This is the name of the protocol to use with this service.
1013 @xref{Protocols Database}.
1014 @end table
1015 @end deftp
1016
1017 To get information about a particular service, use the
1018 @code{getservbyname} or @code{getservbyport} functions.  The information
1019 is returned in a statically-allocated structure; you must copy the
1020 information if you need to save it across calls.
1021
1022 @comment netdb.h
1023 @comment BSD
1024 @deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto})
1025 The @code{getservbyname} function returns information about the service
1026 named @var{name} using protocol @var{proto}.  If the lookup fails, a
1027 null pointer is returned.
1028 @end deftypefun
1029
1030 @comment netdb.h
1031 @comment BSD
1032 @deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto})
1033 The @code{getservbyport} function returns information about the service
1034 at port @var{port} using protocol @var{proto}.  If the lookup fails, a
1035 null pointer is returned.
1036 @end deftypefun
1037
1038 You can also scan the services database using @code{setservent},
1039 @code{getservent}, and @code{endservent}.
1040
1041 @comment netdb.h
1042 @comment BSD
1043 @deftypefun void setservent (int @var{stayopen})
1044 This function opens and rewinds the services database.  If the
1045 @var{stayopen} argument is true, the database stays open after calls to
1046 @code{getservbyname} or @code{getservbyport}.
1047 @end deftypefun
1048
1049 @comment netdb.h
1050 @comment BSD
1051 @deftypefun {struct servent *} getservent (void)
1052 This function returns the next entry in the services database.  A null
1053 pointer is returned if there are no more entries.
1054 @end deftypefun
1055
1056 @comment netdb.h
1057 @comment BSD
1058 @deftypefun void endservent (void)
1059 This function closes the services database.
1060 @end deftypefun
1061
1062
1063 @node Networks Database
1064 @subsection Networks Database
1065 @cindex networks database
1066 @cindex converting network number to network name
1067 @cindex converting network name to network number
1068
1069 @pindex /etc/networks
1070 There is also a database that keeps track of all the known networks.
1071 This is usually either the file @file{/etc/networks} or an equivalent
1072 from a name server.  
1073
1074 The following utilities for accessing the networks database are declared
1075 in @file{netdb.h}.  You usually don't have to worry about the networks
1076 database to write a program that uses sockets; the information is
1077 presented here for completeness only.
1078 @pindex netdb.h
1079
1080 @comment netdb.h
1081 @comment BSD
1082 @deftp {struct Type} netent
1083 This data type is used to represent information about entries in the
1084 networks database.  It has the following members:
1085
1086 @table @code
1087 @item char *n_name
1088 This is the ``official'' name of the network.
1089
1090 @item char **n_aliases
1091 These are alternative names for the network, represented as a vector
1092 of strings.  A null pointer terminates the array.
1093
1094 @item int n_addrtype
1095 This is the type of the network number; this is always equal to
1096 @code{AF_INET} for Internet networks.
1097
1098 @item unsigned long int n_net
1099 This is the network number.  Network numbers are returned in host
1100 byte order; see @ref{Byte Order Conversion}.
1101 @end table
1102 @end deftp
1103
1104 Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search
1105 the networks database for information about a specific network.  The
1106 information is returned in a statically-allocated structure; you must
1107 copy the information if you need to save it.
1108
1109 @comment netdb.h
1110 @comment BSD
1111 @deftypefun {struct netent *} getnetbyname (const char *@var{name})
1112 The @code{getnetbyname} function returns information about the network
1113 named @var{name}.  If the lookup fails, a null pointer is returned.
1114 @end deftypefun
1115
1116 @comment netdb.h
1117 @comment BSD
1118 @deftypefun {struct netent *} getnetbyaddr (long @var{net}, int @var{type})
1119 The @code{getnetbyaddr} function returns information about the network
1120 of type @var{type} with number @var{net}.  You should specify a value of
1121 @code{AF_INET} for the @var{type} argument for Internet networks.  
1122
1123 If the lookup fails, a null pointer is returned.
1124 @end deftypefun
1125
1126 You can also scan the networks database using @code{setnetent},
1127 @code{getnetent}, and @code{endnetent}.
1128
1129 @comment netdb.h
1130 @comment BSD
1131 @deftypefun void setnetent (int @var{stayopen})
1132 This function opens and rewinds the networks database.  If the
1133 @var{stayopen} argument is true, the database stays open after calls to
1134 @code{getnetbyname} or @code{getnetbyaddr}.
1135 @end deftypefun
1136
1137 @comment netdb.h
1138 @comment BSD
1139 @deftypefun {struct netent *} getnetent (void)
1140 This function returns the next entry in the networks database.  A null
1141 pointer is returned if there are no more entries.
1142 @end deftypefun
1143
1144 @comment netdb.h
1145 @comment BSD
1146 @deftypefun void endnetent (void)
1147 This function closes the networks database.
1148 @end deftypefun
1149
1150
1151 @node Byte Order Conversion
1152 @subsection Byte Order Conversion
1153 @cindex byte order conversion, for socket
1154 @cindex converting byte order
1155
1156 @cindex network byte order
1157 Finally, there is one more wrinkle: the byte ordering of the data in the
1158 @code{sin_port} and @code{sin_addr} members of the @code{sockaddr_in}
1159 structure must be canonicalized into the @dfn{network byte order}.  This
1160 ensures that machines that use different native byte ordering conventions
1161 can still talk to each other.  If you don't do this, your program may fail
1162 when running on or talking to other kinds of machines.
1163
1164 If you use @code{getservbyname} and @code{gethostbyname} or
1165 @code{inet_addr} to get the port number and host address, the values are
1166 already in the network byte order, and you can copy them directly into
1167 the @code{sockaddr_in} structure.
1168
1169 Otherwise, you have to convert the values explicitly.  Use
1170 @code{htons} and @code{ntohs} to convert values for the @code{sin_port}
1171 member.  Use @code{htonl} and @code{ntohl} to convert values for the
1172 @code{sin_addr} member.  (Remember, @code{struct in_addr} is equivalent
1173 to @code{unsigned long int}.)  These functions are declared in
1174 @file{netinet/in.h}.
1175 @pindex netinet/in.h
1176
1177 @comment netinet/in.h
1178 @comment BSD
1179 @deftypefun {unsigned short int} htons (unsigned short int @var{hostshort})
1180 This function converts the @code{short} integer @var{hostshort} from
1181 host byte order to network byte order.
1182 @end deftypefun
1183
1184 @comment netinet/in.h
1185 @comment BSD
1186 @deftypefun {unsigned short int} ntohs (unsigned short int @var{netshort})
1187 This function converts the @code{short} integer @var{netshort} from
1188 network byte order to host byte order.
1189 @end deftypefun
1190
1191 @comment netinet/in.h
1192 @comment BSD
1193 @deftypefun {unsigned long int} htonl (unsigned long int @var{hostlong})
1194 This function converts the @code{long} integer @var{hostlong} from
1195 host byte order to network byte order.
1196 @end deftypefun
1197
1198 @comment netinet/in.h
1199 @comment BSD
1200 @deftypefun {unsigned long int} ntohl (unsigned long int @var{netlong})
1201 This function converts the @code{long} integer @var{netlong} from
1202 network byte order to host byte order.
1203 @end deftypefun
1204
1205 @node Internet Socket Example
1206 @subsection Internet Socket Example
1207
1208 Here is an example showing how to create and name a socket in the
1209 Internet domain.  Since the newly created socket exists on the local
1210 machine that the program is running on, this example uses @code{INADDR_ANY}
1211 as the host address.
1212
1213 @comment This example is from isockserver.c.
1214 @example
1215 #include <sys/socket.h>
1216 #include <netdb.h>
1217 #include <netinet/in.h>
1218 #include <sys/types.h>
1219 #include <stdio.h>
1220 #include <errno.h>
1221 #include <stdlib.h>
1222
1223 int make_socket (unsigned short int port)
1224 @{
1225   int sock, status;
1226   struct sockaddr_in name;
1227   unsigned long int addr;
1228
1229   /* @r{Create the socket.} */
1230   sock = socket (PF_INET, SOCK_STREAM, 0);
1231   if (sock < 0) @{
1232     perror ("socket");
1233     exit (EXIT_FAILURE);
1234   @}
1235
1236   /* @r{Give the socket a name.} */
1237   name.sin_family = AF_INET;
1238   name.sin_port = htons (port);
1239   addr = htonl (INADDR_ANY);
1240   memcpy (&name.sin_addr, &addr, sizeof (addr));
1241   status = bind (sock, (struct sockaddr *)&name, sizeof (name));
1242   if (status < 0) @{
1243     perror ("bind");
1244     exit (EXIT_FAILURE);
1245   @}
1246
1247   return sock;
1248 @}
1249 @end example
1250
1251 Here is another example, showing how you can fill in a @code{sockaddr_in}
1252 structure, given a host name string and a port number:
1253
1254 @comment This example is from isockclient.c.
1255 @example
1256 void init_sockaddr (struct sockaddr_in *name, const char *hostname,
1257                     unsigned short int port)
1258 @{
1259   struct hostent *hostinfo;
1260
1261   name->sin_family = AF_INET;
1262   name->sin_port = htons (PORT);
1263   hostinfo = gethostbyname (SERVERHOST);
1264   if (!hostinfo) @{
1265     fprintf (stderr, "Unknown host %s.\n", SERVERHOST);
1266     exit (EXIT_FAILURE);
1267   @}
1268   memcpy (&name->sin_addr, hostinfo->h_addr, sizeof (unsigned long int));
1269 @}
1270 @end example
1271
1272
1273 @node Types of Sockets
1274 @section Types of Sockets
1275
1276 The GNU library includes support for several different kinds of sockets,
1277 each with different characteristics.  This section describes the
1278 supported socket types.  The symbolic constants listed here are
1279 defined in @file{sys/socket.h}.
1280 @pindex sys/socket.h
1281
1282 Each socket type has a number of attributes that characterize it.
1283
1284 @itemize @bullet
1285 @cindex datagram
1286 @item
1287 Data may be organized as a byte stream, or as a @dfn{datagram} or
1288 message packet.  In the latter case, record boundaries between
1289 messages are preserved.
1290
1291 @item
1292 The socket may maintain a connection to one particular peer socket, or
1293 messages may be addressed individually.
1294
1295 @item
1296 Lost messages or messages received with errors may be retransmitted
1297 automatically, or simply ignored.  
1298
1299 @item
1300 Messages may be guaranteed to arrive in sequence, or permitted to
1301 arrive out of order or be duplicated.
1302 @end itemize
1303
1304 @comment sys/socket.h
1305 @comment BSD
1306 @deftypevr Macro int SOCK_STREAM
1307 The @code{SOCK_STREAM} socket type is similar to a pipe; it provides
1308 a byte stream based communications channel with connection state
1309 and reliable, sequential transmission of messages.
1310
1311 Operations on this type of stream are covered in detail in @ref{Byte
1312 Stream Socket Operations}.
1313 @end deftypevr
1314
1315 @comment sys/socket.h
1316 @comment BSD
1317 @deftypevr Macro int SOCK_DGRAM
1318 The @code{SOCK_DGRAM} socket type is used for sending individually-addressed
1319 datagrams.  This kind of socket does not guarantee reliable or sequential
1320 transmission of messages.  It is typically used in situations where
1321 it is acceptible to simply resend the message if no response is seen
1322 in a reasonable amount of time.
1323
1324 @ref{Datagram Socket Operations}, contains detailed information about
1325 how to use sockets of this type.
1326 @end deftypevr
1327
1328 @comment sys/socket.h
1329 @comment BSD
1330 @deftypevr Macro int SOCK_SEQPACKET
1331 This socket type is similar to @code{SOCK_STREAM}, except that messages
1332 are sent by datagrams rather than as bytes.  This socket type may not
1333 be supported by all protocols.
1334 @end deftypevr
1335
1336 @comment sys/socket.h
1337 @comment BSD
1338 @deftypevr Macro int SOCK_RDM
1339 This socket type is similar to @code{SOCK_DGRAM}, except that reliable
1340 delivery of datagrams is guaranteed.  This socket type may not be
1341 supported by all protocols.
1342 @end deftypevr
1343
1344 @comment sys/socket.h
1345 @comment BSD
1346 @deftypevr Macro int SOCK_RAW
1347 This socket type provides access to internal network protocols and
1348 interfaces.  Ordinary user programs usually have no need to use this
1349 socket type.
1350 @end deftypevr
1351
1352
1353 @node Byte Stream Socket Operations
1354 @section Byte Stream Socket Operations
1355 @cindex byte stream socket
1356
1357 This section describes operations on sockets that have connection state, 
1358 such as @code{SOCK_STREAM} sockets.
1359
1360 @iftex
1361 @itemize @bullet
1362 @item
1363 @ref{Establishing a Connection}, describes how two processes establish a
1364 connection.
1365
1366 @item
1367 @ref{Transferring Data}, describes how data is transferred through the
1368 connected socket.
1369 @end itemize
1370 @end iftex
1371
1372 @menu
1373 * Establishing a Connection::   The socket must be connected before it
1374                                  can transmit data.
1375 * Transferring Data::           How to send and receive data.
1376 * Byte Stream Socket Example::  An example program.
1377 * Out-of-Band Data::            This is an advanced feature.
1378 @end menu
1379
1380 @node Establishing a Connection
1381 @subsection Establishing a Connection
1382 @cindex connecting a socket
1383 @cindex socket, connecting
1384
1385 Before two processes can exchange data through a socket, they must
1386 establish a connection.  One process acts as a server and waits
1387 for a connection by calling the @code{listen} and @code{accept}
1388 function; the other process acts as the client and initiates the
1389 connection by calling the @code{connect} function.
1390
1391 @comment sys/socket.h
1392 @comment BSD
1393 @deftypefun int connect (int @var{filedes}, struct sockaddr *@var{addr}, size_t @var{length})
1394 The @code{connect} function initiates a connection from the socket with
1395 file descriptor @var{filedes} to the socket whose address is specified
1396 by the @var{addr} and @var{length} arguments.  @xref{Socket Naming}, for
1397 information about how these arguments are interpreted.
1398
1399 The normal return value from @code{connect} is @code{0}.  If an error
1400 occurs, @code{connect} returns @code{-1}.  The following @code{errno}
1401 error conditions are defined for this function:
1402
1403 @table @code
1404 @item EBADF
1405 The @var{filedes} is not a valid file descriptor.
1406
1407 @item ENOTSOCK
1408 The @var{filedes} is not a socket.
1409
1410 @item EADDRNOTAVAIL
1411 The specified address is not available on this machine.
1412
1413 @item EAFNOSUPPORT
1414 The address family of the @var{addr} is not supported by this socket.
1415
1416 @item EISCONN
1417 The socket is already connected.
1418
1419 @item ETIMEDOUT
1420 The attempt to establish the connection timed out.
1421
1422 @item ECONNREFUSED
1423 The attempt to establish the connection was actively refused by the peer.
1424
1425 @item ENETUNREACH
1426 The network isn't reachable from this host.
1427
1428 @item EADDRINUSE
1429 The socket address is already in use.
1430
1431 @item EINPROGRESS
1432 The socket is non-blocking and the connection could not be established
1433 immediately.
1434
1435 @item EALREADY
1436 The socket is non-blocking and already has a pending connection in progress.
1437 @end table
1438 @end deftypefun
1439
1440 @comment sys/socket.h
1441 @comment BSD
1442 @deftypefun int listen (int @var{filedes}, unsigned int @var{n})
1443 The @code{listen} function specifies that the socket @var{filedes} is
1444 willing to accept connections.  
1445
1446 The argument @var{n} specifies the length of the queue for pending
1447 connections.  If more than this many connection requests arrive without
1448 actually being accepted via a call to @code{accept}, additional
1449 @code{connect} requests to this socket are either refused with a
1450 @code{ECONNREFUSED} error or retransmitted (depending on the particular
1451 socket protocol).  The system may also impose its own internal limit on
1452 the length of this queue.
1453
1454 The @code{listen} function returns @code{0} on success and @code{-1}
1455 on failure.  The following @code{errno} error conditions are defined
1456 for this function:
1457
1458 @table @code
1459 @item EBADF
1460 The argument @var{filedes} is not a valid file descriptor.
1461
1462 @item ENOTSOCK
1463 The argument @var{filedes} is not a socket.
1464
1465 @item EOPNOTSUPP
1466 The socket @var{filedes} does not support this operation.
1467 @end table
1468 @end deftypefun
1469
1470 @comment sys/socket.h
1471 @comment BSD
1472 @deftypefun int accept (int @var{filedes}, struct sockaddr *@var{addr}, size_t *@var{length_ptr})
1473 This function is used to accept a connection to the socket @var{filedes}.
1474 You must first call @code{listen} on this socket to enable connections to
1475 be made.
1476
1477 The @code{accept} function blocks the calling process if there
1478 are no connections pending, unless the socket @var{filedes} has
1479 nonblocking mode set.  @xref{File Status Flags}.
1480
1481 The @var{sockaddr} and @var{length_ptr} arguments are used to return
1482 information about the name of the peer socket that initiated the
1483 connection.  @xref{Socket Naming}, for information about the format of
1484 the information.
1485
1486 The normal return value from @code{accept} is a newly allocated file
1487 descriptor that refers to the connection; you should use this file
1488 descriptor for transferring data.  The original socket @var{filedes}
1489 remains open, and you can pass it to @code{accept} again to make further
1490 connections.
1491
1492 If an error occurs, @code{accept} returns @code{-1}.  The following
1493 @code{errno} error conditions are defined for this function:
1494
1495 @table @code
1496 @item EBADF
1497 The @var{filedes} argument is not a valid file descriptor.
1498
1499 @item ENOTSOCK
1500 The @var{filedes} argument is not a socket.
1501
1502 @item EOPNOTSUPP
1503 The @var{filedes} does not support this operation.
1504
1505 @item EWOULDBLOCK
1506 The @var{filedes} has nonblocking mode set, and there are no pending
1507 connections immediately available.
1508 @end table
1509 @end deftypefun
1510
1511 @comment sys/socket.h
1512 @comment BSD
1513 @deftypefun int getpeername (int @var{filedes}, struct sockaddr *@var{addr}, size_t *@var{length_ptr})
1514 The @code{getpeername} function returns the address of the peer
1515 connected to the socket @var{filedes} in the locations pointed at by the
1516 @var{addr} and @var{length_ptr} arguments.  @xref{Socket Naming}, for
1517 information about the format of this information.
1518
1519 The return value is @code{0} on success and @code{-1} on error.  The
1520 following @code{errno} error conditions are defined for this function:
1521
1522 @table @code
1523 @item EBADF
1524 The argument @var{filedes} is not a valid file descriptor.
1525
1526 @item ENOTSOCK
1527 The argument @var{filedes} is not a socket.
1528
1529 @item ENOTCONN
1530 The socket @var{filedes} is not connected.
1531
1532 @item ENOBUFS
1533 There are not enough internal buffers available.
1534 @end table
1535 @end deftypefun
1536
1537
1538 @node Transferring Data
1539 @subsection Transferring Data
1540 @cindex reading from a socket
1541 @cindex writing to a socket
1542
1543 Once a socket has been connected to a peer, you can use the ordinary
1544 @code{read} and @code{write} operations (@pxref{I/O Primitives}) to
1545 transfer data.  A socket is a two-way communications channel, so read
1546 and write operations can be performed at either end.
1547
1548 You can also use the @code{send} and @code{recv} functions to perform
1549 read and write operations while specifying additional flags.  The
1550 prototypes for these functions are in the header file
1551 @file{sys/socket.h}.
1552 @pindex sys/socket.h
1553
1554 @comment sys/socket.h
1555 @comment BSD
1556 @deftypefun int send (int @var{filedes}, void *@var{buffer}, size_t @var{size}, int @var{flags})
1557 The @code{send} function is like @code{write}, but with the additional
1558 flags @var{flags}.  The possible values of the @var{flags} are described
1559 below.
1560
1561 This function returns the number of bytes transmitted, or @code{-1} on
1562 failure.  Note, however, that a successful return value merely indicates
1563 that the message has been sent without error, not necessarily that it
1564 has been received without error.
1565
1566 The following @code{errno} error conditions are defined for this function:
1567
1568 @table @code
1569 @item EBADF
1570 The @var{filedes} argument is not a valid file descriptor.
1571
1572 @item ENOTSOCK
1573 The @var{filedes} argument is not a socket.
1574
1575 @item EMSGSIZE
1576 The socket type requires that the message be sent atomically, but the
1577 message is too large for this to be possible.
1578
1579 @item EWOULDBLOCK
1580 Nonblocking mode has been set on the socket, and the write operation
1581 would block.  (Normally @code{send} blocks until the operation can be
1582 completed.)
1583
1584 @item ENOBUFS
1585 There is not enough internal buffer space available.
1586 @end table
1587 @end deftypefun
1588
1589 @comment sys/socket.h
1590 @comment BSD
1591 @deftypefun int recv (int @var{filedes}, void *@var{buffer}, size_t @var{size}, int @var{flags})
1592 The @code{recv} function is like @code{read}, but with the additional
1593 flags @var{flags}.  The possible values of the @var{flags} are described
1594 below.
1595
1596 This function returns the number of bytes received, or @code{-1} on failure.
1597 The following @code{errno} error conditions are defined for this function:
1598
1599 @table @code
1600 @item EBADF
1601 The @var{filedes} argument is not a valid file descriptor.
1602
1603 @item ENOTSOCK
1604 The @var{filedes} argument is not a socket.
1605
1606 @item EWOULDBLOCK
1607 Nonblocking mode has been set on the socket, and the read operation
1608 would block.  (Normally, @code{recv} blocks until there is input available
1609 to be read.)
1610
1611 @item EINTR
1612 The operation was interrupted by a signal before any data was read.
1613 @end table
1614 @end deftypefun
1615
1616 The @var{flags} argument to these functions is a bit mask.  You can
1617 bitwise-OR the values of the following macros together to obtain a
1618 value for this argument.
1619
1620 @comment sys/socket.h
1621 @comment BSD
1622 @deftypevr Macro int MSG_OOB
1623 Send or receive out-of-band data.  @xref{Out-of-Band Data}.
1624 @end deftypevr
1625
1626 @comment sys/socket.h
1627 @comment BSD
1628 @deftypevr Macro int MSG_PEEK
1629 Look at the data but don't remove it from the input queue.  This is
1630 only useful on read operations.
1631 @end deftypevr
1632
1633 @comment sys/socket.h
1634 @comment BSD
1635 @deftypevr Macro int MSG_DONTROUTE
1636 Don't include routing information in the message.  This is only useful
1637 on write operations, and is generally only of interest for diagnostic or
1638 routing programs.
1639 @end deftypevr
1640
1641 @node Byte Stream Socket Example
1642 @subsection Byte Stream Socket Example
1643
1644 Here are a set of example programs that show communications over a 
1645 byte stream socket in the Internet domain.  These programs use the
1646 @code{make_socket} and @code{init_sockaddr} functions that were presented
1647 in @ref{Internet Socket Example} to set up the socket names.
1648
1649 First, here is the client program.  It doesn't do anything particularly
1650 interesting once it has connected to the server; it just sends a message
1651 to the server and exits.
1652
1653 @comment This example is from isockclient.c.
1654 @example
1655 #include <sys/socket.h>
1656 #include <netdb.h>
1657 #include <netinet/in.h>
1658 #include <sys/types.h>
1659 #include <stdio.h>
1660 #include <errno.h>
1661 #include <stdlib.h>
1662
1663
1664 #define PORT 2222
1665 #define MESSAGE "Yow!!! Are we having fun yet?!?"
1666 #define SERVERHOST "churchy.gnu.ai.mit.edu"
1667
1668
1669 void write_to_server (int filedes)
1670 @{
1671   int nbytes;
1672
1673   nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1);
1674   if (nbytes < 0) @{
1675     perror ("write");
1676     exit (EXIT_FAILURE);
1677   @}
1678 @}
1679
1680
1681 void main (void)
1682 @{
1683   int sock;
1684   int status;
1685   struct sockaddr_in servername;
1686
1687   /* @r{Create the socket.}  */
1688   sock = socket (PF_INET, SOCK_STREAM, 0);
1689   if (sock < 0) @{
1690     perror ("socket (client)");
1691     exit (EXIT_FAILURE);
1692   @}
1693
1694   /* @r{Connect to the server.}  */
1695   init_sockaddr (&servername, SERVERHOST, PORT);
1696   status = connect (sock, (struct sockaddr *) &servername,
1697                     sizeof (servername));
1698   if (status < 0) @{
1699     perror ("connect (client)");
1700     exit (EXIT_FAILURE);
1701   @}
1702
1703   /* @r{Send data to the server.} */
1704   write_to_server (sock);
1705   close (sock);
1706   exit (EXIT_SUCCESS);
1707 @}
1708 @end example
1709
1710 The server end is much more complicated.  Since we want to allow
1711 multiple clients to be connected to the server at the same time, it
1712 would be incorrect to wait for input from a single client by simply
1713 calling @code{read} or @code{recv}.  Instead, the right thing to do is
1714 to use @code{select} (described in @ref{Waiting for I/O}) to wait for
1715 input on all of the open sockets.  This also allows the server to deal
1716 with additional connection requests.
1717
1718 Again, this particular program doesn't do anything very exciting once it
1719 has gotten a message from a client.  It does close the socket for that
1720 client when it detects and end-of-file condition (resulting from the
1721 client shutting down its end of the connection).
1722
1723 @comment This example is isockserver.c.
1724 @example
1725 #include <sys/socket.h>
1726 #include <netdb.h>
1727 #include <netinet/in.h>
1728 #include <sys/types.h>
1729 #include <stdio.h>
1730 #include <errno.h>
1731 #include <stdlib.h>
1732
1733 #define PORT 2222
1734 #define MAXMSG 512
1735
1736 int read_from_client (int filedes)
1737 @{
1738   char buffer[MAXMSG];
1739   int nbytes;
1740
1741   nbytes = read (filedes, buffer, MAXMSG);
1742   if (nbytes < 0) @{
1743     /* Read error. */
1744     perror ("read");
1745     exit (EXIT_FAILURE);
1746   @}
1747   else if (nbytes == 0) @{
1748     /* End-of-file. */
1749     return -1;
1750   @}
1751   else @{
1752     /* Data read. */
1753     fprintf (stderr, "Server:  got message: %s\n", buffer);
1754     return 0;
1755   @}
1756 @}
1757
1758
1759 void main (void)
1760 @{
1761   int sock;
1762   int status;
1763   fd_set active_fd_set, read_fd_set;
1764   int i;
1765   struct sockaddr_in clientname;
1766   size_t size;
1767
1768   /* @r{Create the socket and set it up to accept connections.} */
1769   sock = make_socket (PORT);
1770   status = listen (sock, 1);
1771   if (status < 0) @{
1772     perror ("listen");
1773     exit (EXIT_FAILURE);
1774   @}
1775
1776   /* @r{Initialize the set of active sockets.} */
1777   FD_ZERO (&active_fd_set);
1778   FD_SET (sock, &active_fd_set);
1779
1780   while (1) @{
1781     /* @r{Block until input arrives on one or more active sockets.} */
1782     memcpy (&read_fd_set, &active_fd_set, sizeof (active_fd_set));
1783     status = select (FD_SETSIZE, &read_fd_set, NULL, NULL, NULL);
1784     if (status < 0) @{
1785       perror ("select");
1786       exit (EXIT_FAILURE);
1787     @}
1788     /* @r{Service all the sockets with input pending.} */
1789     for (i=0; i<FD_SETSIZE; i++)  @{
1790       if (FD_ISSET (i, &read_fd_set)) @{
1791
1792         /* @r{Connection request on original socket.} */
1793         if (i == sock) @{
1794           size = sizeof (clientname);
1795           status = accept (sock, (struct sockaddr *)&clientname, &size);
1796           if (status < 0) @{
1797             perror ("accept");
1798             exit (EXIT_FAILURE);
1799           @}
1800           fprintf (stderr, "Server: connection from host %s, port %d.\n",
1801                    inet_ntoa (clientname.sin_addr),
1802                    ntohs (clientname.sin_port));
1803           FD_SET (status, &active_fd_set);
1804         @}
1805
1806         /* @r{Data arriving on an already-connected socket.} */
1807         else @{
1808           if (read_from_client (i) < 0) @{
1809             close (i);
1810             FD_CLR (i, &active_fd_set);
1811           @}
1812         @}
1813       @}
1814     @}
1815   @}
1816 @}
1817 @end example
1818
1819
1820 @node Out-of-Band Data
1821 @subsection Out-of-Band Data
1822
1823 @cindex out-of-band data
1824 @cindex urgent socket condition
1825 Streams of type @code{SOCK_STREAM} support the concept of
1826 @dfn{out-of-band} data that is transmitted in a channel in parallel with
1827 that used for ordinary data transmission.  Out-of-band data is typically
1828 used to flag exceptional conditions.
1829
1830 When out-of-band data is pending on a socket, a @code{SIGURG} signal is
1831 sent to the owner process or process group of the socket.  You establish
1832 this using the @code{F_SETOWN} command to the @code{fcntl} function;
1833 see @ref{Interrupt Input}.  You can establish a handler for this signal,
1834 as described in @ref{Signal Handling}.
1835
1836 Alternatively, you can get synchronous notification of pending
1837 out-of-band data by using the @code{select} function to wait for an
1838 exceptional condition on the socket.  @xref{Waiting for I/O}, for more
1839 information about @code{select}.
1840
1841 Receiving a @code{SIGURG} signal only means that out-of-band data is
1842 pending, not that it has arrived.  If you try to read the out-of-band
1843 data with @code{recv} when it has not yet arrived, it fails with a
1844 @code{EWOULDBLOCK} error.  You may even need to read some of the in-band
1845 data to empty out internal buffers before the out-of-band data can be
1846 delivered.
1847
1848
1849 @node Datagram Socket Operations
1850 @section Datagram Socket Operations
1851 @cindex datagram socket
1852 This section describes functions for sending messages on datagram
1853 sockets (type @code{SOCK_DGRAM}).  Unlike the byte stream sockets
1854 discussed in @ref{Byte Stream Socket Operations}, these sockets do
1855 not support any notion of connection state.  Instead, each message
1856 is addressed individually.
1857
1858 The @code{listen} and @code{accept} functions cannot be used on datagram
1859 sockets.  You can call @code{connect} on a datagram socket, but this
1860 only affects the local state of the socket.  It remembers the specified
1861 address as the default for any further data transmission on the socket.
1862 You can remove the connection by calling @code{connect} again and
1863 specifying an address family of @code{AF_UNSPEC} in the @var{addr}
1864 argument.  @xref{Establishing a Connection}, for more information about
1865 the @code{connect} function.
1866
1867 @menu
1868 * Transmitting Datagrams::      Functions for sending and receiving messages
1869                                  on a datagram socket.
1870 * Datagram Socket Example::     An example program.
1871 @end menu
1872
1873 @node Transmitting Datagrams
1874 @subsection Transmitting Datagrams
1875 @cindex sending a datagram
1876 @cindex receiving a datagram
1877 @cindex transmitting datagrams
1878 @cindex datagrams, transmitting
1879
1880 The normal way of sending data on an unconnected datagram socket is
1881 by using the @code{sendto} function.  The @code{recvfrom} function 
1882 reads data from an unconnected datagram socket.  Both of these functions
1883 are declared in @file{sys/socket.h}.
1884 @pindex sys/socket.h
1885
1886 @comment sys/socket.h
1887 @comment BSD
1888 @deftypefun int sendto (int @var{filedes}, void *@var{buffer}. size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, size_t @var{length})
1889 The @code{sendto} function transmits the data in the @var{buffer}
1890 through the socket @var{filedes} to the target socket named by the
1891 @var{addr} and @var{length} arguments.  The @var{size} argument
1892 specifies the number of bytes to be transmitted.
1893
1894 The @var{flags} are interpreted the same way as for @code{send};
1895 see @ref{Transferring Data}.  The return value and error conditions are
1896 also the same as for @code{send}.
1897 @end deftypefun
1898
1899 @comment sys/socket.h
1900 @comment BSD
1901 @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})
1902 The @code{recvfrom} function reads data from the socket @var{filedes} into
1903 the buffer @var{buffer}.  The @var{size} argument specifies the maximum
1904 number of bytes to be read.
1905
1906 The @var{addr} and @var{length_ptr} arguments are used to return information
1907 about the peer socket that sent the information.  @xref{Socket Naming}.
1908 You can specify a null pointer as the @var{addr} argument if you are not
1909 interested in this information.
1910
1911 The @var{flags} are interpreted the same way as for @code{recv};
1912 see @ref{Transferring Data}.  The return value and error conditions are
1913 also the same as for @code{recv}.
1914 @end deftypefun
1915
1916 @ignore
1917 @strong{Incomplete:}  I am not sure what this is for.  It seems to be
1918 related to @code{readv}, which I don't understand either.
1919
1920 @comment sys/socket.h
1921 @comment BSD
1922 @deftp {struct Type} msghdr
1923 @end deftp
1924
1925 @comment sys/socket.h
1926 @comment BSD
1927 @deftypefun int sendmsg (int @var{filedes}, const struct msghdr *@var{message}, int @var{flags})
1928 @end deftypefun
1929
1930 @comment sys/socket.h
1931 @comment BSD
1932 @deftypefun int recvmsg (int @var{filedes}, struct msghdr *@var{message}, int @var{flags})
1933 @end deftypefun
1934 @end ignore
1935
1936 @node Datagram Socket Example
1937 @subsection Datagram Socket Example
1938
1939 Here is a set of example programs that send messages over a datagram
1940 stream in the local domain.  Both the client and server programs use the
1941 @code{make_named_socket} function that was presented in @ref{The Local
1942 Domain} to create and name their sockets.
1943
1944 First, here is the server program.  It sits in a loop waiting for
1945 messages to arrive, bouncing each message back to the sender.
1946 Obviously, this isn't a particularly useful program, but it does show
1947 the general ideas involved.
1948
1949 @comment This example is from lsockserver.c.
1950
1951 @example
1952 #include <sys/socket.h>
1953 #include <sys/un.h>
1954 #include <stdio.h>
1955 #include <errno.h>
1956 #include <stdlib.h>
1957
1958 #define SERVER "/tmp/serversocket"
1959 #define MAXMSG 512
1960
1961 void main (void)
1962 @{
1963   int sock;
1964   char message[MAXMSG];
1965   struct sockaddr_un name;
1966   size_t size;
1967   int nbytes;
1968
1969   /* @r{Make the socket, then loop endlessly.} */
1970
1971   sock = make_named_socket (SERVER);
1972   while (1) @{
1973
1974     /* @r{Wait for a datagram.} */
1975     size = sizeof (name);
1976     nbytes = recvfrom (sock, message, MAXMSG, 0,
1977                        (struct sockaddr *)&name, &size);
1978     if (nbytes < 0) @{
1979       perror ("recfrom (server)");
1980       exit (EXIT_FAILURE);
1981     @}
1982
1983     /* @r{Give a diagnostic message.} */
1984     fprintf (stderr, "Server: got message: %s\n", message);
1985
1986     /* @r{Bounce the message back to the sender.} */
1987     nbytes = sendto (sock, message, nbytes, 0,
1988                      (struct sockaddr *)&name, size);
1989     if (nbytes < 0) @{
1990       perror ("sendto (server)");
1991       exit (EXIT_FAILURE);
1992     @}
1993   @}
1994 @}
1995 @end example
1996
1997 Next, here is the client program.  It sends a datagram to the server
1998 and then waits for a reply.  Notice that the socket for the client (as
1999 well as for the server) in this example has to be given a name.  This is 
2000 so that the server can direct a message back to the client.  Since the
2001 socket has no associated connection state, the only way the server can
2002 do this is by referencing the name of the client.
2003
2004 @comment This example is from lsockclient.c.
2005
2006 @example
2007 #include <sys/socket.h>
2008 #include <sys/un.h>
2009 #include <stdio.h>
2010 #include <errno.h>
2011 #include <stdlib.h>
2012
2013 #define SERVER "/tmp/serversocket"
2014 #define CLIENT "/tmp/mysocket"
2015 #define MAXMSG 512
2016 #define MESSAGE "Yow!!! Are we having fun yet?!?"
2017
2018 void main (void)
2019 @{
2020   int sock;
2021   char message[MAXMSG];
2022   struct sockaddr_un name;
2023   size_t size;
2024   int nbytes;
2025
2026   /* @r{Make the socket.} */
2027   sock = make_named_socket (CLIENT);
2028
2029   /* @r{Initialize the server socket address.} */
2030   name.sun_family = AF_UNIX;
2031   strcpy (name.sun_path, SERVER);
2032   size = strlen (name.sun_path) + sizeof (name.sun_family);
2033
2034   /* @r{Send the datagram.} */
2035   nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0,
2036                    (struct sockaddr *)&name, size);
2037   if (nbytes < 0) @{
2038     perror ("sendto (client)");
2039     exit (EXIT_FAILURE);
2040   @}
2041
2042   /* @r{Wait for a reply.} */   
2043   nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0);
2044   if (nbytes < 0) @{
2045     perror ("recfrom (client)");
2046     exit (EXIT_FAILURE);
2047   @}
2048
2049   /* @r{Print a diagnostic message.} */
2050   fprintf (stderr, "Client: got message: %s\n", message);
2051
2052   /* @r{Clean up.} */
2053   close (sock);
2054   remove (CLIENT);
2055 @}
2056 @end example
2057
2058 Finally, remember that datagram socket communications are unreliable.
2059 In this example, the client program simply blocks indefinitely if the
2060 message is not delivered to the server; it's left up to the user of the
2061 program to kill it off and restart it interactively, if necessary.  A
2062 better solution would be to use @code{select} (@pxref{Waiting for I/O})
2063 to establish a timeout period for the reply, and either resend the
2064 message or shut down the socket cleanly before exiting if the connection
2065 appears to be dead.
2066
2067
2068 @node Socket Options
2069 @section Socket Options
2070 @cindex socket options
2071
2072 This section describes how you can set or inquire about various options
2073 pertaining to sockets and their underlying communications protocols.
2074
2075 @cindex level, for socket options
2076 @cindex socket option level
2077 When you are manipulating a socket option, you must specify which @dfn{level}
2078 the option pertains to.  This describes whether the option applies to
2079 the socket interface, or to a lower-level communications protocol interface.
2080
2081 @menu
2082 * Socket Option Functions::     The basic functions for setting and getting
2083                                  socket options.
2084 * Socket-Level Options::        Details of the options at the socket level.
2085 @end menu
2086
2087 @node Socket Option Functions
2088 @subsection Socket Option Functions
2089
2090 Here are the functions for inquiring about and modifying socket options.
2091 These functions are declared in @file{sys/socket.h}.
2092 @pindex sys/socket.h
2093
2094 @comment sys/socket.h
2095 @comment BSD
2096 @deftypefun int getsockopt (int @var{filedes}, int @var{level}, int @var{optname}, void *@var{optval}, size_t *@var{optlen_ptr})
2097 The @code{getsockopt} function gets information about the value of
2098 option @var{optname} at level @var{level} for socket @var{filedes}.  The
2099 information is stored at the location pointed at by @var{optval}.  You
2100 should initialize the value at @var{optlen_ptr} to contain the size of
2101 this buffer, and on return it contains the actual number of bytes of
2102 information stored.  Most options interpret the @var{optval} buffer as a
2103 single @code{int} value.
2104
2105 The return value is @code{0} on success and @code{-1} on failure.  The
2106 following @code{errno} error conditions are defined for this function:
2107
2108 @table @code
2109 @item EBADF
2110 The @var{filedes} argument is not a valid file descriptor.
2111
2112 @item ENOTSOCK
2113 The @var{filedes} argument is not a socket.
2114
2115 @item ENOPROTOOPT
2116 The @var{optname} doesn't make sense for the given @var{level}.
2117 @end table
2118 @end deftypefun
2119
2120 @comment sys/socket.h
2121 @comment BSD
2122 @deftypefun int setsockopt (int @var{filedes}, int @var{level}, int @var{optname}, void *@var{optval}, size_t @var{optlen})
2123 This function is used to set the socket option @var{optname} at level
2124 @var{level} for socket @var{filedes}.  The value of the option is passed
2125 in the buffer @var{optval}, which has size @var{optlen}.
2126
2127 The return value and error codes are the same as for @code{getsockopt}.
2128 @end deftypefun
2129
2130
2131 @node Socket-Level Options
2132 @subsection Socket-Level Options
2133
2134 The flags for socket-level options are defined in the header file
2135 @file{sys/socket.h}.
2136 @pindex sys/socket.h
2137
2138 @comment sys/socket.h
2139 @comment BSD
2140 @deftypevr Macro int SOL_SOCKET
2141 You should use this macro as the @var{level} argument to @code{getsockopt}
2142 or @code{setsockopt} to manipulate the socket-level options described
2143 in this section.
2144 @end deftypevr
2145
2146 @comment sys/socket.h
2147 @comment BSD
2148 @deftypevr Macro int SO_DEBUG
2149 This option toggles recording of debugging information in the underlying
2150 protocol modules.  The value is an @code{int}, interpreted as a boolean.
2151 @end deftypevr
2152
2153 @comment sys/socket.h
2154 @comment BSD
2155 @deftypevr Macro int SO_REUSEADDR
2156 This option controls whether @code{bind} should permit reuse of local
2157 addresses for this socket.  The value is an @code{int}, interpreted as a
2158 boolean.
2159 @end deftypevr
2160
2161 @comment sys/socket.h
2162 @comment BSD
2163 @deftypevr Macro int SO_KEEPALIVE
2164 This option controls whether the underlying protocol should periodically
2165 transmit messages on a connected socket.  If the peer fails to respond
2166 to these messages, the connection is considered broken.  The value is an
2167 @code{int}, interpreted as a boolean.
2168 @end deftypevr
2169
2170 @comment sys/socket.h
2171 @comment BSD
2172 @deftypevr Macro int SO_DONTROUTE
2173 This option controls whether outgoing messages bypass the normal message
2174 routing facilities.  If set, messages are sent directly to the network
2175 interface instead.  The value is an @code{int}, interpreted as a boolean.
2176 @end deftypevr
2177
2178 @comment sys/socket.h
2179 @comment BSD
2180 @deftypevr Macro int SO_LINGER
2181 This option specifies what should happen when the socket of a type that
2182 promises reliable delivery still has untransmitted messages when it is
2183 closed; see @ref{Closing a Socket}.  The value is a @code{struct linger}
2184 object.
2185 @end deftypevr
2186
2187 @comment sys/socket.h
2188 @comment BSD
2189 @deftp {struct Type} linger
2190 This data type is used to supply a value for the @code{SO_LINGER} socket
2191 option.  It has the following members:
2192
2193 @table @code
2194 @item int l_onoff
2195 This field is interpreted as a boolean.  If nonzero, @code{close}
2196 blocks until the data is transmitted or the timeout period has expired.
2197
2198 @item int l_linger
2199 This specifies the timeout period, in seconds.
2200 @end table
2201 @end deftp
2202
2203 @comment sys/socket.h
2204 @comment BSD
2205 @deftypevr Macro int SO_BROADCAST
2206 This option controls whether datagrams may be broadcast from the socket.
2207 The value is an @code{int}, interpreted as a boolean.
2208 @end deftypevr
2209
2210 @comment sys/socket.h
2211 @comment BSD
2212 @deftypevr Macro int SO_OOBINLINE
2213 If this option is set, out-of-band data received on the socket is placed
2214 in the normal input queue.  This permits it to be read using @code{read}
2215 or @code{recv} without specifying the @code{MSG_OOB} flag.
2216 @xref{Out-of-Band Data}.  The value is an @code{int}, interpreted as a boolean.
2217 @end deftypevr
2218
2219 @comment sys/socket.h
2220 @comment BSD
2221 @deftypevr Macro int SO_SNDBUF
2222 This option gets or sets the size of the output buffer.  The value is an
2223 @code{int}, which is the size in bytes.
2224 @end deftypevr
2225
2226 @comment sys/socket.h
2227 @comment BSD
2228 @deftypevr Macro int SO_RCVBUF
2229 This option gets or sets the size of the input buffer.  The value is an
2230 @code{int}, which is the size in bytes.
2231 @end deftypevr
2232
2233 @comment sys/socket.h
2234 @comment BSD 
2235 @deftypevr Macro int SO_TYPE
2236 This option can be used with @code{getsockopt} only.  It is used to return
2237 the socket type.  The value is an @code{int}.
2238 @end deftypevr
2239
2240 @comment sys/socket.h
2241 @comment BSD 
2242 @deftypevr Macro int SO_ERROR
2243 This option can be used with @code{getsockopt} only.  It is used to reset
2244 the error status of the socket.  The value is an @code{int}, which represents
2245 the previous error status.
2246 @end deftypevr
2247