   This file documents the GNU C library.

   This is Edition 0.06 DRAFT, last updated 24 October 1994, of `The
GNU C Library Reference Manual', for Version 1.09 Beta.

   Copyright (C) 1993, 1994 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translations of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.

Example of File-Namespace Sockets
---------------------------------

   Here is an example showing how to create and name a socket in the
file namespace.

     #include <stddef.h>
     #include <stdio.h>
     #include <errno.h>
     #include <stdlib.h>
     #include <sys/socket.h>
     #include <sys/un.h>

     int
     make_named_socket (const char *filename)
     {
       struct sockaddr_un name;
       int sock;
       size_t size;

       /* Create the socket. */

       sock = socket (PF_UNIX, SOCK_DGRAM, 0);
       if (sock < 0)
         {
           perror ("socket");
           exit (EXIT_FAILURE);
         }

       /* Bind a name to the socket. */

       name.sun_family = AF_FILE;
       strcpy (name.sun_path, filename);

       /* The size of the address is
          the offset of the start of the filename,
          plus its length,
          plus one for the terminating null byte. */
       size = (offsetof (struct sockaddr_un, sun_path)
               + strlen (name.sun_path) + 1);

       if (bind (sock, (struct sockaddr *) &name, size) < 0)
         {
           perror ("bind");
           exit (EXIT_FAILURE);
         }

       return sock;
     }

The Internet Namespace
======================

   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
`PF_INET' of this namespace as the NAMESPACE argument to `socket' or
`socketpair'.  This macro is defined in `sys/socket.h'.

 - Macro: int PF_INET
     This designates the Internet namespace and associated family of
     protocols.

   A socket address for the Internet namespace includes the following
components:

   * The address of the machine you want to connect to.  Internet
     addresses can be specified in several ways; these are discussed in
     Internet Address Format, Host Addresses, and
     Host Names.

   * A port number for that machine.  See Ports.

   You must ensure that the address and port number are represented in a
canonical format called "network byte order".  See Byte Order, for
information about this.

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 `netinet/in.h'.

 - Data Type: struct sockaddr_in
     This is the data type used to represent socket addresses in the
     Internet namespace.  It has the following members:

    `short int sin_family'
          This identifies the address family or format of the socket
          address.  You should store the value of `AF_INET' in this
          member.  See Socket Addresses.

    `struct in_addr sin_addr'
          This is the Internet address of the host machine.  See Host Addresses,
          and Host Names, for how to get a value
          to store here.

    `unsigned short int sin_port'
          This is the port number.  See Ports.

   When you call `bind' or `getsockname', you should specify `sizeof
(struct sockaddr_in)' as the LENGTH parameter if you are using an
Internet namespace socket address.

Host Addresses
--------------

   Each computer on the Internet has one or more "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 `128.52.46.32'.

   Each computer also has one or more "host names", which are strings
of words separated by periods, as in `churchy.gnu.ai.mit.edu'.

   Programs that let the user specify a host typically accept both
numeric addresses and host names.  But the program needs a numeric
address to open a connection; to use a host name, you must convert it
to the numeric address it stands for.

Internet Host Addresses
.......................

   Each computer on the Internet has one or more Internet addresses,
numbers which identify that computer among all those on the Internet.

   An Internet host address is a number containing four bytes of data.
These are divided into two parts, a "network number" and a "local
network address number" within that network.  The network number
consists of the first one, two or three bytes; the rest of the bytes
are the local address.

   Network numbers are registered with the Network Information Center
(NIC), and are divided into three classes--A, B, and C.  The local
network address numbers of individual machines are registered with the
administrator of the particular network.

   Class A networks have single-byte numbers in the range 0 to 127.
There are only a small number of Class A networks, but they can each
support a very large number of hosts.  Medium-sized Class B networks
have two-byte network numbers, with the first byte in the range 128 to
191.  Class C networks are the smallest; they have three-byte network
numbers, with the first byte in the range 192-255.  Thus, the first 1,
2, or 3 bytes of an Internet address specifies a network.  The
remaining bytes of the Internet address specify the address within that
network.

   The Class A network 0 is reserved for broadcast to all networks.  In
addition, the host number 0 within each network is reserved for
broadcast to all hosts in that network.

   The Class A network 127 is reserved for loopback; you can always use
the Internet address `127.0.0.1' to refer to the host machine.

   Since a single machine can be a member of multiple networks, it can
have multiple Internet host addresses.  However, there is never
supposed to be more than one machine with the same host address.

   There are four forms of the "standard numbers-and-dots notation" for
Internet addresses:

