initial import

1 files changed, 2748 insertions, 0 deletions

diff --git a/manual/socket.texi b/manual/socket.texi
new file mode 100644
index 0000000000..0b338fca82
--- /dev/null
+++ b/manual/socket.texi
@@ -0,0 +1,2748 @@
+@node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top
+@chapter Sockets
+
+This chapter describes the GNU facilities for interprocess
+communication using sockets.
+
+@cindex socket
+@cindex interprocess communication, with sockets
+A @dfn{socket} is a generalized interprocess communication channel.
+Like a pipe, a socket is represented as a file descriptor.  But,
+unlike pipes, sockets support communication between unrelated
+processes, and even between processes running on different machines
+that communicate over a network.  Sockets are the primary means of
+communicating with other machines; @code{telnet}, @code{rlogin},
+@code{ftp}, @code{talk}, and the other familiar network programs use
+sockets.
+
+Not all operating systems support sockets.  In the GNU library, the
+header file @file{sys/socket.h} exists regardless of the operating
+system, and the socket functions always exist, but if the system does
+not really support sockets, these functions always fail.
+
+@strong{Incomplete:} We do not currently document the facilities for
+broadcast messages or for configuring Internet interfaces.
+
+@menu
+* Socket Concepts::	Basic concepts you need to know about.
+* Communication Styles::Stream communication, datagrams, and other styles.
+* Socket Addresses::	How socket names (``addresses'') work.
+* File Namespace::	Details about the file namespace.
+* Internet Namespace::	Details about the Internet namespace.
+* Misc Namespaces::	Other namespaces not documented fully here.
+* Open/Close Sockets::  Creating sockets and destroying them.
+* Connections::		Operations on sockets with connection state.
+* Datagrams::		Operations on datagram sockets.
+* Inetd::		Inetd is a daemon that starts servers on request.
+			   The most convenient way to write a server
+			   is to make it work with Inetd.
+* Socket Options::	Miscellaneous low-level socket options.
+* Networks Database::   Accessing the database of network names.
+@end menu
+
+@node Socket Concepts
+@section Socket Concepts
+
+@cindex communication style (of a socket)
+@cindex style of communication (of a socket)
+When you create a socket, you must specify the style of communication
+you want to use and the type of protocol that should implement it.
+The @dfn{communication style} of a socket defines the user-level
+semantics of sending and receiving data on the socket.  Choosing a
+communication style specifies the answers to questions such as these:
+
+@itemize @bullet
+@item
+@cindex packet
+@cindex byte stream
+@cindex stream (sockets)
+@strong{What are the units of data transmission?}  Some communication
+styles regard the data as a sequence of bytes, with no larger
+structure; others group the bytes into records (which are known in
+this context as @dfn{packets}).
+
+@item
+@cindex loss of data on sockets
+@cindex data loss on sockets
+@strong{Can data be lost during normal operation?}  Some communication
+styles guarantee that all the data sent arrives in the order it was
+sent (barring system or network crashes); other styles occasionally
+lose data as a normal part of operation, and may sometimes deliver
+packets more than once or in the wrong order.
+
+Designing a program to use unreliable communication styles usually
+involves taking precautions to detect lost or misordered packets and
+to retransmit data as needed.
+
+@item
+@strong{Is communication entirely with one partner?}  Some
+communication styles are like a telephone call---you make a
+@dfn{connection} with one remote socket, and then exchange data
+freely.  Other styles are like mailing letters---you specify a
+destination address for each message you send.
+@end itemize
+
+@cindex namespace (of socket)
+@cindex domain (of socket)
+@cindex socket namespace
+@cindex socket domain
+You must also choose a @dfn{namespace} for naming the socket.  A socket
+name (``address'') is meaningful only in the context of a particular
+namespace.  In fact, even the data type to use for a socket name may
+depend on the namespace.  Namespaces are also called ``domains'', but we
+avoid that word as it can be confused with other usage of the same
+term.  Each namespace has a symbolic name that starts with @samp{PF_}.
+A corresponding symbolic name starting with @samp{AF_} designates the
+address format for that namespace.
+
+@cindex network protocol
+@cindex protocol (of socket)
+@cindex socket protocol
+@cindex protocol family
+Finally you must choose the @dfn{protocol} to carry out the
+communication.  The protocol determines what low-level mechanism is used
+to transmit and receive data.  Each protocol is valid for a particular
+namespace and communication style; a namespace is sometimes called a
+@dfn{protocol family} because of this, which is why the namespace names
+start with @samp{PF_}.
+
+The rules of a protocol apply to the data passing between two programs,
+perhaps on different computers; most of these rules are handled by the
+operating system, and you need not know about them.  What you do need to
+know about protocols is this:
+
+@itemize @bullet
+@item
+In order to have communication between two sockets, they must specify
+the @emph{same} protocol.
+
+@item
+Each protocol is meaningful with particular style/namespace
+combinations and cannot be used with inappropriate combinations.  For
+example, the TCP protocol fits only the byte stream style of
+communication and the Internet namespace.
+
+@item
+For each combination of style and namespace, there is a @dfn{default
+protocol} which you can request by specifying 0 as the protocol
+number.  And that's what you should normally do---use the default.
+@end itemize
+
+@node Communication Styles
+@section Communication Styles
+
+The GNU library includes support for several different kinds of sockets,
+each with different characteristics.  This section describes the
+supported socket types.  The symbolic constants listed here are
+defined in @file{sys/socket.h}.
+@pindex sys/socket.h
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int SOCK_STREAM
+The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs});
+it operates over a connection with a particular remote socket, and
+transmits data reliably as a stream of bytes.
+
+Use of this style is covered in detail in @ref{Connections}.
+@end deftypevr
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int SOCK_DGRAM
+The @code{SOCK_DGRAM} style is used for sending
+individually-addressed packets, unreliably.  
+It is the diametrical opposite of @code{SOCK_STREAM}.
+
+Each time you write data to a socket of this kind, that data becomes
+one packet.  Since @code{SOCK_DGRAM} sockets do not have connections,
+you must specify the recipient address with each packet.
+
+The only guarantee that the system makes about your requests to
+transmit data is that it will try its best to deliver each packet you
+send.  It may succeed with the sixth packet after failing with the
+fourth and fifth packets; the seventh packet may arrive before the
+sixth, and may arrive a second time after the sixth.
+
+The typical use for @code{SOCK_DGRAM} is in situations where it is
+acceptable to simply resend a packet if no response is seen in a
+reasonable amount of time.
+
+@xref{Datagrams}, for detailed information about how to use datagram
+sockets.
+@end deftypevr
+
+@ignore
+@c This appears to be only for the NS domain, which we aren't
+@c discussing and probably won't support either.
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int SOCK_SEQPACKET
+This style is like @code{SOCK_STREAM} except that the data is
+structured into packets.
+
+A program that receives data over a @code{SOCK_SEQPACKET} socket
+should be prepared to read the entire message packet in a single call
+to @code{read}; if it only reads part of the message, the remainder of
+the message is simply discarded instead of being available for
+subsequent calls to @code{read}.
+
+Many protocols do not support this communication style.
+@end deftypevr
+@end ignore
+
+@ignore
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int SOCK_RDM
+This style is a reliable version of @code{SOCK_DGRAM}: it sends
+individually addressed packets, but guarantees that each packet sent
+arrives exactly once.
+
+@strong{Warning:} It is not clear this is actually supported
+by any operating system.
+@end deftypevr
+@end ignore
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int SOCK_RAW
+This style provides access to low-level network protocols and
+interfaces.  Ordinary user programs usually have no need to use this
+style.
+@end deftypevr
+
+@node Socket Addresses
+@section Socket Addresses
+
+@cindex address of socket
+@cindex name of socket
+@cindex binding a socket address
+@cindex socket address (name) binding
+The name of a socket is normally called an @dfn{address}.  The
+functions and symbols for dealing with socket addresses were named
+inconsistently, sometimes using the term ``name'' and sometimes using
+``address''.  You can regard these terms as synonymous where sockets
+are concerned.
+
+A socket newly created with the @code{socket} function has no
+address.  Other processes can find it for communication only if you
+give it an address.  We call this @dfn{binding} the address to the
+socket, and the way to do it is with the @code{bind} function.
+
+You need be concerned with the address of a socket if other processes
+are to find it and start communicating with it.  You can specify an
+address for other sockets, but this is usually pointless; the first time
+you send data from a socket, or use it to initiate a connection, the
+system assigns an address automatically if you have not specified one.
+
+Occasionally a client needs to specify an address because the server
+discriminates based on addresses; for example, the rsh and rlogin
+protocols look at the client's socket address and don't bypass password
+checking unless it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
+
+The details of socket addresses vary depending on what namespace you are
+using.  @xref{File Namespace}, or @ref{Internet Namespace}, for specific
+information.
+
+Regardless of the namespace, you use the same functions @code{bind} and
+@code{getsockname} to set and examine a socket's address.  These
+functions use a phony data type, @code{struct sockaddr *}, to accept the
+address.  In practice, the address lives in a structure of some other
+data type appropriate to the address format you are using, but you cast
+its address to @code{struct sockaddr *} when you pass it to
+@code{bind}.
+
+@menu
+* Address Formats::		About @code{struct sockaddr}.
+* Setting Address::		Binding an address to a socket.
+* Reading Address::		Reading the address of a socket.
+@end menu
+
+@node Address Formats
+@subsection Address Formats
+
+The functions @code{bind} and @code{getsockname} use the generic data
+type @code{struct sockaddr *} to represent a pointer to a socket
+address.  You can't use this data type effectively to interpret an
+address or construct one; for that, you must use the proper data type
+for the socket's namespace.
+
+Thus, the usual practice is to construct an address in the proper
+namespace-specific type, then cast a pointer to @code{struct sockaddr *}
+when you call @code{bind} or @code{getsockname}.
+
+The one piece of information that you can get from the @code{struct
+sockaddr} data type is the @dfn{address format} designator which tells
+you which data type to use to understand the address fully.
+
+@pindex sys/socket.h
+The symbols in this section are defined in the header file
+@file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment BSD
+@deftp {Date Type} {struct sockaddr}
+The @code{struct sockaddr} type itself has the following members:
+
+@table @code
+@item short int sa_family
+This is the code for the address format of this address.  It
+identifies the format of the data which follows.
+
+@item char sa_data[14]
+This is the actual socket address data, which is format-dependent.  Its
+length also depends on the format, and may well be more than 14.  The
+length 14 of @code{sa_data} is essentially arbitrary.
+@end table
+@end deftp
+
+Each address format has a symbolic name which starts with @samp{AF_}.
+Each of them corresponds to a @samp{PF_} symbol which designates the
+corresponding namespace.  Here is a list of address format names:
+
+@table @code
+@comment sys/socket.h
+@comment GNU
+@item AF_FILE
+@vindex AF_FILE
+This designates the address format that goes with the file namespace.
+(@code{PF_FILE} is the name of that namespace.)  @xref{File Namespace
+Details}, for information about this address format.
+
+@comment sys/socket.h
+@comment BSD
+@item AF_UNIX
+@vindex AF_UNIX
+This is a synonym for @code{AF_FILE}, for compatibility.
+(@code{PF_UNIX} is likewise a synonym for @code{PF_FILE}.)
+
+@comment sys/socket.h
+@comment BSD
+@item AF_INET
+@vindex AF_INET
+This designates the address format that goes with the Internet
+namespace.  (@code{PF_INET} is the name of that namespace.)
+@xref{Internet Address Format}.
+
+@comment sys/socket.h
+@comment BSD
+@item AF_UNSPEC
+@vindex AF_UNSPEC
+This designates no particular address format.  It is used only in rare
+cases, such as to clear out the default destination address of a
+``connected'' datagram socket.  @xref{Sending Datagrams}.
+
+The corresponding namespace designator symbol @code{PF_UNSPEC} exists
+for completeness, but there is no reason to use it in a program.
+@end table
+
+@file{sys/socket.h} defines symbols starting with @samp{AF_} for many
+different kinds of networks, all or most of which are not actually
+implemented.  We will document those that really work, as we receive
+information about how to use them.
+
+@node Setting Address
+@subsection Setting the Address of a Socket
+
+@pindex sys/socket.h
+Use the @code{bind} function to assign an address to a socket.  The
+prototype for @code{bind} is in the header file @file{sys/socket.h}.
+For examples of use, see @ref{File Namespace}, or see @ref{Inet Example}.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, size_t @var{length})
+The @code{bind} function assigns an address to the socket
+@var{socket}.  The @var{addr} and @var{length} arguments specify the
+address; the detailed format of the address depends on the namespace.
+The first part of the address is always the format designator, which
+specifies a namespace, and says that the address is in the format for
+that namespace.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{socket} argument is not a valid file descriptor.
+
+@item ENOTSOCK
+The descriptor @var{socket} is not a socket.
+
+@item EADDRNOTAVAIL
+The specified address is not available on this machine.
+
+@item EADDRINUSE
+Some other socket is already using the specified address.
+
+@item EINVAL
+The socket @var{socket} already has an address.
+
+@item EACCES
+You do not have permission to access the requested address.  (In the
+Internet domain, only the super-user is allowed to specify a port number
+in the range 0 through @code{IPPORT_RESERVED} minus one; see
+@ref{Ports}.)
+@end table
+
+Additional conditions may be possible depending on the particular namespace
+of the socket.
+@end deftypefun
+
+@node Reading Address
+@subsection Reading the Address of a Socket
+
+@pindex sys/socket.h
+Use the function @code{getsockname} to examine the address of an
+Internet socket.  The prototype for this function is in the header file
+@file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, size_t *@var{length-ptr})
+The @code{getsockname} function returns information about the
+address of the socket @var{socket} in the locations specified by the
+@var{addr} and @var{length-ptr} arguments.  Note that the
+@var{length-ptr} is a pointer; you should initialize it to be the
+allocation size of @var{addr}, and on return it contains the actual
+size of the address data.
+
+The format of the address data depends on the socket namespace.  The
+length of the information is usually fixed for a given namespace, so
+normally you can know exactly how much space is needed and can provide
+that much.  The usual practice is to allocate a place for the value
+using the proper data type for the socket's namespace, then cast its
+address to @code{struct sockaddr *} to pass it to @code{getsockname}.
+
+The return value is @code{0} on success and @code{-1} on error.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{socket} argument is not a valid file descriptor.
+
+@item ENOTSOCK
+The descriptor @var{socket} is not a socket.
+
+@item ENOBUFS
+There are not enough internal buffers available for the operation.
+@end table
+@end deftypefun
+
+You can't read the address of a socket in the file namespace.  This is
+consistent with the rest of the system; in general, there's no way to
+find a file's name from a descriptor for that file.
+
+@node File Namespace
+@section The File Namespace
+@cindex file namespace, for sockets
+
+This section describes the details of the file namespace, whose
+symbolic name (required when you create a socket) is @code{PF_FILE}.
+
+@menu
+* Concepts: File Namespace Concepts.	What you need to understand.
+* Details: File Namespace Details.	Address format, symbolic names, etc.
+* Example: File Socket Example.		Example of creating a socket.
+@end menu
+
+@node File Namespace Concepts
+@subsection File Namespace Concepts
+
+In the file namespace, socket addresses are file names.  You can specify
+any file name you want as the address of the socket, but you must have
+write permission on the directory containing it.  In order to connect to
+a socket, you must have read permission for it.  It's common to put
+these files in the @file{/tmp} directory.
+
+One peculiarity of the file namespace is that the name is only used when
+opening the connection; once that is over with, the address is not
+meaningful and may not exist.
+
+Another peculiarity is that you cannot connect to such a socket from
+another machine--not even if the other machine shares the file system
+which contains the name of the socket.  You can see the socket in a
+directory listing, but connecting to it never succeeds.  Some programs
+take advantage of this, such as by asking the client to send its own
+process ID, and using the process IDs to distinguish between clients.
+However, we recommend you not use this method in protocols you design,
+as we might someday permit connections from other machines that mount
+the same file systems.  Instead, send each new client an identifying
+number if you want it to have one.
+
+After you close a socket in the file namespace, you should delete the
+file name from the file system.  Use @code{unlink} or @code{remove} to
+do this; see @ref{Deleting Files}.
+
+The file namespace supports just one protocol for any communication
+style; it is protocol number @code{0}.
+
+@node File Namespace Details
+@subsection Details of File Namespace
+
+@pindex sys/socket.h
+To create a socket in the file namespace, use the constant
+@code{PF_FILE} as the @var{namespace} argument to @code{socket} or
+@code{socketpair}.  This constant is defined in @file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment GNU
+@deftypevr Macro int PF_FILE
+This designates the file namespace, in which socket addresses are file
+names, and its associated family of protocols.
+@end deftypevr
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int PF_UNIX
+This is a synonym for @code{PF_FILE}, for compatibility's sake.
+@end deftypevr
+
+The structure for specifying socket names in the file namespace is
+defined in the header file @file{sys/un.h}:
+@pindex sys/un.h
+
+@comment sys/un.h
+@comment BSD
+@deftp {Data Type} {struct sockaddr_un}
+This structure is used to specify file namespace socket addresses.  It has
+the following members:
+
+@table @code
+@item short int sun_family
+This identifies the address family or format of the socket address.
+You should store the value @code{AF_FILE} to designate the file
+namespace.  @xref{Socket Addresses}.
+
+@item char sun_path[108]
+This is the file name to use.
+
+@strong{Incomplete:}  Why is 108 a magic number?  RMS suggests making
+this a zero-length array and tweaking the example following to use
+@code{alloca} to allocate an appropriate amount of storage based on
+the length of the filename.
+@end table
+@end deftp
+
+You should compute the @var{length} parameter for a socket address in
+the file namespace as the sum of the size of the @code{sun_family}
+component and the string length (@emph{not} the allocation size!) of
+the file name string.
+
+@node File Socket Example
+@subsection Example of File-Namespace Sockets
+
+Here is an example showing how to create and name a socket in the file
+namespace.
+
+@smallexample
+@include mkfsock.c.texi
+@end smallexample
+
+@node Internet Namespace
+@section The Internet Namespace
+@cindex Internet namespace, for sockets
+
+This section describes the details the protocols and socket naming
+conventions used in the Internet namespace.
+
+To create a socket in the Internet namespace, use the symbolic name
+@code{PF_INET} of this namespace as the @var{namespace} argument to
+@code{socket} or @code{socketpair}.  This macro is defined in
+@file{sys/socket.h}.
+@pindex sys/socket.h
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int PF_INET
+This designates the Internet namespace and associated family of
+protocols.
+@end deftypevr
+
+A socket address for the Internet namespace includes the following components:
+
+@itemize @bullet
+@item
+The address of the machine you want to connect to.  Internet addresses
+can be specified in several ways; these are discussed in @ref{Internet
+Address Format}, @ref{Host Addresses}, and @ref{Host Names}.
+
+@item
+A port number for that machine.  @xref{Ports}.
+@end itemize
+
+You must ensure that the address and port number are represented in a
+canonical format called @dfn{network byte order}.  @xref{Byte Order},
+for information about this.
+
+@menu
+* Internet Address Format::     How socket addresses are specified in the
+                                 Internet namespace.
+* Host Addresses::	        All about host addresses of internet host.
+* Protocols Database::		Referring to protocols by name.
+* Ports::			Internet port numbers.
+* Services Database::           Ports may have symbolic names.
+* Byte Order::		        Different hosts may use different byte
+                                 ordering conventions; you need to
+                                 canonicalize host address and port number. 
+* Inet Example::	        Putting it all together.
+@end menu
+
+@node Internet Address Format
+@subsection Internet Socket Address Format
+
+In the Internet namespace, a socket address consists of a host address
+and a port on that host.  In addition, the protocol you choose serves
+effectively as a part of the address because local port numbers are
+meaningful only within a particular protocol.
+
+The data type for representing socket addresses in the Internet namespace
+is defined in the header file @file{netinet/in.h}.
+@pindex netinet/in.h
+
+@comment netinet/in.h
+@comment BSD
+@deftp {Data Type} {struct sockaddr_in}
+This is the data type used to represent socket addresses in the
+Internet namespace.  It has the following members:
+
+@table @code
+@item short int sin_family
+This identifies the address family or format of the socket address.
+You should store the value of @code{AF_INET} in this member.
+@xref{Socket Addresses}.
+
+@item struct in_addr sin_addr
+This is the Internet address of the host machine.  @xref{Host
+Addresses}, and @ref{Host Names}, for how to get a value to store
+here.
+
+@item unsigned short int sin_port
+This is the port number.  @xref{Ports}.
+@end table
+@end deftp
+
+When you call @code{bind} or @code{getsockname}, you should specify
+@code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
+you are using an Internet namespace socket address.
+
+@node Host Addresses
+@subsection Host Addresses
+
+Each computer on the Internet has one or more @dfn{Internet addresses},
+numbers which identify that computer among all those on the Internet.
+Users typically write numeric host addresses as sequences of four
+numbers, separated by periods, as in @samp{128.52.46.32}.
+
+Each computer also has one or more @dfn{host names}, which are strings
+of words separated by periods, as in @samp{churchy.gnu.ai.mit.edu}.
+
+Programs that let the user specify a host typically accept both numeric
+addresses and host names