`A.B.C.D'
     This specifies all four bytes of the address individually.

`A.B.C'
     The last part of the address, C, is interpreted as a 2-byte
     quantity.  This is useful for specifying host addresses in a Class
     B network with network address number `A.B'.

`A.B'
     The last part of the address, C, is interpreted as a 3-byte
     quantity.  This is useful for specifying host addresses in a Class
     A network with network address number A.

`A'
     If only one part is given, this corresponds directly to the host
     address number.

   Within each part of the address, the usual C conventions for
specifying the radix apply.  In other words, a leading `0x' or `0X'
implies hexadecimal radix; a leading `0' implies octal; and otherwise
decimal radix is assumed.

Host Address Data Type
......................

   Internet host addresses are represented in some contexts as integers
(type `unsigned long int').  In other contexts, the integer is packaged
inside a structure of type `struct in_addr'.  It would be better if the
usage were made consistent, but it is not hard to extract the integer
from the structure or put the integer into a structure.

   The following basic definitions for Internet addresses appear in the
header file `netinet/in.h':

 - Data Type: struct in_addr
     This data type is used in certain contexts to contain an Internet
     host address.  It has just one field, named `s_addr', which
     records the host address number as an `unsigned long int'.

 - Macro: unsigned long int INADDR_LOOPBACK
     You can use this constant to stand for "the address of this
     machine," instead of finding its actual address.  It is the
     Internet address `127.0.0.1', which is usually called `localhost'.
     This special constant saves you the trouble of looking up the
     address of your own machine.  Also, the system usually implements
     `INADDR_LOOPBACK' specially, avoiding any network traffic for the
     case of one machine talking to itself.

 - Macro: unsigned long int INADDR_ANY
     You can use this constant to stand for "any incoming address," when
     binding to an address.  See Setting Address.  This is the usual
     address to give in the `sin_addr' member of `struct sockaddr_in'
     when you want to accept Internet connections.

 - Macro: unsigned long int INADDR_BROADCAST
     This constant is the address you use to send a broadcast message.

 - Macro: unsigned long int INADDR_NONE
     This constant is returned by some functions to indicate an error.

Host Address Functions
......................

   These additional functions for manipulating Internet addresses are
declared in `arpa/inet.h'.  They represent Internet addresses in
network byte order; they represent network numbers and
local-address-within-network numbers in host byte order.  See Byte Order,
for an explanation of network and host byte order.

 - Function: int inet_aton (const char *NAME, struct in_addr *ADDR)
     This function converts the Internet host address NAME from the
     standard numbers-and-dots notation into binary data and stores it
     in the `struct in_addr' that ADDR points to.  `inet_aton' returns
     nonzero if the address is valid, zero if not.

 - Function: unsigned long int inet_addr (const char *NAME)
     This function converts the Internet host address NAME from the
     standard numbers-and-dots notation into binary data.  If the input
     is not valid, `inet_addr' returns `INADDR_NONE'.  This is an
     obsolete interface to `inet_aton', described immediately above; it
     is obsolete because `INADDR_NONE' is a valid address
     (255.255.255.255), and `inet_aton' provides a cleaner way to
     indicate error return.

 - Function: unsigned long int inet_network (const char *NAME)
     This function extracts the network number from the address NAME,
     given in the standard numbers-and-dots notation.  If the input is
     not valid, `inet_network' returns `-1'.

 - Function: char * inet_ntoa (struct in_addr ADDR)
     This function converts the Internet host address ADDR to a string
     in the standard numbers-and-dots notation.  The return value is a
     pointer into a statically-allocated buffer.  Subsequent calls will
     overwrite the same buffer, so you should copy the string if you
     need to save it.

 - Function: struct in_addr inet_makeaddr (int NET, int LOCAL)
     This function makes an Internet host address by combining the
     network number NET with the local-address-within-network number
     LOCAL.

 - Function: int inet_lnaof (struct in_addr ADDR)
     This function returns the local-address-within-network part of the
     Internet host address ADDR.

 - Function: int inet_netof (struct in_addr ADDR)
     This function returns the network number part of the Internet host
     address ADDR.

Host Names
..........

   Besides the standard numbers-and-dots notation for Internet
addresses, you can also refer to a host by a symbolic name.  The
advantage of a symbolic name is that it is usually easier to remember.
For example, the machine with Internet address `128.52.46.32' is also
known as `churchy.gnu.ai.mit.edu'; and other machines in the
`gnu.ai.mit.edu' domain can refer to it simply as `churchy'.

   Internally, the system uses a database to keep track of the mapping
between host names and host numbers.  This database is usually either
the file `/etc/hosts' or an equivalent provided by a name server.  The
functions and other symbols for accessing this database are declared in
`netdb.h'.  They are BSD features, defined unconditionally if you
include `netdb.h'.

 - Data Type: struct hostent
     This data type is used to represent an entry in the hosts
     database.  It has the following members:

    `char *h_name'
          This is the "official" name of the host.

    `char **h_aliases'
          These are alternative names for the host, represented as a
          null-terminated vector of strings.

    `int h_addrtype'
          This is the host address type; in practice, its value is
          always `AF_INET'.  In principle other kinds of addresses
          could be represented in the data base as well as Internet
          addresses; if this were done, you might find a value in this
          field other than `AF_INET'.  See Socket Addresses.

    `int h_length'
          This is the length, in bytes, of each address.

    `char **h_addr_list'
          This is the vector of addresses for the host.  (Recall that
          the host might be connected to multiple networks and have
          different addresses on each one.)  The vector is terminated
          by a null pointer.

    `char *h_addr'
          This is a synonym for `h_addr_list[0]'; in other words, it is
          the first host address.

   As far as the host database is concerned, each address is just a
block of memory `h_length' bytes long.  But in other contexts there is
an implicit assumption that you can convert this to a `struct in_addr'
or an `unsigned long int'.  Host addresses in a `struct hostent'
structure are always given in network byte order; see Byte Order.

   You can use `gethostbyname' or `gethostbyaddr' to search the hosts
database for information about a particular host.  The information is
returned in a statically-allocated structure; you must copy the
information if you need to save it across calls.

 - Function: struct hostent * gethostbyname (const char *NAME)
     The `gethostbyname' function returns information about the host
     named NAME.  If the lookup fails, it returns a null pointer.

 - Function: struct hostent * gethostbyaddr (const char *ADDR, int
          LENGTH, int FORMAT)
     The `gethostbyaddr' function returns information about the host
     with Internet address ADDR.  The LENGTH argument is the size (in
     bytes) of the address at ADDR.  FORMAT specifies the address
     format; for an Internet address, specify a value of `AF_INET'.

     If the lookup fails, `gethostbyaddr' returns a null pointer.

   If the name lookup by `gethostbyname' or `gethostbyaddr' fails, you
can find out the reason by looking at the value of the variable
`h_errno'.  (It would be cleaner design for these functions to set
`errno', but use of `h_errno' is compatible with other systems.)
Before using `h_errno', you must declare it like this:

     extern int h_errno;

   Here are the error codes that you may find in `h_errno':

`HOST_NOT_FOUND'
     No such host is known in the data base.

`TRY_AGAIN'
     This condition happens when the name server could not be
     contacted.  If you try again later, you may succeed then.

`NO_RECOVERY'
     A non-recoverable error occurred.

`NO_ADDRESS'
     The host database contains an entry for the name, but it doesn't
     have an associated Internet address.

   You can also scan the entire hosts database one entry at a time using
`sethostent', `gethostent', and `endhostent'.  Be careful in using
these functions, because they are not reentrant.

 - Function: void sethostent (int STAYOPEN)
     This function opens the hosts database to begin scanning it.  You
     can then call `gethostent' to read the entries.

     If the STAYOPEN argument is nonzero, this sets a flag so that
     subsequent calls to `gethostbyname' or `gethostbyaddr' will not
     close the database (as they usually would).  This makes for more
     efficiency if you call those functions several times, by avoiding
     reopening the database for each call.

 - Function: struct hostent * gethostent ()
     This function returns the next entry in the hosts database.  It
     returns a null pointer if there are no more entries.

 - Function: void endhostent ()
     This function closes the hosts database.

Internet Ports
--------------

   A socket address in the Internet namespace consists of a machine's
Internet address plus a "port number" which distinguishes the sockets
on a given machine (for a given protocol).  Port numbers range from 0
to 65,535.

   Port numbers less than `IPPORT_RESERVED' are reserved for standard
servers, such as `finger' and `telnet'.  There is a database that keeps
track of these, and you can use the `getservbyname' function to map a
service name onto a port number; see Services Database.

   If you write a server that is not one of the standard ones defined in
the database, you must choose a port number for it.  Use a number
greater than `IPPORT_USERRESERVED'; such numbers are reserved for
servers and won't ever be generated automatically by the system.
Avoiding conflicts with servers being run by other users is up to you.

   When you use a socket without specifying its address, the system
generates a port number for it.  This number is between
`IPPORT_RESERVED' and `IPPORT_USERRESERVED'.

   On the Internet, it is actually legitimate to have two different
sockets with the same port number, as long as they never both try to
communicate with the same socket address (host address plus port
number).  You shouldn't duplicate a port number except in special
circumstances where a higher-level protocol requires it.  Normally, the
system won't let you do it; `bind' normally insists on distinct port
numbers.  To reuse a port number, you must set the socket option
`SO_REUSEADDR'.  See Socket-Level Options.

   These macros are defined in the header file `netinet/in.h'.

 - Macro: int IPPORT_RESERVED
     Port numbers less than `IPPORT_RESERVED' are reserved for
     superuser use.

 - Macro: int IPPORT_USERRESERVED
     Port numbers greater than or equal to `IPPORT_USERRESERVED' are
     reserved for explicit use; they will never be allocated
     automatically.

The Services Database
---------------------

   The database that keeps track of "well-known" services is usually
either the file `/etc/services' or an equivalent from a name server.
You can use these utilities, declared in `netdb.h', to access the
services database.

 - Data Type: struct servent
     This data type holds information about entries from the services
     database.  It has the following members:

    `char *s_name'
          This is the "official" name of the service.

    `char **s_aliases'
          These are alternate names for the service, represented as an
          array of strings.  A null pointer terminates the array.

    `int s_port'
          This is the port number for the service.  Port numbers are
          given in network byte order; see Byte Order.

    `char *s_proto'
          This is the name of the protocol to use with this service.
          See Protocols Database.

   To get information about a particular service, use the
`getservbyname' or `getservbyport' functions.  The information is
returned in a statically-allocated structure; you must copy the
information if you need to save it across calls.

 - Function: struct servent * getservbyname (const char *NAME, const
          char *PROTO)
     The `getservbyname' function returns information about the service
     named NAME using protocol PROTO.  If it can't find such a service,
     it returns a null pointer.

     This function is useful for servers as well as for clients; servers
     use it to determine which port they should listen on (see
     Listening.).

 - Function: struct servent * getservbyport (int PORT, const char
          *PROTO)
     The `getservbyport' function returns information about the service
     at port PORT using protocol PROTO.  If it can't find such a
     service, it returns a null pointer.

   You can also scan the services database using `setservent',
`getservent', and `endservent'.  Be careful in using these functions,
because they are not reentrant.

 - Function: void setservent (int STAYOPEN)
     This function opens the services database to begin scanning it.

     If the STAYOPEN argument is nonzero, this sets a flag so that
     subsequent calls to `getservbyname' or `getservbyport' will not
     close the database (as they usually would).  This makes for more
     efficiency if you call those functions several times, by avoiding
     reopening the database for each call.

 - Function: struct servent * getservent (void)
     This function returns the next entry in the services database.  If
     there are no more entries, it returns a null pointer.

 - Function: void endservent (void)
     This function closes the services database.

Byte Order Conversion
---------------------

   Different kinds of computers use different conventions for the
ordering of bytes within a word.  Some computers put the most
significant byte within a word first (this is called "big-endian"
order), and others put it last ("little-endian" order).

   So that machines with different byte order conventions can
communicate, the Internet protocols specify a canonical byte order
convention for data transmitted over the network.  This is known as the
"network byte order".

   When establishing an Internet socket connection, you must make sure
that the data in the `sin_port' and `sin_addr' members of the
`sockaddr_in' structure are represented in the network byte order.  If
you are encoding integer data in the messages sent through the socket,
you should convert this to network byte order too.  If you don't do
this, your program may fail when running on or talking to other kinds
of machines.

   If you use `getservbyname' and `gethostbyname' or `inet_addr' to get
the port number and host address, the values are already in the network
byte order, and you can copy them directly into the `sockaddr_in'
structure.

   Otherwise, you have to convert the values explicitly.  Use `htons'
and `ntohs' to convert values for the `sin_port' member.  Use `htonl'
and `ntohl' to convert values for the `sin_addr' member.  (Remember,
`struct in_addr' is equivalent to `unsigned long int'.)  These
functions are declared in `netinet/in.h'.

 - Function: unsigned short int htons (unsigned short int HOSTSHORT)
     This function converts the `short' integer HOSTSHORT from host
     byte order to network byte order.

 - Function: unsigned short int ntohs (unsigned short int NETSHORT)
     This function converts the `short' integer NETSHORT from network
     byte order to host byte order.

 - Function: unsigned long int htonl (unsigned long int HOSTLONG)
     This function converts the `long' integer HOSTLONG from host byte
     order to network byte order.

 - Function: unsigned long int ntohl (unsigned long int NETLONG)
     This function converts the `long' integer NETLONG from network
     byte order to host byte order.

Protocols Database
------------------

   The communications protocol used with a socket controls low-level
details of how data is exchanged.  For example, the protocol implements
things like checksums to detect errors in transmissions, and routing
instructions for messages.  Normal user programs have little reason to
mess with these details directly.

   The default communications protocol for the Internet namespace
depends on the communication style.  For stream communication, the
default is TCP ("transmission control protocol").  For datagram
communication, the default is UDP ("user datagram protocol").  For
reliable datagram communication, the default is RDP ("reliable datagram
protocol").  You should nearly always use the default.

   Internet protocols are generally specified by a name instead of a
number.  The network protocols that a host knows about are stored in a
database.  This is usually either derived from the file
`/etc/protocols', or it may be an equivalent provided by a name server.
You look up the protocol number associated with a named protocol in
the database using the `getprotobyname' function.

   Here are detailed descriptions of the utilities for accessing the
protocols database.  These are declared in `netdb.h'.

 - Data Type: struct protoent
     This data type is used to represent entries in the network
     protocols database.  It has the following members:

    `char *p_name'
          This is the official name of the protocol.

    `char **p_aliases'
          These are alternate names for the protocol, specified as an
          array of strings.  The last element of the array is a null
          pointer.

    `int p_proto'
          This is the protocol number (in host byte order); use this
          member as the PROTOCOL argument to `socket'.

   You can use `getprotobyname' and `getprotobynumber' to search the
protocols database for a specific protocol.  The information is
returned in a statically-allocated structure; you must copy the
information if you need to save it across calls.

 - Function: struct protoent * getprotobyname (const char *NAME)
     The `getprotobyname' function returns information about the
     network protocol named NAME.  If there is no such protocol, it
     returns a null pointer.

 - Function: struct protoent * getprotobynumber (int PROTOCOL)
     The `getprotobynumber' function returns information about the
     network protocol with number PROTOCOL.  If there is no such
     protocol, it returns a null pointer.

   You can also scan the whole protocols database one protocol at a
time by using `setprotoent', `getprotoent', and `endprotoent'.  Be
careful in using these functions, because they are not reentrant.

 - Function: void setprotoent (int STAYOPEN)
     This function opens the protocols database to begin scanning it.

     If the STAYOPEN argument is nonzero, this sets a flag so that
     subsequent calls to `getprotobyname' or `getprotobynumber' will
     not close the database (as they usually would).  This makes for
     more efficiency if you call those functions several times, by
     avoiding reopening the database for each call.

 - Function: struct protoent * getprotoent (void)
     This function returns the next entry in the protocols database.  It
     returns a null pointer if there are no more entries.

 - Function: void endprotoent (void)
     This function closes the protocols database.

Internet Socket Example
-----------------------

   Here is an example showing how to create and name a socket in the
Internet namespace.  The newly created socket exists on the machine that
the program is running on.  Rather than finding and using the machine's
Internet address, this example specifies `INADDR_ANY' as the host
address; the system replaces that with the machine's actual address.

     #include <stdio.h>
     #include <stdlib.h>
     #include <sys/socket.h>
     #include <netinet/in.h>

     int
     make_socket (unsigned short int port)
     {
       int sock;
       struct sockaddr_in name;

       /* Create the socket. */
       sock = socket (PF_INET, SOCK_STREAM, 0);
       if (sock < 0)
         {
           perror ("socket");
           exit (EXIT_FAILURE);
         }

       /* Give the socket a name. */
       name.sin_family = AF_INET;
       name.sin_port = htons (port);
       name.sin_addr.s_addr = htonl (INADDR_ANY);
       if (bind (sock, (struct sockaddr *) &name, sizeof (name)) < 0)
         {
           perror ("bind");
           exit (EXIT_FAILURE);
         }

       return sock;
     }

   Here is another example, showing how you can fill in a `sockaddr_in'
structure, given a host name string and a port number:

     #include <stdio.h>
     #include <stdlib.h>
     #include <sys/socket.h>
     #include <netinet/in.h>
     #include <netdb.h>

     void
     init_sockaddr (struct sockaddr_in *name,
                    const char *hostname,
                    unsigned short int port)
     {
       struct hostent *hostinfo;

       name->sin_family = AF_INET;
       name->sin_port = htons (port);
       hostinfo = gethostbyname (hostname);
       if (hostinfo == NULL)
         {
           fprintf (stderr, "Unknown host %s.\n", hostname);
           exit (EXIT_FAILURE);
         }
       name->sin_addr = *(struct in_addr *) hostinfo->h_addr;
     }

Other Namespaces
================

   Certain other namespaces and associated protocol families are
supported but not documented yet because they are not often used.
`PF_NS' refers to the Xerox Network Software protocols.  `PF_ISO' stands
for Open Systems Interconnect.  `PF_CCITT' refers to protocols from
CCITT.  `socket.h' defines these symbols and others naming protocols
not actually implemented.

   `PF_IMPLINK' is used for communicating between hosts and Internet
Message Processors.  For information on this, and on `PF_ROUTE', an
occasionally-used local area routing protocol, see the GNU Hurd Manual
(to appear in the future).

Opening and Closing Sockets
===========================

   This section describes the actual library functions for opening and
closing sockets.  The same functions work for all namespaces and
connection styles.

Creating a Socket
-----------------

   The primitive for creating a socket is the `socket' function,
declared in `sys/socket.h'.

 - Function: int socket (int NAMESPACE, int STYLE, int PROTOCOL)
     This function creates a socket and specifies communication style
     STYLE, which should be one of the socket styles listed in
     Communication Styles.  The NAMESPACE argument specifies the
     namespace; it must be `PF_FILE' (see File Namespace.) or
     `PF_INET' (see Internet Namespace.).  PROTOCOL designates the
     specific protocol (see Socket Concepts.); zero is usually
     right for PROTOCOL.

     The return value from `socket' is the file descriptor for the new
     socket, or `-1' in case of error.  The following `errno' error
     conditions are defined for this function:

    `EPROTONOSUPPORT'
          The PROTOCOL or STYLE is not supported by the NAMESPACE
          specified.

    `EMFILE'
          The process already has too many file descriptors open.

    `ENFILE'
          The system already has too many file descriptors open.

    `EACCESS'
          The process does not have privilege to create a socket of the
          specified STYLE or PROTOCOL.

    `ENOBUFS'
          The system ran out of internal buffer space.

     The file descriptor returned by the `socket' function supports both
     read and write operations.  But, like pipes, sockets do not
     support file positioning operations.

   For examples of how to call the `socket' function, see File Namespace,
or Inet Example.

Closing a Socket
----------------

   When you are finished using a socket, you can simply close its file
descriptor with `close'; see Opening and Closing Files.  If
there is still data waiting to be transmitted over the connection,
normally `close' tries to complete this transmission.  You can control
this behavior using the `SO_LINGER' socket option to specify a timeout
period; see Socket Options.

   You can also shut down only reception or only transmission on a
connection by calling `shutdown', which is declared in `sys/socket.h'.

 - Function: int shutdown (int SOCKET, int HOW)
     The `shutdown' function shuts down the connection of socket
     SOCKET.  The argument HOW specifies what action to perform:

    `0'
          Stop receiving data for this socket.  If further data arrives,
          reject it.

    `1'
          Stop trying to transmit data from this socket.  Discard any
          data waiting to be sent.  Stop looking for acknowledgement of
          data already sent; don't retransmit it if it is lost.

    `2'
          Stop both reception and transmission.

     The return value is `0' on success and `-1' on failure.  The
     following `errno' error conditions are defined for this function:

    `EBADF'
          SOCKET is not a valid file descriptor.

    `ENOTSOCK'
          SOCKET is not a socket.

    `ENOTCONN'
          SOCKET is not connected.

Socket Pairs
------------

   A "socket pair" consists of a pair of connected (but unnamed)
sockets.  It is very similar to a pipe and is used in much the same
way.  Socket pairs are created with the `socketpair' function, declared
in `sys/socket.h'.  A socket pair is much like a pipe; the main
difference is that the socket pair is bidirectional, whereas the pipe
has one input-only end and one output-only end (see Pipes and FIFOs.).

 - Function: int socketpair (int NAMESPACE, int STYLE, int PROTOCOL,
          int FILEDES[2])
     This function creates a socket pair, returning the file
     descriptors in `FILEDES[0]' and `FILEDES[1]'.  The socket pair is
     a full-duplex communications channel, so that both reading and
     writing may be performed at either end.

     The NAMESPACE, STYLE, and PROTOCOL arguments are interpreted as
     for the `socket' function.  STYLE should be one of the
     communication styles listed in Communication Styles.  The
     NAMESPACE argument specifies the namespace, which must be
     `AF_FILE' (see File Namespace.); PROTOCOL specifies the
     communications protocol, but zero is the only meaningful value.

     If STYLE specifies a connectionless communication style, then the
     two sockets you get are not *connected*, strictly speaking, but
     each of them knows the other as the default destination address,
     so they can send packets to each other.

     The `socketpair' function returns `0' on success and `-1' on
     failure.  The following `errno' error conditions are defined for
     this function:

    `EMFILE'
          The process has too many file descriptors open.

    `EAFNOSUPPORT'
          The specified namespace is not supported.

    `EPROTONOSUPPORT'
          The specified protocol is not supported.

    `EOPNOTSUPP'
          The specified protocol does not support the creation of
          socket pairs.

Using Sockets with Connections
==============================

   The most common communication styles involve making a connection to a
particular other socket, and then exchanging data with that socket over
and over.  Making a connection is asymmetric; one side (the "client")
acts to request a connection, while the other side (the "server") makes
a socket and waits for the connection request.

Making a Connection
-------------------

   In making a connection, the client makes a connection while the
server waits for and accepts the connection.  Here we discuss what the
client program must do, using the `connect' function, which is declared
in `sys/socket.h'.

 - Function: int connect (int SOCKET, struct sockaddr *ADDR, size_t
          LENGTH)
     The `connect' function initiates a connection from the socket with
     file descriptor SOCKET to the socket whose address is specified by
     the ADDR and LENGTH arguments.  (This socket is typically on
     another machine, and it must be already set up as a server.)
     See Socket Addresses, for information about how these
     arguments are interpreted.

     Normally, `connect' waits until the server responds to the request
     before it returns.  You can set nonblocking mode on the socket
     SOCKET to make `connect' return immediately without waiting for
     the response.  See File Status Flags, for information about
     nonblocking mode.

     The normal return value from `connect' is `0'.  If an error
     occurs, `connect' returns `-1'.  The following `errno' error
     conditions are defined for this function:

    `EBADF'
          The socket SOCKET is not a valid file descriptor.

    `ENOTSOCK'
          The socket SOCKET is not a socket.

    `EADDRNOTAVAIL'
          The specified address is not available on the remote machine.

    `EAFNOSUPPORT'
          The namespace of the ADDR is not supported by this socket.

    `EISCONN'
          The socket SOCKET is already connected.

    `ETIMEDOUT'
          The attempt to establish the connection timed out.

    `ECONNREFUSED'
          The server has actively refused to establish the connection.

    `ENETUNREACH'
          The network of the given ADDR isn't reachable from this host.

    `EADDRINUSE'
          The socket address of the given ADDR is already in use.

    `EINPROGRESS'
          The socket SOCKET is non-blocking and the connection could
          not be established immediately.

    `EALREADY'
          The socket SOCKET is non-blocking and already has a pending
          connection in progress.

Listening for Connections
-------------------------

   Now let us consider what the server process must do to accept
connections on a socket.  First it must use the `listen' function to
enable connection requests on the socket, and then accept each incoming
connection with a call to `accept' (see Accepting Connections.).
Once connection requests are enabled on a server socket, the `select'
function reports when the socket has a connection ready to be accepted
(see Waiting for I/O.).

   The `listen' function is not allowed for sockets using
connectionless communication styles.

   You can write a network server that does not even start running
until a connection to it is requested.  See Inetd Servers.

   In the Internet namespace, there are no special protection mechanisms
for controlling access to connect to a port; any process on any machine
can make a connection to your server.  If you want to restrict access to
your server, make it examine the addresses associated with connection
requests or implement some other handshaking or identification protocol.

   In the File namespace, the ordinary file protection bits control who
has access to connect to the socket.

 - Function: int listen (int SOCKET, unsigned int N)
     The `listen' function enables the socket SOCKET to accept
     connections, thus making it a server socket.

     The argument N specifies the length of the queue for pending
     connections.  When the queue fills, new clients attempting to
     connect fail with `ECONNREFUSED' until the server calls `accept' to
     accept a connection from the queue.

     The `listen' function returns `0' on success and `-1' on failure.
     The following `errno' error conditions are defined for this
     function:

    `EBADF'
          The argument SOCKET is not a valid file descriptor.

    `ENOTSOCK'
          The argument SOCKET is not a socket.

    `EOPNOTSUPP'
          The socket SOCKET does not support this operation.

Accepting Connections
---------------------

   When a server receives a connection request, it can complete the
connection by accepting the request.  Use the function `accept' to do
this.

   A socket that has been established as a server can accept connection
requests from multiple clients.  The server's original socket *does not
become part* of the connection; instead, `accept' makes a new socket
which participates in the connection.  `accept' returns the descriptor
for this socket.  The server's original socket remains available for
listening for further connection requests.

   The number of pending connection requests on a server socket is
finite.  If connection requests arrive from clients faster than the
server can act upon them, the queue can fill up and additional requests
are refused with a `ECONNREFUSED' error.  You can specify the maximum
length of this queue as an argument to the `listen' function, although
the system may also impose its own internal limit on the length of this
queue.

 - Function: int accept (int SOCKET, struct sockaddr *ADDR, size_t
          *LENGTH-PTR)
     This function is used to accept a connection request on the server
     socket SOCKET.

     The `accept' function waits if there are no connections pending,
     unless the socket SOCKET has nonblocking mode set.  (You can use
     `select' to wait for a pending connection, with a nonblocking
     socket.)  See File Status Flags, for information about
     nonblocking mode.

     The ADDR and LENGTH-PTR arguments are used to return information
     about the name of the client socket that initiated the connection.
     See Socket Addresses, for information about the format of the
     information.

     Accepting a connection does not make SOCKET part of the
     connection.  Instead, it creates a new socket which becomes
     connected.  The normal return value of `accept' is the file
     descriptor for the new socket.

     After `accept', the original socket SOCKET remains open and
     unconnected, and continues listening until you close it.  You can
     accept further connections with SOCKET by calling `accept' again.

     If an error occurs, `accept' returns `-1'.  The following `errno'
     error conditions are defined for this function:

    `EBADF'
          The SOCKET argument is not a valid file descriptor.

    `ENOTSOCK'
          The descriptor SOCKET argument is not a socket.

    `EOPNOTSUPP'
          The descriptor SOCKET does not support this operation.

    `EWOULDBLOCK'
          SOCKET has nonblocking mode set, and there are no pending
          connections immediately available.

   The `accept' function is not allowed for sockets using
connectionless communication styles.

Who is Connected to Me?
-----------------------

 - Function: int getpeername (int SOCKET, struct sockaddr *ADDR, size_t
          *LENGTH-PTR)
     The `getpeername' function returns the address of the socket that
     SOCKET is connected to; it stores the address in the memory space
     specified by ADDR and LENGTH-PTR.  It stores the length of the
     address in `*LENGTH-PTR'.

     See Socket Addresses, for information about the format of the
     address.  In some operating systems, `getpeername' works only for
     sockets in the Internet domain.

     The return value is `0' on success and `-1' on error.  The
     following `errno' error conditions are defined for this function:

    `EBADF'
          The argument SOCKET is not a valid file descriptor.

    `ENOTSOCK'
          The descriptor SOCKET is not a socket.

    `ENOTCONN'
          The socket SOCKET is not connected.

    `ENOBUFS'
          There are not enough internal buffers available.

Transferring Data
-----------------

   Once a socket has been connected to a peer, you can use the ordinary
`read' and `write' operations (see I/O Primitives.) to transfer
data.  A socket is a two-way communications channel, so read and write
operations can be performed at either end.

   There are also some I/O modes that are specific to socket operations.
In order to specify these modes, you must use the `recv' and `send'
functions instead of the more generic `read' and `write' functions.
The `recv' and `send' functions take an additional argument which you
can use to specify various flags to control the special I/O modes.  For
example, you can specify the `MSG_OOB' flag to read or write
out-of-band data, the `MSG_PEEK' flag to peek at input, or the
`MSG_DONTROUTE' flag to control inclusion of routing information on
output.

Sending Data
............

   The `send' function is declared in the header file `sys/socket.h'.
If your FLAGS argument is zero, you can just as well use `write'
instead of `send'; see I/O Primitives.  If the socket was
connected but the connection has broken, you get a `SIGPIPE' signal for
any use of `send' or `write' (see Miscellaneous Signals.).

 - Function: int send (int SOCKET, void *BUFFER, size_t SIZE, int FLAGS)
     The `send' function is like `write', but with the additional flags
     FLAGS.  The possible values of FLAGS are described in Socket Data Options.

     This function returns the number of bytes transmitted, or `-1' on
     failure.  If the socket is nonblocking, then `send' (like `write')
     can return after sending just part of the data.  See File Status Flags,
     for information about nonblocking mode.

     Note, however, that a successful return value merely indicates that
     the message has been sent without error, not necessarily that it
     has been received without error.

     The following `errno' error conditions are defined for this
     function:

    `EBADF'
          The SOCKET argument is not a valid file descriptor.

    `EINTR'
          The operation was interrupted by a signal before any data was
          sent.  See Interrupted Primitives.

    `ENOTSOCK'
          The descriptor SOCKET is not a socket.

    `EMSGSIZE'
          The socket type requires that the message be sent atomically,
          but the message is too large for this to be possible.

    `EWOULDBLOCK'
          Nonblocking mode has been set on the socket, and the write
          operation would block.  (Normally `send' blocks until the
          operation can be completed.)

    `ENOBUFS'
          There is not enough internal buffer space available.

    `ENOTCONN'
          You never connected this socket.

    `EPIPE'
          This socket was connected but the connection is now broken.
          In this case, `send' generates a `SIGPIPE' signal first; if
          that signal is ignored or blocked, or if its handler returns,
          then `send' fails with `EPIPE'.