<!-- HEY YOU!!!!!!!!! -->
<!-- this file is automatically generated by the script -->
<!--       ./prepare-manpages.sh      -->
<!-- so PLEASE do not modify it: your changes will be lost -->


<chapter id="tcpip-library-reference">
  <title>TCP/IP Library Reference</title>


  <sect1 id="GETDOMAINNAME">
    <title>GETDOMAINNAME</title>
    <screen>

GETDOMAINNAME(3)          System Programmer's Manual          GETDOMAINNAME(3)

NAME
     getdomainname, setdomainname - get/set YP domain name of current host

SYNOPSIS
     #include &lt;unistd.h>

     int
     getdomainname(char *name, size_t namelen)

     int
     setdomainname(const char *name, size_t namelen)

DESCRIPTION
     The getdomainname() function returns the YP domain name for the current
     processor, as previously set by setdomainname().  The parameter namelen
     specifies the size of the name array.  If insufficient space is provided,
     the returned name is truncated.  The returned name is always null termi-
     nated.

     setdomainname() sets the domain name of the host machine to be name,
     which has length namelen. This call is restricted to the superuser and is
     normally used only when the system is bootstrapped.

RETURN VALUES
     If the call succeeds a value of 0 is returned.  If the call fails, a val-
     ue of -1 is returned and an error code is placed in the global variable
     errno.

ERRORS
     The following errors may be returned by these calls:

     [EFAULT]      The name or namelen parameter gave an invalid address.

     [EPERM]       The caller tried to set the domain name and was not the su-
                   peruser.

SEE ALSO
     domainname(1),  gethostid(3),  gethostname(3),  sysctl(3),  sysctl(8),
     yp(8)

BUGS
     Domain names are limited to MAXHOSTNAMELEN (from &lt;sys/param.h>) charac-
     ters, currently 256.  This includes the terminating NUL character.

     If the buffer passed to getdomainname() is too small, other operating
     systems may not guarantee termination with NUL.

HISTORY
     The getdomainname function call appeared in SunOS 3.x.

BSD Experimental                  May 6, 1994                                1
    </screen>
  </sect1>

  <sect1 id="GETHOSTNAME">
    <title>GETHOSTNAME</title>
    <screen>

GETHOSTNAME(3)            System Programmer's Manual            GETHOSTNAME(3)

NAME
     gethostname, sethostname - get/set name of current host

SYNOPSIS
     #include &lt;unistd.h>

     int
     gethostname(char *name, size_t namelen)

     int
     sethostname(const char *name, size_t namelen)

DESCRIPTION
     The gethostname() function returns the standard host name for the current
     processor, as previously set by sethostname().  The parameter namelen
     specifies the size of the name array.  If insufficient space is provided,
     the returned name is truncated.  The returned name is always null termi-
     nated.

     sethostname() sets the name of the host machine to be name, which has
     length namelen. This call is restricted to the superuser and is normally
     used only when the system is bootstrapped.

RETURN VALUES
     If the call succeeds a value of 0 is returned.  If the call fails, a val-
     ue of -1 is returned and an error code is placed in the global variable
     errno.

ERRORS
     The following errors may be returned by these calls:

     [EFAULT]      The name or namelen parameter gave an invalid address.

     [EPERM]       The caller tried to set the hostname and was not the supe-
                   ruser.

SEE ALSO
     hostname(1),  getdomainname(3),  gethostid(3),  sysctl(3),  sysctl(8),
     yp(8)

STANDARDS
     The gethostname() function call conforms to .

HISTORY
     The gethostname() function call appeared in 4.2BSD.

BUGS
     Host names are limited to MAXHOSTNAMELEN (from &lt;sys/param.h>) characters,
     currently 256.  This includes the terminating NUL character.

     If the buffer passed to gethostname() is smaller than MAXHOSTNAMELEN,
     other operating systems may not guarantee termination with NUL.

BSD Experimental                 June 4, 1993                                1
    </screen>
  </sect1>

  <sect1 id="BYTEORDER">
    <title>BYTEORDER</title>
    <screen>

BYTEORDER(3)              System Programmer's Manual              BYTEORDER(3)

NAME
     htonl, htons, ntohl, ntohs, htobe32, htobe16, betoh32, betoh16, htole32,
     htole16, letoh32, letoh16, swap32, swap16 - convert values between dif-
     ferent byte orderings

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;machine/endian.h>

     u_int32_t
     htonl(u_int32_t host32)

     u_int16_t
     htons(u_int16_t host16)

     u_int32_t
     ntohl(u_int32_t net32)

     u_int16_t
     ntohs(u_int16_t net16)

     u_int32_t
     htobe32(u_int32_t host32)

     u_int16_t
     htobe16(u_int16_t host16)

     u_int32_t
     betoh32(u_int32_t big32)

     u_int16_t
     betoh16(u_int16_t big16)

     u_int32_t
     htole32(u_int32_t host32)

     u_int16_t
     htole16(u_int16_t host16)

     u_int32_t
     letoh32(u_int32_t little32)

     u_int16_t
     letoh16(u_int16_t little16)

     u_int32_t
     swap32(u_int32_t val32)

     u_int16_t
     swap16(u_int16_t val16)

DESCRIPTION
     These routines convert 16- and 32-bit quantities between different byte
     orderings.  The ``swap'' functions reverse the byte ordering of the given
     quantity, the others converts either from/to the native byte order used
     by the host to/from either little- or big-endian (a.k.a network) order.

     Apart from the swap functions, the names can be described by this form:
     {src-order}to{dst-order}{size}.  Both {src-order} and {dst-order} can
     take the following forms:



           h    Host order.
           n    Network order (big-endian).
           be   Big-endian (most significant byte first).
           le   Little-endian (least significant byte first).

     One of the specified orderings must be `h'. {size} will take these forms:

           l    Long (32-bit, used in conjunction with forms involving `n').
           s    Short (16-bit, used in conjunction with forms involving `n').
           16   16-bit.
           32   32-bit.

     The swap functions are of the form: swap{size}.

     Names involving `n' convert quantities between network byte order and
     host byte order.  The last letter (`s' or `l') is a mnemonic for the tra-
     ditional names for such quantities, short and long, respectively.  Today,
     the C concept of short and long integers need not coincide with this tra-
     ditional misunderstanding.  On machines which have a byte order which is
     the same as the network order, routines are defined as null macros.

     The functions involving either ``be'', ``le'', or ``swap'' use the num-
     bers 16 and 32 for specifying the bitwidth of the quantities they operate
     on.  Currently all supported architectures are either big- or little-en-
     dian so either the ``be'' or ``le'' variants are implemented as null
     macros.

     The routines mentioned above which have either {src-order} or {dst-order}
     set to `n' are most often used in conjunction with Internet addresses and
     ports as returned by gethostbyname(3) and getservent(3).

SEE ALSO
     gethostbyname(3),  getservent(3)

HISTORY
     The byteorder functions appeared in 4.2BSD.

BUGS
     On the vax, alpha, i386, and so far mips, bytes are handled backwards
     from most everyone else in the world.  This is not expected to be fixed
     in the near future.

BSD Experimental                 June 4, 1993                                2
    </screen>
  </sect1>

  <sect1 id="ETHERS">
    <title>ETHERS</title>
    <screen>

ETHERS(3)                 System Programmer's Manual                 ETHERS(3)

NAME
     ether_aton, ether_ntoa, ether_addr, ether_ntohost, ether_hostton,
     ether_line - get ethers entry

SYNOPSIS
     #include &lt;netinet/if_ether.h>

     char *
     ether_ntoa(struct ether_addr *e)

     struct ether_addr *
     ether_aton(char *s)

     int
     ether_ntohost(char *hostname, struct ether_addr *e)

     int
     ether_hostton(char *hostname, struct ether_addr *e)

     int
     ether_line(char *l, struct ether_addr *e, char *hostname)

DESCRIPTION
     Ethernet addresses are represented by the following structure:

           struct ether_addr {
                   u_int8_t  ether_addr_octet[6];
           };

     The ether_ntoa() function converts this structure into an ASCII string of
     the form ``xx:xx:xx:xx:xx:xx'', consisting of 6 hexadecimal numbers sepa-
     rated by colons.  It returns a pointer to a static buffer that is reused
     for each call.  The ether_aton() converts an ASCII string of the same
     form and to a structure containing the 6 octets of the address.  It re-
     turns a pointer to a static structure that is reused for each call.

     The ether_ntohost() and ether_hostton() functions interrogate the
     database mapping host names to Ethernet addresses, /etc/ethers. The
     ether_ntohost() function looks up the given Ethernet address and writes
     the associated host name into the character buffer passed.  This buffer
     should be MAXHOSTNAMELEN characters in size.  The ether_hostton() func-
     tion looks up the given host name and writes the associated Ethernet ad-
     dress into the structure passed.  Both functions return zero if they find
     the requested host name or address, and -1 if not.

     Each call reads /etc/ethers from the beginning; if a `+' appears alone on
     a line in the file, then ether_hostton() will consult the ethers.byname
     YP map, and ether_ntohost() will consult the ethers.byaddr YP map.

     The ether_line() function parses a line from the /etc/ethers file and
     fills in the passed struct ether_addr and character buffer with the Eth-
     ernet address and host name on the line.  It returns zero if the line was
     successfully parsed and -1 if not.  The character buffer should be
     MAXHOSTNAMELEN characters in size.

FILES
     /etc/ethers

SEE ALSO
     ethers(5)

HISTORY
     The ether_ntoa(), ether_aton(), ether_ntohost(), ether_hostton(), and
     ether_line() functions were adopted from SunOS and appeared in

BUGS
     The data space used by these functions is static; if future use requires
     the data, it should be copied before any subsequent calls to these func-
     tions overwrite it.

BSD Experimental               December 16, 1993                             2
    </screen>
  </sect1>

  <sect1 id="GETADDRINFO">
    <title>GETADDRINFO</title>
    <screen>

GETADDRINFO(3)            System Programmer's Manual            GETADDRINFO(3)

NAME
     getaddrinfo, freeaddrinfo, gai_strerror - nodename-to-address translation
     in protocol-independent manner

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>
     #include &lt;netdb.h>

     int
     getaddrinfo(const char *nodename, const char *servname,
             const struct addrinfo *hints, struct addrinfo **res)

     void
     freeaddrinfo(struct addrinfo *ai)

     char *
     gai_strerror(int ecode)

DESCRIPTION
     The getaddrinfo() function is defined for protocol-independent nodename-
     to-address translation.  It performs the functionality of gethostby-
     name(3) and getservbyname(3),  but in a more sophisticated manner.

     The addrinfo structure is defined as a result of including the &lt;netdb.h>
     header:

     struct addrinfo {                                                  *
          int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
          int     ai_family;    /* PF_xxx */
          int     ai_socktype;  /* SOCK_xxx */
          int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
          size_t  ai_addrlen;   /* length of ai_addr */
          char   *ai_canonname; /* canonical name for nodename */
          struct sockaddr  *ai_addr; /* binary address */
          struct addrinfo  *ai_next; /* next structure in linked list */
     };

     The nodename and servname arguments are pointers to NUL-terminated
     strings or NULL. One or both of these two arguments must be a non-null
     pointer.  In the normal client scenario, both the nodename and servname
     are specified.  In the normal server scenario, only the servname is spec-
     ified.  A non-null nodename string can be either a node name or a numeric
     host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex
     address).  A non-null servname string can be either a service name or a
     decimal port number.

     The caller can optionally pass an addrinfo structure, pointed to by the
     third argument, to provide hints concerning the type of socket that the
     caller supports.  In this hints structure all members other than
     ai_flags, ai_family, ai_socktype, and ai_protocol must be zero or a null
     pointer.  A value of PF_UNSPEC for ai_family means the caller will accept
     any protocol family.  A value of 0 for ai_socktype means the caller will
     accept any socket type.  A value of 0 for ai_protocol means the caller
     will accept any protocol.  For example, if the caller handles only TCP
     and not UDP, then the ai_socktype member of the hints structure should be
     set to SOCK_STREAM when getaddrinfo() is called.  If the caller handles
     only IPv4 and not IPv6, then the ai_family member of the hints structure
     should be set to PF_INET when getaddrinfo() is called.  If the third ar-
     gument to getaddrinfo() is a null pointer, this is the same as if the
     caller had filled in an addrinfo structure initialized to zero with
     ai_family set to PF_UNSPEC.

     Upon successful return a pointer to a linked list of one or more addrinfo
     structures is returned through the final argument.  The caller can pro-
     cess each addrinfo structure in this list by following the ai_next point-
     er, until a null pointer is encountered.  In each returned addrinfo
     structure the three members ai_family, ai_socktype, and ai_protocol are
     the corresponding arguments for a call to the socket() function.  In each
     addrinfo structure the ai_addr member points to a filled-in socket ad-
     dress structure whose length is specified by the ai_addrlen member.

     If the AI_PASSIVE bit is set in the ai_flags member of the hints struc-
     ture, then the caller plans to use the returned socket address structure
     in a call to bind().  In this case, if the nodename argument is a null
     pointer, then the IP address portion of the socket address structure will
     be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
     address.

     If the AI_PASSIVE bit is not set in the ai_flags member of the hints
     structure, then the returned socket address structure will be ready for a
     call to connect() (for a connection-oriented protocol) or either
     connect(), sendto(), or sendmsg() (for a connectionless protocol). In
     this case, if the nodename argument is a null pointer, then the IP ad-
     dress portion of the socket address structure will be set to the loopback
     address.

     If the AI_CANONNAME bit is set in the ai_flags member of the hints struc-
     ture, then upon successful return the ai_canonname member of the first
     addrinfo structure in the linked list will point to a NUL-terminated
     string containing the canonical name of the specified nodename.

     If the AI_NUMERICHOST bit is set in the ai_flags member of the hints
     structure, then a non-null nodename string must be a numeric host address
     string.  Otherwise an error of EAI_NONAME is returned.  This flag pre-
     vents any type of name resolution service (e.g., the DNS) from being
     called.

     The arguments to getaddrinfo() must sufficiently be consistent and unam-
     biguous.  Here are pitfall cases you may encounter:

     o   getaddrinfo() will raise an error if members of the hints structure
         are not consistent.  For example, for internet address families,
         getaddrinfo() will raise an error if you specify SOCK_STREAM to
         ai_socktype while you specify IPPROTO_UDP to ai_protocol.

     o   If you specify a servname which is defined only for certain
         ai_socktype, getaddrinfo() will raise an error because the arguments
         are not consistent.  For example, getaddrinfo() will raise an error
         if you ask for ``tftp'' service on SOCK_STREAM.

     o   For internet address families, if you specify servname while you set
         ai_socktype to SOCK_RAW, getaddrinfo() will raise an error, because
         service names are not defined for the internet SOCK_RAW space.

     o   If you specify a numeric servname, while leaving ai_socktype and
         ai_protocol unspecified, getaddrinfo() will raise an error.  This is
         because the numeric servname does not identify any socket type, and
         getaddrinfo() is not allowed to glob the argument in such case.

     All of the information returned by getaddrinfo() is dynamically allocat-
     ed: the addrinfo structures, the socket address structures, and canonical
     node name strings pointed to by the addrinfo structures.  To return this
     information to the system the function freeaddrinfo() is called.  The
     addrinfo structure pointed to by the ai argument is freed, along with any
     dynamic storage pointed to by the structure.  This operation is repeated
     until a NULL ai_next pointer is encountered.


     To aid applications in printing error messages based on the EAI_xxx codes
     returned by getaddrinfo(), gai_strerror() is defined.  The argument is
     one of the EAI_xxx values defined earlier and the return value points to
     a string describing the error.  If the argument is not one of the EAI_xxx
     values, the function still returns a pointer to a string whose contents
     indicate an unknown error.

   Extension for scoped IPv6 address
     The implementation allows experimental numeric IPv6 address notation with
     scope identifier.  By appending the percent character and scope identifi-
     er to addresses, you can fill sin6_scope_id field for addresses.  This
     would make management of scoped address easier, and allows cut-and-paste
     input of scoped address.

     At this moment the code supports only link-local addresses with the for-
     mat.  Scope identifier is hardcoded to name of hardware interface associ-
     ated with the link.  (such as ne0). Example would be like
     ``fe80::1%ne0'', which means ``fe80::1 on the link associated with ne0
     interface''.

     The implementation is still very experimental and non-standard.  The cur-
     rent implementation assumes one-by-one relationship between interface and
     link, which is not necessarily true from the specification.

EXAMPLES
     The following code tries to connect to ``www.kame.net'' service ``http''.
     via stream socket.  It loops through all the addresses available, regard-
     less from address family.  If the destination resolves to IPv4 address,
     it will use AF_INET socket.  Similarly, if it resolves to IPv6, AF_INET6
     socket is used.  Observe that there is no hardcoded reference to particu-
     lar address family.  The code works even if getaddrinfo returns addresses
     that are not IPv4/v6.

           struct addrinfo hints, *res, *res0;
           int error;
           int s;
           const char *cause = NULL;

           memset(&amp;hints, 0, sizeof(hints));
           hints.ai_family = PF_UNSPEC;
           hints.ai_socktype = SOCK_STREAM;
           error = getaddrinfo("www.kame.net", "http", &amp;hints, &amp;res0);
           if (error) {
                   errx(1, "%s", gai_strerror(error));
                   /*NOTREACHED*/
           }
           s = -1;
           for (res = res0; res; res = res->ai_next) {
                   s = socket(res->ai_family, res->ai_socktype,
                       res->ai_protocol);
                   if (s &lt; 0) {
                           cause = "socket";
                           continue;
                   }

                   if (connect(s, res->ai_addr, res->ai_addrlen) &lt; 0) {
                           cause = "connect";
                           close(s);
                           s = -1;
                           continue;
                   }

                   break;  /* okay we got one */
           }
           if (s &lt; 0) {
                   err(1, cause);
                   /*NOTREACHED*/
           }
           freeaddrinfo(res0);

     The following example tries to open a wildcard listening socket onto ser-
     vice ``http'', for all the address families available.

           struct addrinfo hints, *res, *res0;
           int error;
           int s[MAXSOCK];
           int nsock;
           const char *cause = NULL;

           memset(&amp;hints, 0, sizeof(hints));
           hints.ai_family = PF_UNSPEC;
           hints.ai_socktype = SOCK_STREAM;
           hints.ai_flags = AI_PASSIVE;
           error = getaddrinfo(NULL, "http", &amp;hints, &amp;res0);
           if (error) {
                   errx(1, "%s", gai_strerror(error));
                   /*NOTREACHED*/
           }
           nsock = 0;
           for (res = res0; res &amp;&amp; nsock &lt; MAXSOCK; res = res->ai_next) {
                   s[nsock] = socket(res->ai_family, res->ai_socktype,
                       res->ai_protocol);
                   if (s[nsock] &lt; 0) {
                           cause = "socket";
                           continue;
                   }

                   if (bind(s[nsock], res->ai_addr, res->ai_addrlen) &lt; 0) {
                           cause = "bind";
                           close(s[nsock]);
                           continue;
                   }
                   (void) listen(s[nsock], 5);

                   nsock++;
           }
           if (nsock == 0) {
                   err(1, cause);
                   /*NOTREACHED*/
           }
           freeaddrinfo(res0);

DIAGNOSTICS
     Error return status from getaddrinfo() is zero on success and non-zero on
     errors.  Non-zero error codes are defined in &lt;netdb.h>, and as follows:

     EAI_ADDRFAMILY  Address family for nodename not supported.
     EAI_AGAIN       Temporary failure in name resolution.
     EAI_BADFLAGS    Invalid value for ai_flags.
     EAI_FAIL        Non-recoverable failure in name resolution.
     EAI_FAMILY      ai_family not supported.
     EAI_MEMORY      Memory allocation failure.
     EAI_NODATA      No address associated with nodename.
     EAI_NONAME      nodename nor servname provided, or not known.
     EAI_SERVICE     servname not supported for ai_socktype.
     EAI_SOCKTYPE    ai_socktype not supported.
     EAI_SYSTEM      System error returned in errno.

     If called with proper argument, gai_strerror() returns a pointer to a
     string describing the given error code.  If the argument is not one of
     the EAI_xxx values, the function still returns a pointer to a string
     whose contents indicate an unknown error.

SEE ALSO
     getnameinfo(3),  gethostbyname(3),  getservbyname(3),  hosts(5),
     resolv.conf(5),  services(5),  hostname(7),  named(8)

     R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
     Extensions for IPv6, RFC2553, March 1999.

     Tatsuya Jinmei, and Atsushi Onoe, An Extension of Format for IPv6 Scoped
     Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-format-02.txt,
     work in progress material.

     Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
     the freenix track: 2000 USENIX annual technical conference, June 2000.

HISTORY
     The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
     kit.

STANDARDS
     The getaddrinfo() function is defined in IEEE POSIX 1003.1g draft speci-
     fication, and documented in ``Basic Socket Interface Extensions for
     IPv6'' (RFC2553).

BUGS
     The current implementation is not thread-safe.

     The text was shamelessly copied from RFC2553.

BSD Experimental                 May 25, 1995                                5
    </screen>
  </sect1>

  <sect1 id="GETHOSTBYNAME">
    <title>GETHOSTBYNAME</title>
    <screen>

GETHOSTBYNAME(3)          System Programmer's Manual          GETHOSTBYNAME(3)

NAME
     gethostbyname, gethostbyname2, gethostbyaddr, gethostent, sethostent,
     endhostent, hstrerror, herror - get network host entry

SYNOPSIS
     #include &lt;netdb.h>
     extern int h_errno;

     struct hostent *
     gethostbyname(const char *name)

     struct hostent *
     gethostbyname2(const char *name, int af)

     struct hostent *
     gethostbyaddr(const char *addr, int len, int af)

     struct hostent *
     gethostent(void)

     void
     sethostent(int stayopen)

     void
     endhostent(void)

     void
     herror(const char *string)

     const char *
     hstrerror(int err)

DESCRIPTION
     The gethostbyname() and gethostbyaddr() functions each return a pointer
     to an object with the following structure describing an internet host
     referenced by name or by address, respectively.  This structure contains
     either information obtained from the name server (i.e., resolver(3) and
     named(8)),  broken-out fields from a line in /etc/hosts, or database en-
     tries supplied by the yp(8) system.  resolv.conf(5) describes how the
     particular database is chosen.

     struct  hostent {
             char    *h_name;        /* official name of host */
             char    **h_aliases;    /* alias list */
             int     h_addrtype;     /* host address type */
             int     h_length;       /* length of address */
             char    **h_addr_list;  /* list of addresses from name server */
     };
     #define h_addr  h_addr_list[0]  /* address, for backward compatibility */

     The members of this structure are:

     h_name       Official name of the host.

     h_aliases    A zero-terminated array of alternate names for the host.

     h_addrtype   The type of address being returned.

     h_length     The length, in bytes, of the address.

     h_addr_list  A zero-terminated array of network addresses for the host.

                  Host addresses are returned in network byte order.

     h_addr       The first address in h_addr_list; this is for backward com-
                  patibility.

     The function gethostbyname() will search for the named host in the cur-
     rent domain and its parents using the search lookup semantics detailed in
     resolv.conf(5) and hostname(7).

     gethostbyname2() is an advanced form of gethostbyname() which allows
     lookups in address families other than AF_INET, for example AF_INET6.

     The gethostbyaddr() function will search for the specified address of
     length len in the address family af. The only address family currently
     supported is AF_INET.

     The sethostent() function may be used to request the use of a connected
     TCP socket for queries.  If the stayopen flag is non-zero, this sets the
     option to send all queries to the name server using TCP and to retain the
     connection after each call to gethostbyname() or gethostbyaddr().  Other-
     wise, queries are performed using UDP datagrams.

     The endhostent() function closes the TCP connection.

     The herror() function prints an error message describing the failure.  If
     its argument string is non-null, it is prepended to the message string
     and separated from it by a colon (`:') and a space.  The error message is
     printed with a trailing newline.  The contents of the error message is
     the same as that returned by hstrerror() with argument h_errno.

FILES
     /etc/hosts
     /etc/resolv.conf

DIAGNOSTICS
     Error return status from gethostbyname(), gethostbyname2(), and
     gethostbyaddr() is indicated by return of a null pointer.  The external
     integer h_errno may then be checked to see whether this is a temporary
     failure or an invalid or unknown host.

     The variable h_errno can have the following values:

     HOST_NOT_FOUND  No such host is known.

     TRY_AGAIN       This is usually a temporary error and means that the lo-
                     cal server did not receive a response from an authorita-
                     tive server.  A retry at some later time may succeed.

     NO_RECOVERY     Some unexpected server failure was encountered.  This is
                     a non-recoverable error.

     NO_DATA         The requested name is valid but does not have an IP ad-
                     dress; this is not a temporary error.  This means that
                     the name is known to the name server but there is no ad-
                     dress associated with this name.  Another type of request
                     to the name server using this domain name will result in
                     an answer; for example, a mail-forwarder may be regis-
                     tered for this domain.

SEE ALSO
     resolver(3),  getaddrinfo(3),  getnameinfo(3),  hosts(5),
     resolv.conf(5),  hostname(7),  named(8)

CAVEAT
     If the search routines in resolv.conf(5) decide to read the /etc/hosts
     file, gethostent() and other functions will read the next line of the
     file, re-opening the file if necessary.

     The sethostent() function opens and/or rewinds the file /etc/hosts. If
     the stayopen argument is non-zero, the file will not be closed after each
     call to gethostbyname(), gethostbyname2(), or gethostbyaddr().

     The endhostent() function closes the file.

HISTORY
     The herror() function appeared in 4.3BSD. The endhostent(),
     gethostbyaddr(), gethostbyname(), gethostent(), and sethostent() func-
     tions appeared in 4.2BSD.

BUGS
     These functions use static data storage; if the data is needed for future
     use, it should be copied before any subsequent calls overwrite it.  Only
     the Internet address formats are currently understood.

     YP does not support any address families other than AF_INET and uses the
     traditional database format.

BSD Experimental                March 13, 1997                               3
    </screen>
  </sect1>

  <sect1 id="GETIFADDRS">
    <title>GETIFADDRS</title>
    <screen>

GETIFADDRS(3)             System Programmer's Manual             GETIFADDRS(3)

NAME
     getifaddrs - get interface addresses

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>
     #include &lt;ifaddrs.h>

     int
     getifaddrs(struct ifaddrs **ifap)

     void
     freeifaddrs(struct ifaddrs *ifap)

DESCRIPTION
     The getifaddrs() function stores a reference to a linked list of the net-
     work interfaces on the local machine in the memory referenced by ifap.
     The list consists of ifaddrs structures, as defined in the include file
     &lt;ifaddrs.h>. The ifaddrs structure contains at least the following en-
     tries:

         struct ifaddrs   *ifa_next;         /* Pointer to next struct */
         char             *ifa_name;         /* Interface name */
         u_int             ifa_flags;        /* Interface flags */
         struct sockaddr  *ifa_addr;         /* Interface address */
         struct sockaddr  *ifa_netmask;      /* Interface netmask */
         struct sockaddr  *ifa_broadaddr;    /* Interface broadcast address */
         struct sockaddr  *ifa_dstaddr;      /* P2P interface destination */
         void             *ifa_data;         /* Address specific data */

     ifa_next
             Contains a pointer to the next structure on the list.  This field
             is set to NULL in last structure on the list.

     ifa_name
             Contains the interface name.

     ifa_flags
             Contains the interface flags, as set by ifconfig(8).

     ifa_addr
             References either the address of the interface or the link level
             address of the interface, if one exists, otherwise it is NULL.
             (The sa_family field of the ifa_addr field should be consulted to
             determine the format of the ifa_addr address.)

     ifa_netmask
             References the netmask associated with ifa_addr, if one is set,
             otherwise it is NULL.

     ifa_broadaddr
             This field, which should only be referenced for non-P2P inter-
             faces, references the broadcast address associated with ifa_addr,
             if one exists, otherwise it is NULL.

     ifa_dstaddr
             References the destination address on a P2P interface, if one ex-
             ists, otherwise it is NULL.

     ifa_data
             References address family specific data.  For AF_LINK addresses
             it contains a pointer to the struct if_data (as defined in in-
             clude file &lt;net/if.h>) which contains various interface at-
             tributes and statistics.  For all other address families, it con-
             tains a pointer to the struct ifa_data (as defined in include
             file &lt;net/if.h>) which contains per-address interface statistics.

     The data returned by getifaddrs() is dynamically allocated and should be
     freed using freeifaddrs() when no longer needed.

RETURN VALUES
     Upon successful completion, a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.

ERRORS
     The getifaddrs() may fail and set errno for any of the errors specified
     for the library routines ioctl(2),  socket(2),  malloc(3),  or sysctl(3).


BUGS
     If both &lt;net/if.h> and &lt;ifaddrs.h> are being included, &lt;net/if.h> must be
     included before &lt;ifaddrs.h>.

SEE ALSO
     ioctl(2),  socket(2),  sysctl(3),  networking(4),  ifconfig(8)

HISTORY
     The getifaddrs() function first appeared in BSDI BSD/OS.  The function is
     supplied on since

                                January 4, 2002                              2
    </screen>
  </sect1>

  <sect1 id="GETNAMEINFO">
    <title>GETNAMEINFO</title>
    <screen>

GETNAMEINFO(3)            System Programmer's Manual            GETNAMEINFO(3)

NAME
     getnameinfo - address-to-nodename translation in protocol-independent
     manner

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>
     #include &lt;netdb.h>

     int
     getnameinfo(const struct sockaddr *sa, socklen_t salen, char *host,
             size_t hostlen, char *serv, size_t servlen, int flags)

DESCRIPTION
     The getnameinfo() function is defined for protocol-independent address-
     to-nodename translation.  Its functionality is a reverse conversion of
     getaddrinfo(3),  and implements similar functionality with gethostbyad-
     dr(3) and getservbyport(3) in more sophisticated manner.

     This function looks up an IP address and port number provided by the
     caller in the DNS and system-specific database, and returns text strings
     for both in buffers provided by the caller.  The function indicates suc-
     cessful completion by a zero return value; a non-zero return value indi-
     cates failure.

     The first argument, sa, points to either a sockaddr_in structure (for
     IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP address
     and port number.  The salen argument gives the length of the sockaddr_in
     or sockaddr_in6 structure.

     The function returns the nodename associated with the IP address in the
     buffer pointed to by the host argument.  The caller provides the size of
     this buffer via the hostlen argument.  The service name associated with
     the port number is returned in the buffer pointed to by serv, and the
     servlen argument gives the length of this buffer.  The caller specifies
     not to return either string by providing a zero value for the hostlen or
     servlen arguments.  Otherwise, the caller must provide buffers large
     enough to hold the nodename and the service name, including the terminat-
     ing null characters.

     Unfortunately most systems do not provide constants that specify the max-
     imum size of either a fully-qualified domain name or a service name.
     Therefore to aid the application in allocating buffers for these two re-
     turned strings the following constants are defined in &lt;netdb.h>:

     #define NI_MAXHOST    MAXHOSTNAMELEN
     #define NI_MAXSERV    32

     The first value is actually defined as the constant MAXDNAME in recent
     versions of BIND's &lt;arpa/nameser.h> header (older versions of BIND define
     this constant to be 256) and the second is a guess based on the services
     listed in the current Assigned Numbers RFC.

     The final argument is a flag that changes the default actions of this
     function.  By default the fully-qualified domain name (FQDN) for the host
     is looked up in the DNS and returned.  If the flag bit NI_NOFQDN is set,
     only the nodename portion of the FQDN is returned for local hosts.

     If the flag bit NI_NUMERICHOST is set, or if the host's name cannot be
     located in the DNS, the numeric form of the host's address is returned
     instead of its name (e.g., by calling inet_ntop() instead of
     gethostbyaddr()). If the flag bit NI_NAMEREQD is set, an error is re-
     turned if the host's name cannot be located in the DNS.

     If the flag bit NI_NUMERICSERV is set, the numeric form of the service
     address is returned (e.g., its port number) instead of its name.  The two
     NI_NUMERICxxx flags are required to support the -n flag that many com-
     mands provide.

     A fifth flag bit, NI_DGRAM, specifies that the service is a datagram ser-
     vice, and causes getservbyport() to be called with a second argument of
     "udp" instead of its default of "tcp". This is required for the few ports
     (512-514) that have different services for UDP and TCP.

     These NI_xxx flags are defined in &lt;netdb.h>.

   Extension for scoped IPv6 address
     The implementation allows experimental numeric IPv6 address notation with
     scope identifier.  IPv6 link-local address will appear as string like
     ``fe80::1%ne0'', if NI_WITHSCOPEID bit is enabled in flags argument.  Re-
     fer to getaddrinfo(3) for the notation.

EXAMPLES
     The following code tries to get numeric hostname, and service name, for
     given socket address.  Observe that there is no hardcoded reference to
     particular address family.

           struct sockaddr *sa;    /* input */
           char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];

           if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
               sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
                   errx(1, "could not get numeric hostname");
                   /*NOTREACHED*/
           }
           printf("host=%s, serv=%s\n", hbuf, sbuf);

     The following version checks if the socket address has reverse address
     mapping.

           struct sockaddr *sa;    /* input */
           char hbuf[NI_MAXHOST];

           if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
               NI_NAMEREQD)) {
                   errx(1, "could not resolve hostname");
                   /*NOTREACHED*/
           }
           printf("host=%s\n", hbuf);

DIAGNOSTICS
     The function indicates successful completion by a zero return value; a
     non-zero return value indicates failure.  Error codes are as below:

     EAI_AGAIN     The name could not be resolved at this time.  Future at-
                   tempts may succeed.

     EAI_BADFLAGS  The flags had an invalid value.

     EAI_FAIL      A non-recoverable error occurred.

     EAI_FAMILY    The address family was not recognized or the address length
                   was invalid for the specified family.

     EAI_MEMORY    There was a memory allocation failure.

     EAI_NONAME    The name does not resolve for the supplied parameters.
                   NI_NAMEREQD is set and the host's name cannot be located,

                   or both nodename and servname were null.

     EAI_SYSTEM    A system error occurred.  The error code can be found in
                   errno.

SEE ALSO
     getaddrinfo(3),  gethostbyaddr(3),  getservbyport(3),  hosts(5),
     resolv.conf(5),  services(5),  hostname(7),  named(8)

     R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
     Extensions for IPv6, RFC2553, March 1999.

     Tatsuya Jinmei, and Atsushi Onoe, An Extension of Format for IPv6 Scoped
     Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-format-02.txt,
     work in progress material.

     Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
     the freenix track: 2000 USENIX annual technical conference, June 2000.

HISTORY
     The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
     kit.

STANDARDS
     The getaddrinfo() function is defined IEEE POSIX 1003.1g draft specifica-
     tion, and documented in ``Basic Socket Interface Extensions for IPv6''
     (RFC2553).

BUGS
     The current implementation is not thread-safe.

     The text was shamelessly copied from RFC2553.

     intentionally uses different NI_MAXHOST value from what RFC2553 suggests,
     to avoid buffer length handling mistakes.

BSD Experimental                 May 25, 1995                                3
    </screen>
  </sect1>

  <sect1 id="GETNETENT">
    <title>GETNETENT</title>
    <screen>

GETNETENT(3)              System Programmer's Manual              GETNETENT(3)

NAME
     getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent - get network
     entry

SYNOPSIS
     #include &lt;netdb.h>

     struct netent *
     getnetent(void)

     struct netent *
     getnetbyname(char *name)

     struct netent *
     getnetbyaddr(in_addr_t net, int type)

     void
     setnetent(int stayopen)

     void
     endnetent(void)

DESCRIPTION
     The getnetent(), getnetbyname(), and getnetbyaddr() functions each return
     a pointer to an object with the following structure containing the bro-
     ken-out fields of a line in the network database, /etc/networks.

           struct  netent {
                   char            *n_name;        /* official name of net */
                   char            **n_aliases;    /* alias list */
                   int             n_addrtype;     /* net number type */
                   in_addr_t       n_net;          /* net number */
           };

     The members of this structure are:

     n_name      The official name of the network.

     n_aliases   A zero-terminated list of alternate names for the network.

     n_addrtype  The type of the network number returned; currently only
                 AF_INET.

     n_net       The network number.  Network numbers are returned in machine
                 byte order.

     The getnetent() function reads the next line of the file, opening the
     file if necessary.

     The setnetent() function opens and rewinds the file.  If the stayopen
     flag is non-zero, the net database will not be closed after each call to
     getnetbyname() or getnetbyaddr().

     The endnetent() function closes the file.

     The getnetbyname() and getnetbyaddr() functions search the domain name
     server if the system is configured to use one.  If the search fails, or
     no name server is configured, they sequentially search from the beginning
     of the file until a matching net name or net address and type is found,
     or until EOF is encountered.  Network numbers are supplied in host order.

FILES

     /etc/networks

DIAGNOSTICS
     Null pointer (0) returned on EOF or error.

SEE ALSO
     resolver(3),  networks(5)

HISTORY
     The getnetent(), getnetbyaddr(), getnetbyname(), setnetent(), and
     endnetent() functions appeared in 4.2BSD.

BUGS
     The data space used by these functions is static; if future use requires
     the data, it should be copied before any subsequent calls to these func-
     tions overwrite it.  Only Internet network numbers are currently under-
     stood.  Expecting network numbers to fit in no more than 32 bits is
     naive.

BSD Experimental                March 13, 1997                               2
    </screen>
  </sect1>

  <sect1 id="GETPROTOENT">
    <title>GETPROTOENT</title>
    <screen>

GETPROTOENT(3)            System Programmer's Manual            GETPROTOENT(3)

NAME
     getprotoent, getprotobynumber, getprotobyname, setprotoent, endprotoent -
     get protocol entry

SYNOPSIS
     #include &lt;netdb.h>

     struct protoent *
     getprotoent(void)

     struct protoent *
     getprotobyname(char *name)

     struct protoent *
     getprotobynumber(int proto)

     void
     setprotoent(int stayopen)

     void
     endprotoent(void)

DESCRIPTION
     The getprotoent(), getprotobyname(), and getprotobynumber() functions
     each return a pointer to an object with the following structure contain-
     ing the broken-out fields of a line in the network protocol database,
     /etc/protocols.


           struct  protoent {
                   char    *p_name;        /* official name of protocol */
                   char    **p_aliases;    /* alias list */
                   int     p_proto;        /* protocol number */
           };

     The members of this structure are:

     p_name     The official name of the protocol.

     p_aliases  A zero-terminated list of alternate names for the protocol.

     p_proto    The protocol number.

     The getprotoent() function reads the next line of the file, opening the
     file if necessary.

     The setprotoent() function opens and rewinds the file.  If the stayopen
     flag is non-zero, the net database will not be closed after each call to
     getprotobyname() or getprotobynumber().

     The endprotoent() function closes the file.

     The getprotobyname() and getprotobynumber() functions sequentially search
     from the beginning of the file until a matching protocol name or protocol
     number is found, or until EOF is encountered.

RETURN VALUES
     Null pointer (0) returned on EOF or error.

FILES


     /etc/protocols

SEE ALSO
     protocols(5)

HISTORY
     The getprotoent(), getprotobynumber(), getprotobyname(), setprotoent(),
     and endprotoent() functions appeared in 4.2BSD.

BUGS
     These functions use a static data space; if the data is needed for future
     use, it should be copied before any subsequent calls overwrite it.  Only
     the Internet protocols are currently understood.

BSD Experimental                 June 4, 1993                                2
    </screen>
  </sect1>

  <sect1 id="GETRRSETBYNAME">
    <title>GETRRSETBYNAME</title>
    <screen>

GETRRSETBYNAME(3)         System Programmer's Manual         GETRRSETBYNAME(3)

NAME
     getrrsetbyname - retrieve DNS records

SYNOPSIS
     #include &lt;netdb.h>

     int
     getrrsetbyname(const char *hostname, unsigned int rdclass,
             unsigned int rdtype, unsigned int flags, struct rrsetinfo **res)

     int
     freerrset(struct rrsetinfo **rrset)

DESCRIPTION
     getrrsetbyname() gets a set of resource records associated with a
     hostname, class and type. hostname is a pointer a to null-terminated
     string.  The flags field is currently unused and must be zero.

     After a successful call to getrrsetbyname(), *res is a pointer to an
     rrsetinfo structure, containing a list of one or more rdatainfo struc-
     tures containing resource records and potentially another list of
     rdatainfo structures containing SIG resource records associated with
     those records.  The members rri_rdclass and rri_rdtype are copied from
     the parameters.  rri_ttl and rri_name are properties of the obtained
     rrset.  The resource records contained in rri_rdatas and rri_sigs are in
     uncompressed DNS wire format.  Properties of the rdataset are represented
     in the rri_flags bitfield. If the RRSET_VALIDATED bit is set, the data
     has been DNSSEC validated and the signatures verified.

     The following structures are used:

     struct  rdatainfo {
             unsigned int            rdi_length;     /* length of data */
             unsigned char           *rdi_data;      /* record data */
     };

     struct  rrsetinfo {
             unsigned int            rri_flags;      /* RRSET_VALIDATED ... */
             unsigned int            rri_rdclass;    /* class number */
             unsigned int            rri_rdtype;     /* RR type number */
             unsigned int            rri_ttl;        /* time to live */
             unsigned int            rri_nrdatas;    /* size of rdatas array */
             unsigned int            rri_nsigs;      /* size of sigs array */
             char                    *rri_name;      /* canonical name */
             struct rdatainfo        *rri_rdatas;    /* individual records */
             struct rdatainfo        *rri_sigs;      /* individual signatures */
     };

     All of the information returned by getrrsetbyname() is dynamically allo-
     cated: the rrsetinfo and rdatainfo structures, and the canonical host
     name strings pointed to by the rrsetinfostructure. Memory allocated for
     the dynamically allocated structures created by a successful call to
     getrrsetbyname() is released by freerrset().  rrset is a pointer to a
     struct rrset created by a call to getrrsetbyname().

     If the EDNS0 option is activated in resolv.conf(3),  getrrsetbyname()
     will request DNSSEC authentication using the EDNS0 DNSSEC OK (DO) bit.

RETURN VALUES
     getrrsetbyname() returns zero on success, and one of the following error
     codes if an error occurred:


     ERRSET_NONAME    the name does not exist
     ERRSET_NODATA    the name exists, but does not have data of the desired
                      type
     ERRSET_NOMEMORY  memory could not be allocated
     ERRSET_INVAL     a parameter is invalid
     ERRSET_FAIL      other failure

SEE ALSO
     resolver(3),  resolv.conf(5),  named(8)

AUTHORS
     Jakob Schlyter &lt;jakob@openbsd.org>

HISTORY
     getrrsetbyname() first appeared in The API first appeared in ISC BIND
     version 9.

BUGS
     The data in *rdi_data should be returned in uncompressed wire format.
     Currently, the data is in compressed format and the caller can't uncom-
     press since it doesn't have the full message.

CAVEATS
     The RRSET_VALIDATED flag in rri_flags is set if the AD (autenticated da-
     ta) bit in the DNS answer is set. This flag should not be trusted unless
     the transport between the nameserver and the resolver is secure (e.g.
     IPsec, trusted network, loopback communication).

BSD Experimental                 Oct 18, 2000                                2
    </screen>
  </sect1>

  <sect1 id="GETSERVENT">
    <title>GETSERVENT</title>
    <screen>

GETSERVENT(3)             System Programmer's Manual             GETSERVENT(3)

NAME
     getservent, getservbyport, getservbyname, setservent, endservent - get
     service entry

SYNOPSIS
     #include &lt;netdb.h>

     struct servent *
     getservent(void)

     struct servent *
     getservbyname(char *name, char *proto)

     struct servent *
     getservbyport(int port, char *proto)

     void
     setservent(int stayopen)

     void
     endservent(void)

DESCRIPTION
     The getservent(), getservbyname(), and getservbyport() functions each re-
     turn a pointer to an object with the following structure containing the
     broken-out fields of a line in the network services database,
     /etc/services.

           struct  servent {
                   char    *s_name;        /* official name of service */
                   char    **s_aliases;    /* alias list */
                   int     s_port;         /* port service resides at */
                   char    *s_proto;       /* protocol to use */
           };

     The members of this structure are:

     s_name     The official name of the service.

     s_aliases  A zero-terminated list of alternate names for the service.

     s_port     The port number at which the service resides.  Port numbers
                are returned in network byte order.

     s_proto    The name of the protocol to use when contacting the service.

     The getservent() function reads the next line of the file, opening the
     file if necessary.

     The setservent() function opens and rewinds the file.  If the stayopen
     flag is non-zero, the net database will not be closed after each call to
     getservbyname() or getservbyport().

     The endservent() function closes the file.

     The getservbyname() and getservbyport() functions sequentially search
     from the beginning of the file until a matching protocol name or port
     number (specified in network byte order) is found, or until EOF is en-
     countered.  If a protocol name is also supplied (non-null), searches must
     also match the protocol.

FILES

     /etc/services

DIAGNOSTICS
     Null pointer (0) returned on EOF or error.

SEE ALSO
     getprotoent(3),  services(5)

HISTORY
     The getservent(), getservbyport(), getservbyname(), setservent(), and
     endservent() functions appeared in 4.2BSD.

BUGS
     These functions use static data storage; if the data is needed for future
     use, it should be copied before any subsequent calls overwrite it.  Ex-
     pecting port numbers to fit in a 32-bit quantity is probably naive.

BSD Experimental               January 12, 1994                              2
    </screen>
  </sect1>

  <sect1 id="IF-NAMETOINDEX">
    <title>IF_NAMETOINDEX</title>
    <screen>

IF_NAMETOINDEX(3)         System Programmer's Manual         IF_NAMETOINDEX(3)

NAME
     if_nametoindex, if_indextoname, if_nameindex, if_freenameindex - convert
     interface index to name, and vice versa

SYNOPSIS
     #include &lt;net/if.h>

     unsigned int
     if_nametoindex(const char *ifname)

     char *
     if_indextoname(unsigned int ifindex, char *ifname)

     struct if_nameindex *
     if_nameindex(void)

     void
     if_freenameindex(struct if_nameindex *ptr)

DESCRIPTION
     These functions map interface indexes to interface names (such as
     ``lo0''), and vice versa.

     The if_nametoindex() function converts an interface name specified by the
     ifname argument to an interface index (positive integer value).  If the
     specified interface does not exist, 0 will be returned.

     if_indextoname() converts an interface index specified by the ifindex ar-
     gument to an interface name.  The ifname argument must point to a buffer
     of at least IF_NAMESIZE bytes into which the interface name corresponding
     to the specified index is returned.  (IF_NAMESIZE is also defined in
     &lt;net/if.h> and its value includes a terminating null byte at the end of
     the interface name.)  This pointer is also the return value of the func-
     tion.  If there is no interface corresponding to the specified index,
     NULL is returned.

     if_nameindex() returns an array of if_nameindex structures.
     if_nametoindex is also defined in &lt;net/if.h>, and is as follows:

     struct if_nameindex {
         unsigned int   if_index;  /* 1, 2, ... */
         char          *if_name;   /* null terminated name: "le0", ... */
     };

     The end of the array of structures is indicated by a structure with an
     if_index of 0 and an if_name of NULL. The function returns a null pointer
     on error.  The memory used for this array of structures along with the
     interface names pointed to by the if_name members is obtained dynamical-
     ly.  This memory is freed by the if_freenameindex() function.

     if_freenameindex() takes a pointer that was returned by if_nameindex() as
     argument (ptr), and it reclaims the region allocated.

DIAGNOSTICS
     if_nametoindex() returns 0 on error, positive integer on success.
     if_indextoname() and if_nameindex() return NULL on errors.

SEE ALSO
     R. Gilligan, S.  Thomson, J. Bound, and W. Stevens, ``Basic Socket Inter-
     face Extensions for IPv6,'' RFC2553, March 1999.

STANDARDS
     These functions are defined in ``Basic Socket Interface Extensions for
     IPv6'' (RFC2533).

BSD Experimental                 May 21, 1998                                2
    </screen>
  </sect1>

  <sect1 id="INET">
    <title>INET</title>
    <screen>

INET(3)                   System Programmer's Manual                   INET(3)

NAME
     inet_addr, inet_aton, inet_lnaof, inet_makeaddr, inet_netof,
     inet_network, inet_ntoa, inet_ntop, inet_pton - Internet address manipu-
     lation routines

SYNOPSIS
     #include &lt;sys/socket.h>
     #include &lt;netinet/in.h>
     #include &lt;arpa/inet.h>

     in_addr_t
     inet_addr(const char *cp)

     int
     inet_aton(const char *cp, struct in_addr *addr)

     in_addr_t
     inet_lnaof(struct in_addr in)

     struct in_addr
     inet_makeaddr(unsigned long net, unsigned long lna)

     in_addr_t
     inet_netof(struct in_addr in)

     in_addr_t
     inet_network(const char *cp)

     char *
     inet_ntoa(struct in_addr in)

     const char *
     inet_ntop(int af, const void *src, char *dst, size_t size)

     int
     inet_pton(int af, const char *src, void *dst)

DESCRIPTION
     The routines inet_aton(), inet_addr() and inet_network() interpret char-
     acter strings representing numbers expressed in the Internet standard `.'
     notation.  The inet_pton() function converts a presentation format ad-
     dress (that is, printable form as held in a character string) to network
     format (usually a struct in_addr or some other internal binary represen-
     tation, in network byte order).  It returns 1 if the address was valid
     for the specified address family, or 0 if the address wasn't parseable in
     the specified address family, or -1 if some system error occurred (in
     which case errno will have been set).  This function is presently valid
     for AF_INET and AF_INET6. The inet_aton() routine interprets the speci-
     fied character string as an Internet address, placing the address into
     the structure provided.  It returns 1 if the string was successfully in-
     terpreted, or 0 if the string was invalid.  The inet_addr() and
     inet_network() functions return numbers suitable for use as Internet ad-
     dresses and Internet network numbers, respectively.

     The function inet_ntop() converts an address from network format (usually
     a struct in_addr or some other binary form, in network byte order) to
     presentation format (suitable for external display purposes).  It returns
     NULL if a system error occurs (in which case, errno will have been set),
     or it returns a pointer to the destination string.  The routine
     inet_ntoa() takes an Internet address and returns an ASCII string repre-
     senting the address in `.' notation.  The routine inet_makeaddr() takes
     an Internet network number and a local network address and constructs an
     Internet address from it.  The routines inet_netof() and inet_lnaof()
     break apart Internet host addresses, returning the network number and lo-
     cal network address part, respectively.

     All Internet addresses are returned in network order (bytes ordered from
     left to right).  All network numbers and local address parts are returned
     as machine format integer values.

INTERNET ADDRESSES (IP VERSION 4)
     Values specified using the `.' notation take one of the following forms:

           a.b.c.d
           a.b.c
           a.b
           a

     When four parts are specified, each is interpreted as a byte of data and
     assigned, from left to right, to the four bytes of an Internet address.
     Note that when an Internet address is viewed as a 32-bit integer quantity
     on a system that uses little-endian byte order (such as the Intel 386,
     486 and Pentium processors) the bytes referred to above appear as
     ``d.c.b.a''. That is, little-endian bytes are ordered from right to left.

     When a three part address is specified, the last part is interpreted as a
     16-bit quantity and placed in the rightmost two bytes of the network ad-
     dress.  This makes the three part address format convenient for specify-
     ing Class B network addresses as ``128.net.host''.

     When a two part address is supplied, the last part is interpreted as a
     24-bit quantity and placed in the rightmost three bytes of the network
     address.  This makes the two part address format convenient for specify-
     ing Class A network addresses as ``net.host''.

     When only one part is given, the value is stored directly in the network
     address without any byte rearrangement.

     All numbers supplied as ``parts'' in a `.' notation may be decimal, oc-
     tal, or hexadecimal, as specified in the C language (i.e., a leading 0x
     or 0X implies hexadecimal; otherwise, a leading 0 implies octal; other-
     wise, the number is interpreted as decimal).

INTERNET ADDRESSES (IP VERSION 6)
     In order to support scoped IPv6 addresses, getaddrinfo(3) and getnamein-
     fo(3) are recommended rather than the functions presented here.

     The presentation format of an IPv6 address is given in [RFC1884 2.2]:

     There are three conventional forms for representing IPv6 addresses as
     text strings:

     1.   The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the hex-
          adecimal values of the eight 16-bit pieces of the address.  Exam-
          ples:

                FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
                1080:0:0:0:8:800:200C:417A

          Note that it is not necessary to write the leading zeros in an indi-
          vidual field, but there must be at least one numeral in every field
          (except for the case described in 2.).

     2.   Due to the method of allocating certain styles of IPv6 addresses, it
          will be common for addresses to contain long strings of zero bits.
          In order to make writing addresses


          containing zero bits easier a special syntax is available to com-
          press the zeros.  The use of ``::'' indicates multiple groups of 16
          bits of zeros.  The ``::'' can only appear once in an address.  The
          ``::'' can also be used to compress the leading and/or trailing ze-
          ros in an address.

          For example the following addresses:

                1080:0:0:0:8:800:200C:417A  a unicast address
                FF01:0:0:0:0:0:0:43         a multicast address
                0:0:0:0:0:0:0:1             the loopback address
                0:0:0:0:0:0:0:0             the unspecified addresses

          may be represented as:

                1080::8:800:200C:417A       a unicast address
                FF01::43                    a multicast address
                ::1                         the loopback address
                ::                          the unspecified addresses

     3.   An alternative form that is sometimes more convenient when dealing
          with a mixed environment of IPv4 and IPv6 nodes is
          x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values of
          the six high-order 16-bit pieces of the address, and the 'd's are
          the decimal values of the four low-order 8-bit pieces of the address
          (standard IPv4 representation).  Examples:

                0:0:0:0:0:0:13.1.68.3
                0:0:0:0:0:FFFF:129.144.52.38

          or in compressed form:

                ::13.1.68.3
                ::FFFF:129.144.52.38

DIAGNOSTICS
     The constant INADDR_NONE is returned by inet_addr() and inet_network()
     for malformed requests.

SEE ALSO
     byteorder(3),  gethostbyname(3),  getnetent(3),  inet_net(3),  hosts(5),
     networks(5)

STANDARDS
     The inet_ntop and inet_pton functions conforms to the IETF IPv6 BSD API
     and address formatting specifications.  Note that inet_pton does not ac-
     cept 1-, 2-, or 3-part dotted addresses; all four parts must be speci-
     fied.  This is a narrower input set than that accepted by inet_aton.

HISTORY
     The inet_addr, inet_network, inet_makeaddr, inet_lnaof and inet_netof
     functions appeared in 4.2BSD. The inet_aton and inet_ntoa functions ap-
     peared in 4.3BSD. The inet_pton and inet_ntop functions appeared in BIND
     4.9.4.

BUGS
     The value INADDR_NONE (0xffffffff) is a valid broadcast address, but
     inet_addr() cannot return that value without indicating failure.  Also,
     inet_addr() should have been designed to return a struct in_addr. The
     newer inet_aton() function does not share these problems, and almost all
     existing code should be modified to use inet_aton() instead.

     The problem of host byte ordering versus network byte ordering is confus-
     ing.


     The string returned by inet_ntoa() resides in a static memory area.
    </screen>
  </sect1>

  <sect1 id="INET6-OPTION-SPACE">
    <title>INET6_OPTION_SPACE</title>
    <screen>

INET6_OPTION_SPACE(3)     System Programmer's Manual     INET6_OPTION_SPACE(3)

NAME
     inet6_option_space, inet6_option_init, inet6_option_append,
     inet6_option_alloc, inet6_option_next, inet6_option_find - IPv6 Hop-by-
     Hop and Destination Options manipulation

SYNOPSIS
     #include &lt;netinet/in.h>

     int
     inet6_option_space(int nbytes)

     int
     inet6_option_init(void *bp, struct cmsghdr **cmsgp, int type)

     int
     inet6_option_append(struct cmsghdr *cmsg, const u_int8_t *typep,
             int multx, int plusy)

     u_int8_t *
     inet6_option_alloc(struct cmsghdr *cmsg, int datalen, int multx,
             int plusy);

     int
     inet6_option_next(const struct cmsghdr *cmsg, u_int8_t **tptrp)

     int
     inet6_option_find(const struct cmsghdr *cmsg, u_int8_t **tptrp, int type)

DESCRIPTION
     Building and parsing the Hop-by-Hop and Destination options is complicat-
     ed due to alignment constranints, padding and ancillary data manipula-
     tion.  RFC2292 defines a set of functions to help the application.  The
     function prototypes for these functions are all in the &lt;netinet/in.h>
     header.

   inet6_option_space
     inet6_option_space() returns the number of bytes required to hold an op-
     tion when it is stored as ancillary data, including the cmsghdr structure
     at the beginning, and any padding at the end (to make its size a multiple
     of 8 bytes). The argument is the size of the structure defining the op-
     tion, which must include any pad bytes at the beginning (the value y in
     the alignment term ``xn + y''), the type byte, the length byte, and the
     option data.

     Note: If multiple options are stored in a single ancillary data object,
     which is the recommended technique, this function overestimates the
     amount of space required by the size of N-1 cmsghdr structures, where N
     is the number of options to be stored in the object.  This is of little
     consequence, since it is assumed that most Hop-by-Hop option headers and
     Destination option headers carry only one option (appendix B of
     [RFC-2460]).

   inet6_option_init
     inet6_option_init() is called once per ancillary data object that will
     contain either Hop-by-Hop or Destination options.  It returns 0 on suc-
     cess or -1 on an error.

     bp is a pointer to previously allocated space that will contain the an-
     cillary data object.  It must be large enough to contain all the individ-
     ual options to be added by later calls to inet6_option_append() and
     inet6_option_alloc().


     cmsgp is a pointer to a pointer to a cmsghdr structure.  *cmsgp is ini-
     tialized by this function to point to the cmsghdr structure constructed
     by this function in the buffer pointed to by bp.

     type is either IPV6_HOPOPTS or IPV6_DSTOPTS. This type is stored in the
     cmsg_type member of the cmsghdr structure pointed to by *cmsgp.

   inet6_option_append
     This function appends a Hop-by-Hop option or a Destination option into an
     ancillary data object that has been initialized by inet6_option_init().
     This function returns 0 if it succeeds or -1 on an error.

     cmsg is a pointer to the cmsghdr structure that must have been initial-
     ized by inet6_option_init().

     typep is a pointer to the 8-bit option type.  It is assumed that this
     field is immediately followed by the 8-bit option data length field,
     which is then followed immediately by the option data.  The caller ini-
     tializes these three fields (the type-length-value, or TLV) before call-
     ing this function.

     The option type must have a value from 2 to 255, inclusive.  (0 and 1 are
     reserved for the Pad1 and PadN options, respectively.)

     The option data length must have a value between 0 and 255, inclusive,
     and is the length of the option data that follows.

     multx is the value x in the alignment term ``xn + y''. It must have a
     value of 1, 2, 4, or 8.

     plusy is the value y in the alignment term ``xn + y''. It must have a
     value between 0 and 7, inclusive.

   inet6_option_alloc
     This function appends a Hop-by-Hop option or a Destination option into an
     ancillary data object that has been initialized by inet6_option_init().
     This function returns a pointer to the 8-bit option type field that
     starts the option on success, or NULL on an error.

     The difference between this function and inet6_option_append() is that
     the latter copies the contents of a previously built option into the an-
     cillary data object while the current function returns a pointer to the
     space in the data object where the option's TLV must then be built by the
     caller.

     cmsg is a pointer to the cmsghdr structure that must have been initial-
     ized by inet6_option_init().

     datalen is the value of the option data length byte for this option.
     This value is required as an argument to allow the function to determine
     if padding must be appended at the end of the option.  argument  since
     the option data length must already be stored by the caller. (The
     inet6_option_append() function does not need  a  data  length)

     multx is the value x in the alignment term ``xn + y''. It must have a
     value of 1, 2, 4, or 8.

     plusy is the value y in the alignment term ``xn + y''. It must have a
     value between 0 and 7, inclusive.

   inet6_option_next
     This function processes the next Hop-by-Hop option or Destination option
     in an ancillary data object.  If another option remains to be processed,
     the return value of the function is 0 and *tptrp points to the 8-bit op-
     tion type field the option data (which  is  followed  by the 8-bit option
     data length, followed by). If no more options remain to be processed, the
     return value is -1 and *tptrp is NULL. If an error occurs, the return
     value is -1 and *tptrp is not NULL.

     cmsg is a pointer to cmsghdr structure of which cmsg_level equals
     IPPROTO_IPV6 and cmsg_type equals either IPV6_HOPOPTS or IPV6_DSTOPTS.

     tptrp is a pointer to a pointer to an 8-bit byte and *tptrp is used by
     the function to remember its place in the ancillary data object each time
     the function is called.  The first time this function is called for a
     given ancillary data object, *tptrp must be set to NULL.

     Each time this function returns success, *tptrp points to the 8-bit op-
     tion type field for the next option to be processed.

   inet6_option_find
     This function is similar to the previously described inet6_option_next()
     function, except this function lets the caller specify the option type to
     be searched for, instead of always returning the next option in the an-
     cillary data object.  cmsg is a pointer to cmsghdr structure of which
     cmsg_level equals IPPROTO_IPV6 and cmsg_type equals either IPV6_HOPOPTS
     or IPV6_DSTOPTS.

     tptrp is a pointer to a pointer to an 8-bit byte and *tptrp is used by
     the function to remember its place in the ancillary data object each time
     the function is called.  The first time this function is called for a
     given ancillary data object, *tptrp must be set to NULL. ~ This function
     starts searching for an option of the specified type beginning after the
     value of *tptrp. If an option of the specified type is located, this
     function returns 0 and *tptrp points to the 8- bit option type field for
     the option of the specified type.  If an option of the specified type is
     not located, the return value is -1 and *tptrp is NULL. If an error oc-
     curs, the return value is -1 and *tptrp is not NULL.

DIAGNOSTICS
     inet6_option_init() and inet6_option_append() return 0 on success or -1
     on an error.

     inet6_option_alloc() returns NULL on an error.

     On errors, inet6_option_next() and inet6_option_find() return -1 setting
     *tptrp to non NULL value.

EXAMPLES
     RFC2292 gives comprehensive examples in chapter 6.

SEE ALSO
     W. Stevens, and M. Thomas, Advanced Sockets API for IPv6, RFC2292,
     February 1998.

     S. Deering, and R. Hinden, Internet Protocol, Version 6 (IPv6)
     Specification, RFC2460, December 1998.

HISTORY
     The implementation first appeared in KAME advanced networking kit.

STANDARDS
     The functions are documented in ``Advanced Sockets API for IPv6''
     (RFC2292).

BUGS
     The text was shamelessly copied from RFC2292.

BSD Experimental               December 10, 1999                             3
    </screen>
  </sect1>

  <sect1 id="INET6-RTHDR-SPACE">
    <title>INET6_RTHDR_SPACE</title>
    <screen>

INET6_RTHDR_SPACE(3)      System Programmer's Manual      INET6_RTHDR_SPACE(3)

NAME
     inet6_rthdr_space, inet6_rthdr_init, inet6_rthdr_add,
     inet6_rthdr_lasthop, inet6_rthdr_reverse, inet6_rthdr_segments,
     inet6_rthdr_getaddr, inet6_rthdr_getflags - IPv6 Routing Header Options
     manipulation

SYNOPSIS
     #include &lt;netinet/in.h>

     size_t
     inet6_rthdr_space(int type, int segments)

     struct cmsghdr *
     inet6_rthdr_init(void *bp, int type)

     int
     inet6_rthdr_add(struct cmsghdr *cmsg, const struct in6_addr *addr,
             unsigned int flags)

     int
     inet6_rthdr_lasthop(struct cmsghdr *cmsg, unsigned int flags)

     int
     inet6_rthdr_reverse(const struct cmsghdr *in, struct cmsghdr *out)

     int
     inet6_rthdr_segments(const struct cmsghdr *cmsg)

     struct in6_addr *
     inet6_rthdr_getaddr(struct cmsghdr *cmsg, int index)

     int
     inet6_rthdr_getflags(const struct cmsghdr *cmsg, int index)

DESCRIPTION
     RFC2292 IPv6 advanced API defines eight functions that the application
     calls to build and examine a Routing header.  Four functions build a
     Routing header:

     inet6_rthdr_space() return #bytes required for ancillary data

     inet6_rthdr_init() initialize ancillary data for Routing header

     inet6_rthdr_add() add IPv6 address &amp; flags to Routing header

     inet6_rthdr_lasthop() specify the flags for the final hop

     Four functions deal with a returned Routing header:

     inet6_rthdr_reverse() reverse a Routing header

     inet6_rthdr_segments() return #segments in a Routing header

     inet6_rthdr_getaddr() fetch one address from a Routing header

     inet6_rthdr_getflags() fetch one flag from a Routing header

     The function prototypes for these functions are all in the &lt;netinet/in.h>
     header.

   inet6_rthdr_space
     This function returns the number of bytes required to hold a Routing
     header of the specified type containing the specified number of segments
     (addresses). For an IPv6 Type 0 Routing header, the number of segments
     must be between 1 and 23, inclusive.  The return value includes the size
     of the cmsghdr structure that precedes the Routing header, and any re-
     quired padding.

     If the return value is 0, then either the type of the Routing header is
     not supported by this implementation or the number of segments is invalid
     for this type of Routing header.

     Note: This function returns the size but does not allocate the space re-
     quired for the ancillary data.  This allows an application to allocate a
     larger buffer, if other ancillary data objects are desired, since all the
     ancillary data objects must be specified to sendmsg(2) as a single
     msg_control buffer.

   inet6_rthdr_init
     This function initializes the buffer pointed to by bp to contain a
     cmsghdr structure followed by a Routing header of the specified type. The
     cmsg_len member of the cmsghdr structure is initialized to the size of
     the structure plus the amount of space required by the Routing header.
     The cmsg_level and cmsg_type members are also initialized as required.

     The caller must allocate the buffer and its size can be determined by
     calling inet6_rthdr_space().

     Upon success the return value is the pointer to the cmsghdr structure,
     and this is then used as the first argument to the next two functions.
     Upon an error the return value is NULL.

   inet6_rthdr_add
     This function adds the address pointed to by addr to the end of the Rout-
     ing header being constructed and sets the type of this hop to the value
     of flags. For an IPv6 Type 0 Routing header, flags must be either
     IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.

     If successful, the cmsg_len member of the cmsghdr structure is updated to
     account for the new address in the Routing header and the return value of
     the function is 0.  Upon an error the return value of the function is -1.

   inet6_rthdr_lasthop
     This function specifies the Strict/Loose flag for the final hop of a
     Routing header.  For an IPv6 Type 0 Routing header, flags must be either
     IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.

     The return value of the function is 0 upon success, or -1 upon an error.

     Notice that a Routing header specifying N intermediate nodes requires N+1
     Strict/Loose flags.  This requires N calls to inet6_rthdr_add() followed
     by one call to inet6_rthdr_lasthop().

   inet6_rthdr_reverse
     This function takes a Routing header that was received as ancillary data
     (pointed to by the first argument, in) and writes a new Routing header
     that sends datagrams along the reverse of that route.  Both arguments are
     allowed to point to the same buffer (that is, the reversal can occur in
     place).

     The return value of the function is 0 on success, or -1 upon an error.

   inet6_rthdr_segments
     This function returns the number of segments (addresses) contained in the
     Routing header described by cmsg. On success the return value is between
     1 and 23, inclusive.  The return value of the function is -1 upon an er-
     ror.


   inet6_rthdr_getaddr
     This function returns a pointer to the IPv6 address specified by index
     inet6_rthdr_segments() (which must have a value between  1  and  the
     value  returned  by) in the Routing header described by cmsg. An applica-
     tion should first call inet6_rthdr_segments() to obtain the number of
     segments in the Routing header.

     Upon an error the return value of the function is NULL.

   inet6_rthdr_getflags
     This function returns the flags value specified by index
     inet6_rthdr_segments() (which  must  have  a  value  between  0 and the
     value returned by) in the Routing header described by cmsg. For an IPv6
     Type 0 Routing header the return value will be either IPV6_RTHDR_LOOSE or
     IPV6_RTHDR_STRICT.

     Upon an error the return value of the function is -1.

     Note: Addresses are indexed starting at 1, and flags starting at 0, to
     maintain consistency with the terminology and figures in RFC2460.

DIAGNOSTICS
     inet6_rthdr_space() returns 0 on errors.

     inet6_rthdr_add(), inet6_rthdr_lasthop() and inet6_rthdr_reverse() return
     0 on success, and returns -1 on error.

     inet6_rthdr_init() and inet6_rthdr_getaddr() return NULL on error.

     inet6_rthdr_segments() and inet6_rthdr_getflags() return -1 on error.

EXAMPLES
     RFC2292 gives comprehensive examples in chapter 8.

SEE ALSO
     W. Stevens, and M. Thomas, Advanced Sockets API for IPv6, RFC2292,
     February 1998.

     S. Deering, and R. Hinden, Internet Protocol, Version 6 (IPv6)
     Specification, RFC2460, December 1998.

HISTORY
     The implementation first appeared in KAME advanced networking kit.

STANDARDS
     The functions are documented in ``Advanced Sockets API for IPv6''
     (RFC2292).

BUGS
     The text was shamelessly copied from RFC2292.

     inet6_rthdr_reverse() is not implemented yet.

BSD Experimental               December 10, 1999                             3
    </screen>
  </sect1>

  <sect1 id="INET-NET">
    <title>INET_NET</title>
    <screen>

INET_NET(3)               System Programmer's Manual               INET_NET(3)

NAME
     inet_net_ntop, inet_net_pton - Internet network number manipulation rou-
     tines

SYNOPSIS
     #include &lt;sys/socket.h>
     #include &lt;netinet/in.h>
     #include &lt;arpa/inet.h>

     char *
     inet_net_ntop(int af, const void *src, int bits, char *dst, size_t size)

     int
     inet_net_pton(int af, const char *src, void *dst, size_t size)

DESCRIPTION
     The inet_net_ntop() function converts an Internet network number from
     network format (usually a struct in_addr or some other binary form, in
     network byte order) to CIDR presentation format (suitable for external
     display purposes).  bits is the number of bits in src that are the net-
     work number.  It returns NULL if a system error occurs (in which case,
     errno will have been set), or it returns a pointer to the destination
     string.

     The inet_net_pton() function converts a presentation format Internet net-
     work number (that is, printable form as held in a character string) to
     network format (usually a struct in_addr or some other internal binary
     representation, in network byte order).  It returns the number of bits
     (either computed based on the class, or specified with /CIDR), or -1 if a
     failure occurred (in which case errno will have been set.  It will be set
     to ENOENT if the Internet network number was not valid).

     The only value for af currently supported is AF_INET. size is the size of
     the result buffer dst.

NETWORK NUMBERS (IP VERSION 4)
     Internet network numbers may be specified in one of the following forms:

           a.b.c.d/bits
           a.b.c.d
           a.b.c
           a.b
           a

     When four parts are specified, each is interpreted as a byte of data and
     assigned, from left to right, to the four bytes of an Internet network
     number.  Note that when an Internet network number is viewed as a 32-bit
     integer quantity on a system that uses little-endian byte order (such as
     the Intel 386, 486, and Pentium processors) the bytes referred to above
     appear as ``d.c.b.a''. That is, little-endian bytes are ordered from
     right to left.

     When a three part number is specified, the last part is interpreted as a
     16-bit quantity and placed in the rightmost two bytes of the Internet
     network number.  This makes the three part number format convenient for
     specifying Class B network numbers as ``128.net.host''.

     When a two part number is supplied, the last part is interpreted as a
     24-bit quantity and placed in the rightmost three bytes of the Internet
     network number.  This makes the two part number format convenient for
     specifying Class A network numbers as ``net.host''.


     When only one part is given, the value is stored directly in the Internet
     network number without any byte rearrangement.

     All numbers supplied as ``parts'' in a `.' notation may be decimal, oc-
     tal, or hexadecimal, as specified in the C language (i.e., a leading 0x
     or 0X implies hexadecimal; otherwise, a leading 0 implies octal; other-
     wise, the number is interpreted as decimal).

SEE ALSO
     byteorder(3),  inet(3),  networks(5)

HISTORY
     The inet_net_ntop and inet_net_pton functions first appeared in BIND
     4.9.4.

BSD Experimental                 June 18, 1997                               2
    </screen>
  </sect1>

  <sect1 id="IPX">
    <title>IPX</title>
    <screen>

IPX(3)                    System Programmer's Manual                    IPX(3)

NAME
     ipx_addr, ipx_ntoa - IPX address conversion routines

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;netipx/ipx.h>

     struct ipx_addr
     ipx_addr(const char *cp)

     char *
     ipx_ntoa(struct ipx_addr ipx)

DESCRIPTION
     The routine ipx_addr() interprets character strings representing IPX ad-
     dresses, returning binary information suitable for use in system calls.
     The routine ipx_ntoa() takes IPX addresses and returns ASCII strings rep-
     resenting the address in a notation in common use:

           &lt;network number>.&lt;host number>.&lt;port number>

     Trailing zero fields are suppressed, and each number is printed in hex-
     adecimal, in a format suitable for input to ipx_addr().  Any fields lack-
     ing super-decimal digits will have a trailing `H' appended.

     An effort has been made to ensure that ipx_addr() be compatible with most
     formats in common use.  It will first separate an address into 1 to 3
     fields using a single delimiter chosen from period (`.'), colon (`:'), or
     pound-sign (`#'). Each field is then examined for byte separators (colon
     or period).  If there are byte separators, each subfield separated is
     taken to be a small hexadecimal number, and the entirety is taken as a
     network-byte-ordered quantity to be zero extended in the high-network-or-
     der bytes.  Next, the field is inspected for hyphens, in which case the
     field is assumed to be a number in decimal notation with hyphens separat-
     ing the millenia.  Next, the field is assumed to be a number: It is in-
     terpreted as hexadecimal if there is a leading `0x' (as in C), a trailing
     `H' (as in Mesa), or there are any super-decimal digits present.  It is
     interpreted as octal is there is a leading `0' and there are no super-oc-
     tal digits.  Otherwise, it is converted as a decimal number.

RETURN VALUES
     None.  (See BUGS.)

SEE ALSO
     ns(4),  hosts(5),  networks(5)

HISTORY
     The precursor ns_addr() and ns_ntoa() functions appeared in 4.3BSD.

BUGS
     The string returned by ipx_ntoa() resides in a static memory area.  The
     function ipx_addr() should diagnose improperly formed input, and there
     should be an unambiguous way to recognize this.

BSD Experimental                 June 4, 1993                                1
    </screen>
  </sect1>

  <sect1 id="ISO-ADDR">
    <title>ISO_ADDR</title>
    <screen>

ISO_ADDR(3)               System Programmer's Manual               ISO_ADDR(3)

NAME
     iso_addr, iso_ntoa - network address conversion routines for Open System
     Interconnection

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;netiso/iso.h>

     struct iso_addr *
     iso_addr(char *cp)

     char *
     iso_ntoa(struct iso_addr *isoa)

DESCRIPTION
     The routine iso_addr() interprets character strings representing OSI ad-
     dresses, returning binary information suitable for use in system calls.
     The routine iso_ntoa() takes OSI addresses and returns ASCII strings rep-
     resenting NSAPs (network service access points) in a notation inverse to
     that accepted by iso_addr().

     Unfortunately, no universal standard exists for representing OSI network
     addresses.

     The format employed by iso_addr() is a sequence of hexadecimal ``digits''
     (optionally separated by periods), of the form:

           &lt;hex digits>.&lt;hex digits>.&lt;hex digits>

     Each pair of hexadecimal digits represents a byte with the leading digit
     indicating the higher-ordered bits.  A period following an even number of
     bytes has no effect (but may be used to increase legibility).  A period
     following an odd number of bytes has the effect of causing the byte of
     address being translated to have its higher order bits filled with zeros.

RETURN VALUES
     iso_ntoa() always returns a null terminated string.  iso_addr() always
     returns a pointer to a struct iso_addr. (See BUGS.)

SEE ALSO
     iso(4)

HISTORY
     The iso_addr() and iso_ntoa() functions appeared in 4.3BSD-Reno.

BUGS
     The returned values reside in a static memory area.

     The function iso_addr() should diagnose improperly formed input, and
     there should be an unambiguous way to recognize this.

BSD Experimental                 June 4, 1993                                1
    </screen>
  </sect1>

  <sect1 id="LINK-ADDR">
    <title>LINK_ADDR</title>
    <screen>

LINK_ADDR(3)              System Programmer's Manual              LINK_ADDR(3)

NAME
     link_addr, link_ntoa - elementary address specification routines for link
     level access

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>
     #include &lt;net/if_dl.h>

     void
     link_addr(const char *addr, struct sockaddr_dl *sdl)

     char *
     link_ntoa(const struct sockaddr_dl *sdl)

DESCRIPTION
     The link_addr() function interprets character strings representing link-
     level addresses, returning binary information suitable for use in system
     calls.  link_ntoa() takes a link-level address and returns an ASCII
     string representing some of the information present, including the link
     level address itself, and the interface name or number, if present.  This
     facility is experimental and is still subject to change.

     For link_addr(), the string addr may contain an optional network inter-
     face identifier of the form ``name unit-number'', suitable for the first
     argument to ifconfig(8),  followed in all cases by a colon and an inter-
     face address in the form of groups of hexadecimal digits separated by pe-
     riods.  Each group represents a byte of address; address bytes are filled
     left to right from low order bytes through high order bytes.

     Thus le0:8.0.9.13.d.30 represents an Ethernet address to be transmitted
     on the first Lance Ethernet interface.

RETURN VALUES
     link_ntoa() always returns a null-terminated string.  link_addr() has no
     return value.  (See BUGS.)

SEE ALSO
     iso(4),  ifconfig(8)

HISTORY
     The link_addr() and link_ntoa() functions appeared in 4.3BSD-Reno.

BUGS
     The returned values for link_ntoa reside in a static memory area.

     The function link_addr() should diagnose improperly formed input, and
     there should be an unambiguous way to recognize this.

     If the sdl_len field of the link socket address sdl is 0, link_ntoa()
     will not insert a colon before the interface address bytes.  If this
     translated address is given to link_addr() without inserting an initial
     colon, the latter will not interpret it correctly.

BSD Experimental                 July 28, 1993                               1
    </screen>
  </sect1>

  <sect1 id="NET-ADDRCMP">
    <title>NET_ADDRCMP</title>
    <screen>

NET_ADDRCMP(3)            System Programmer's Manual            NET_ADDRCMP(3)

NAME
     net_addrcmp - compare socket address structures

SYNOPSIS
     #include &lt;netdb.h>

     int
     net_addrcmp(struct sockaddr *sa1, struct sockaddr *sa2)

DESCRIPTION
     The net_addrcmp() function compares two socket address structures, sa1
     and sa2.

RETURN VALUES
     If sa1 and sa2 are for the same address, net_addrcmp() returns 0.

     The sa_len fields are compared first.  If they do not match,
     net_addrcmp() returns -1 or 1 if sa1->sa_len is less than or greater than
     sa2->sa_len, respectively.

     Next, the sa_family members are compared.  If they do not match,
     net_addrcmp() returns -1 or 1 if sa1->sa_family is less than or greater
     than sa2->sa_family, respectively.

     Lastly, if each socket address structure's sa_len and sa_family fields
     match, the protocol-specific data (the sa_data field) is compared.  If
     there's a match, both sa1 and sa2 must refer to the same address, and 0
     is returned; otherwise, a value >0 or &lt;0 is returned.

HISTORY
     A net_addrcmp() function was added in

BSD Experimental                 July 3, 1999                                1
    </screen>
  </sect1>

  <sect1 id="NS">
    <title>NS</title>
    <screen>

NS(3)                     System Programmer's Manual                     NS(3)

NAME
     ns_addr, ns_ntoa - Xerox NS(tm) address conversion routines

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;netns/ns.h>

     struct ns_addr
     ns_addr(char *cp)

     char *
     ns_ntoa(struct ns_addr ns)

DESCRIPTION
     The routine ns_addr() interprets character strings representing XNS ad-
     dresses, returning binary information suitable for use in system calls.
     The routine ns_ntoa() takes XNS addresses and returns ASCII strings rep-
     resenting the address in a notation in common use in the Xerox Develop-
     ment Environment:

           &lt;network number>.&lt;host number>.&lt;port number>

     Trailing zero fields are suppressed, and each number is printed in hex-
     adecimal, in a format suitable for input to ns_addr().  Any fields lack-
     ing super-decimal digits will have a trailing `H' appended.

     Unfortunately, no universal standard exists for representing XNS address-
     es.  An effort has been made to ensure that ns_addr() be compatible with
     most formats in common use.  It will first separate an address into 1 to
     3 fields using a single delimiter chosen from period (`.'), colon (`:'),
     or pound-sign `#'. Each field is then examined for byte separators (colon
     or period).  If there are byte separators, each subfield separated is
     taken to be a small hexadecimal number, and the entirety is taken as a
     network-byte-ordered quantity to be zero extended in the high-network-or-
     der bytes.  Next, the field is inspected for hyphens, in which case the
     field is assumed to be a number in decimal notation with hyphens separat-
     ing the millenia.  Next, the field is assumed to be a number: It is in-
     terpreted as hexadecimal if there is a leading `0x' (as in C), a trailing
     `H' (as in Mesa), or there are any super-decimal digits present.  It is
     interpreted as octal is there is a leading `0' and there are no super-oc-
     tal digits.  Otherwise, it is converted as a decimal number.

RETURN VALUES
     None.  (See BUGS.)

SEE ALSO
     hosts(5),  networks(5)

HISTORY
     The ns_addr() and ns_toa() functions appeared in 4.3BSD.

BUGS
     The string returned by ns_ntoa() resides in a static memory area.  The
     function ns_addr() should diagnose improperly formed input, and there
     should be an unambiguous way to recognize this.

BSD Experimental                 June 4, 1993                                1
    </screen>
  </sect1>

  <sect1 id="RESOLVER">
    <title>RESOLVER</title>
    <screen>

RESOLVER(3)               System Programmer's Manual               RESOLVER(3)

NAME
     res_query, res_search, res_mkquery, res_send, res_init, dn_comp,
     dn_expand - resolver routines

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;netinet/in.h>
     #include &lt;arpa/nameser.h>
     #include &lt;resolv.h>

     int
     res_query(char *dname, int class, int type, u_char *answer, int anslen)

     int
     res_search(char *dname, int class, int type, u_char *answer, int anslen)

     int
     res_mkquery(int op, char *dname, int class, int type, char *data,
             int datalen, struct rrec *newrr, char *buf, int buflen)

     int
     res_send(char *msg, int msglen, char *answer, int anslen)

     int
     res_init(void)

     int
     dn_comp(char *exp_dn, char *comp_dn, int length, char **dnptrs,
             char **lastdnptr)

     int
     dn_expand(u_char *msg, u_char *eomorig, u_char *comp_dn, u_char *exp_dn,
             int length)

DESCRIPTION
     These routines are used for making, sending, and interpreting query and
     reply messages with Internet domain name servers.

     Global configuration and state information that is used by the resolver
     routines is kept in the structure _res. Most of the values have reason-
     able defaults and can be ignored.  Options stored in _res.options are de-
     fined in &lt;resolv.h> and are as follows.  Options are stored as a simple
     bit mask containing the bitwise OR of the options enabled.

     RES_INIT       True if the initial name server address and default domain
                    name are initialized (i.e., res_init() has been called).

     RES_DEBUG      Print debugging messages.

     RES_AAONLY     Accept authoritative answers only.  With this option,
                    res_send() should continue until it finds an authoritative
                    answer or finds an error.  Currently this is not imple-
                    mented.

     RES_USEVC      Use TCP connections for queries instead of UDP datagrams.

     RES_STAYOPEN   Used with RES_USEVC to keep the TCP connection open be-
                    tween queries.  This is useful only in programs that regu-
                    larly do many queries.  UDP should be the normal mode
                    used.

     RES_IGNTC      Unused currently (ignore truncation errors, i.e., don't

                    retry with TCP).

     RES_RECURSE    Set the recursion-desired bit in queries.  This is the de-
                    fault.  (res_send() does not do iterative queries and ex-
                    pects the name server to handle recursion.)

     RES_DEFNAMES   If set, res_search() will append the default domain name
                    to single-component names (those that do not contain a
                    dot).  This option is enabled by default.

     RES_DNSRCH     If this option is set, res_search() will search for host
                    names in the current domain and in parent domains; see
                    hostname(7).  This is used by the standard host lookup
                    routine gethostbyname(3).  This option is enabled by de-
                    fault.

     RES_USE_INET6  Enables support for IPv6-only applications.  This causes
                    IPv4 addresses to be returned as an IPv4 mapped address.
                    For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1.
                    The option is not meaningful on

     The res_init() routine reads the configuration file (if any; see
     resolv.conf(5))  to get the default domain name, search list, and the In-
     ternet address of the local name server(s).  If no server is configured,
     the host running the resolver is tried.  The current domain name is de-
     fined by the hostname if not specified in the configuration file; it can
     be overridden by the environment variable LOCALDOMAIN. This environment
     variable may contain several blank-separated tokens if you wish to over-
     ride the search list on a per-process basis.  This is similar to the
     search command in the configuration file.  Another environment variable
     RES_OPTIONS can be set to override certain internal resolver options
     which are otherwise set by changing fields in the _res structure or are
     inherited from the configuration file's options command.  The syntax of
     the RES_OPTIONS environment variable is explained in resolv.conf(5).
     Initialization normally occurs on the first call to one of the following
     routines.

     The res_query() function provides an interface to the server query mecha-
     nism.  It constructs a query, sends it to the local server, awaits a re-
     sponse, and makes preliminary checks on the reply.  The query requests
     information of the specified type and class for the specified fully qual-
     ified domain name dname. The reply message is left in the answer buffer
     with length anslen supplied by the caller.

     The res_search() routine makes a query and awaits a response like
     res_query(), but in addition, it implements the default and search rules
     controlled by the RES_DEFNAMES and RES_DNSRCH options.  It returns the
     first successful reply.

     The remaining routines are lower-level routines used by res_query().  The
     res_mkquery() function constructs a standard query message and places it
     in buf. It returns the size of the query, or -1 if the query is larger
     than buflen. The query type op is usually QUERY, but can be any of the
     query types defined in &lt;arpa/nameser.h>. The domain name for the query is
     given by dname. newrr is currently unused but is intended for making up-
     date messages.

     The res_send() routine sends a pre-formatted query and returns an answer.
     It will call res_init() if RES_INIT is not set, send the query to the lo-
     cal name server, and handle timeouts and retries.  The length of the re-
     ply message is returned, or -1 if there were errors.

     The dn_comp() function compresses the domain name exp_dn and stores it in
     comp_dn. The size of the compressed name is returned or -1 if there were
     errors.  The size of the array pointed to by comp_dn is given by length.
     The compression uses an array of pointers dnptrs to previously compressed
     names in the current message.  The first pointer points to the beginning
     of the message and the list ends with NULL. The limit to the array is
     specified by lastdnptr. A side effect of dn_comp() is to update the list
     of pointers for labels inserted into the message as the name is com-
     pressed.  If dnptr is NULL, names are not compressed.  If lastdnptr is
     NULL, the list of labels is not updated.

     The dn_expand() entry expands the compressed domain name comp_dn to a
     full domain name The compressed name is contained in a query or reply
     message; msg is a pointer to the beginning of the message.  The uncom-
     pressed name is placed in the buffer indicated by exp_dn which is of size
     length. The size of compressed name is returned or -1 if there was an er-
     ror.

FILES
     /etc/resolv.conf configuration file see resolv.conf(5).

SEE ALSO
     gethostbyname(3),  resolv.conf(5),  hostname(7),  named(8)

     RFC1032, RFC1033, RFC1034, RFC1035, RFC1535, RFC974

     Name Server Operations Guide for BIND.

HISTORY
     The res_query function appeared in 4.3BSD.

BSD Experimental                 June 4, 1993                                3
    </screen>
  </sect1>

  <sect1 id="ACCEPT">
    <title>ACCEPT</title>
    <screen>

ACCEPT(2)                 System Programmer's Manual                 ACCEPT(2)

NAME
     accept - accept a connection on a socket

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>

     int
     accept(int s, struct sockaddr *addr, socklen_t *addrlen)

DESCRIPTION
     The argument s is a socket that has been created with socket(2),  bound
     to an address with bind(2),  and is listening for connections after a
     listen(2).  The accept() argument extracts the first connection request
     on the queue of pending connections, creates a new socket with the same
     properties of s, and allocates a new file descriptor for the socket.  If
     no pending connections are present on the queue, and the socket is not
     marked as non-blocking, accept() blocks the caller until a connection is
     present.  If the socket is marked non-blocking and no pending connections
     are present on the queue, accept() returns an error as described below.
     The accepted socket may not be used to accept more connections.  The
     original socket s remains open.

     The argument addr is a result parameter that is filled in with the ad-
     dress of the connecting entity as known to the communications layer.  The
     exact format of the addr parameter is determined by the domain in which
     the communication is occurring.  The addrlen is a value-result parameter;
     it should initially contain the amount of space pointed to by addr; on
     return it will contain the actual length (in bytes) of the address re-
     turned.  This call is used with connection-based socket types, currently
     with SOCK_STREAM.

     It is possible to select(2) or poll(2) a socket for the purposes of doing
     an accept() by selecting it for read.

     For certain protocols which require an explicit confirmation, such as ISO
     or DATAKIT, accept() can be thought of as merely dequeuing the next con-
     nection request and not implying confirmation.  Confirmation can be im-
     plied by a normal read or write on the new file descriptor, and rejection
     can be implied by closing the new socket.

     One can obtain user connection request data without confirming the con-
     nection by issuing a recvmsg(2) call with an msg_iovlen of 0 and a non-
     zero msg_controllen, or by issuing a getsockopt(2) request.  Similarly,
     one can provide user connection rejection information by issuing a
     sendmsg(2) call with providing only the control information, or by call-
     ing setsockopt(2).

RETURN VALUES
     The call returns -1 on error.  If it succeeds, it returns a non-negative
     integer that is a descriptor for the accepted socket.

ERRORS
     The accept() will fail if:

     [EBADF]       The descriptor is invalid.

     [ENOTSOCK]    The descriptor references a file, not a socket.

     [EOPNOTSUPP]  The referenced socket is not of type SOCK_STREAM.

     [EINVAL]      The referenced socket is not listening for connections

                   (that is, listen(2) has not yet been called).

     [EFAULT]      The addr parameter is not in a writable part of the user
                   address space.

     [EWOULDBLOCK]
                   The socket is marked non-blocking and no connections are
                   present to be accepted.

     [EMFILE]      The per-process descriptor table is full.

     [ENFILE]      The system file table is full.

     [ECONNABORTED]
                   A connection has been aborted.

SEE ALSO
     bind(2),  connect(2),  listen(2),  poll(2),  select(2),  poll(2),  sock-
     et(2)

HISTORY
     The accept() function appeared in 4.2BSD.

BSD Experimental               February 15, 1999                             2
    </screen>
  </sect1>

  <sect1 id="BIND">
    <title>BIND</title>
    <screen>

BIND(2)                   System Programmer's Manual                   BIND(2)

NAME
     bind - bind a name to a socket

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>

     int
     bind(int s, const struct sockaddr *name, socklen_t namelen)

DESCRIPTION
     bind() assigns a name to an unnamed socket.  When a socket is created
     with socket(2) it exists in a name space (address family) but has no name
     assigned.  bind() requests that name be assigned to the socket.

NOTES
     Binding a name in the UNIX domain creates a socket in the file system
     that must be deleted by the caller when it is no longer needed (using
     unlink(2)).

     The rules used in name binding vary between communication domains.  Con-
     sult the manual entries in section 4 for detailed information.

RETURN VALUES
     If the bind is successful, a 0 value is returned.  A return value of -1
     indicates an error, which is further specified in the global errno.

ERRORS
     The bind() call will fail if:

     [EBADF]       S is not a valid descriptor.

     [ENOTSOCK]    S is not a socket.

     [EADDRNOTAVAIL]
                   The specified address is not available from the local ma-
                   chine.

     [EADDRINUSE]  The specified address is already in use.

     [EINVAL]      The socket is already bound to an address.

     [EINVAL]      The family of the socket and that requested in
                   name->sa_family are not equivalent.

     [EACCES]      The requested address is protected, and the current user
                   has inadequate permission to access it.

     [EFAULT]      The name parameter is not in a valid part of the user ad-
                   dress space.

     The following errors are specific to binding names in the UNIX domain.

     [ENOTDIR]     A component of the path prefix is not a directory.

     [ENAMETOOLONG]
                   A component of a pathname exceeded {NAME_MAX} characters,
                   or an entire path name exceeded {PATH_MAX} characters.

     [ENOENT]      A prefix component of the path name does not exist.

     [ELOOP]       Too many symbolic links were encountered in translating the

                   pathname.

     [EIO]         An I/O error occurred while making the directory entry or
                   allocating the inode.

     [EROFS]       The name would reside on a read-only file system.

     [EISDIR]      An empty pathname was specified.

SEE ALSO
     connect(2),  getsockname(2),  listen(2),  socket(2)

HISTORY
     The bind() function call appeared in 4.2BSD.

BSD Experimental               February 15, 1999                             2
    </screen>
  </sect1>

  <sect1 id="CONNECT">
    <title>CONNECT</title>
    <screen>

CONNECT(2)                System Programmer's Manual                CONNECT(2)

NAME
     connect - initiate a connection on a socket

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>

     int
     connect(int s, const struct sockaddr *name, socklen_t namelen)

DESCRIPTION
     The parameter s is a socket.  If it is of type SOCK_DGRAM, this call
     specifies the peer with which the socket is to be associated; this ad-
     dress is that to which datagrams are to be sent, and the only address
     from which datagrams are to be received.  If the socket is of type
     SOCK_STREAM, this call attempts to make a connection to another socket.
     The other socket is specified by name, which is an address in the commu-
     nications space of the socket.  Each communications space interprets the
     name parameter in its own way.  Generally, stream sockets may successful-
     ly connect() only once; datagram sockets may use connect() multiple times
     to change their association.  Datagram sockets may dissolve the associa-
     tion by connecting to an invalid address, such as a null address.

RETURN VALUES
     If the connection or binding succeeds, 0 is returned.  Otherwise a -1 is
     returned, and a more specific error code is stored in errno.

ERRORS
     The connect() call fails if:

     [EBADF]       S is not a valid descriptor.

     [ENOTSOCK]    S is a descriptor for a file, not a socket.

     [EADDRNOTAVAIL]
                   The specified address is not available on this machine.

     [EAFNOSUPPORT]
                   Addresses in the specified address family cannot be used
                   with this socket.

     [EISCONN]     The socket is already connected.

     [ETIMEDOUT]   Connection establishment timed out without establishing a
                   connection.

     [EINVAL]      A TCP connection with a local broadcast, the all-ones or a
                   multicast address as the peer was attempted.

     [ECONNREFUSED]
                   The attempt to connect was forcefully rejected.

     [EINTR]       A connect was interrupted before it succeeded by the deliv-
                   ery of a signal.

     [ENETUNREACH]
                   The network isn't reachable from this host.

     [EADDRINUSE]  The address is already in use.

     [EFAULT]      The name parameter specifies an area outside the process

                   address space.

     [EINPROGRESS]
                   The socket is non-blocking and the connection cannot be
                   completed immediately.  It is possible to select(2) or
                   poll(2) for completion by selecting the socket for writing,
                   and also use getsockopt(2) with SO_ERROR to check for error
                   conditions.

     [EALREADY]    The socket is non-blocking and a previous connection at-
                   tempt has not yet been completed.

     The following errors are specific to connecting names in the UNIX domain.
     These errors may not apply in future versions of the UNIX IPC domain.

     [ENOTDIR]     A component of the path prefix is not a directory.

     [ENAMETOOLONG]
                   A component of a pathname exceeded {NAME_MAX} characters,
                   or an entire path name exceeded {PATH_MAX} characters.

     [ENOENT]      The named socket does not exist.

     [EACCES]      Search permission is denied for a component of the path
                   prefix.

     [EACCES]      Write access to the named socket is denied.

     [ELOOP]       Too many symbolic links were encountered in translating the
                   pathname.

SEE ALSO
     accept(2),  getsockname(2),  getsockopt(2),  poll(2),  select(2),  sock-
     et(2)

HISTORY
     The connect() function call appeared in 4.2BSD.

BSD Experimental               February 15, 1999                             2
    </screen>
  </sect1>

  <sect1 id="GETPEERNAME">
    <title>GETPEERNAME</title>
    <screen>

GETPEERNAME(2)            System Programmer's Manual            GETPEERNAME(2)

NAME
     getpeername - get name of connected peer

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>

     int
     getpeername(int s, struct sockaddr *name, socklen_t *namelen)

DESCRIPTION
     getpeername() returns the address information of the peer connected to
     socket s. One common use occurs when a process inherits an open socket,
     such as TCP servers forked from inetd(8).  In this scenario,
     getpeername() is used to determine the connecting client's IP address.

     getpeername() takes three parameters:

     s Contains the file descriptor of the socket whose peer should be looked
     up.

     name Points to a sockaddr structure that will hold the address informa-
     tion for the connected peer.  Normal use requires one to use a structure
     specific to the protocol family in use, such as sockaddr_in (IPv4) or
     sockaddr_in6 (IPv6), cast to a (struct sockaddr *).

     For greater portability, especially with the newer protocol families, the
     new struct sockaddr_storage should be used.  sockaddr_storage is large
     enough to hold any of the other sockaddr_* variants.  On return, it can
     be cast to the correct sockaddr type, based the protocol family contained
     in its ss_family field.

     namelen Indicates the amount of space pointed to by name, in bytes.

     If address information for the local end of the socket is required, the
     getsockname(2) function should be used instead.

     If name does not point to enough space to hold the entire socket address,
     the result will be truncated to namelen bytes.

RETURN VALUES
     If the call succeeds, a 0 is returned and namelen is set to the actual
     size of the socket address returned in name. Otherwise, errno is set and
     a value of -1 is returned.

ERRORS
     On failure, errno is set to one of the following:

     [EBADF]       The argument s is not a valid descriptor.

     [ENOTSOCK]    The argument s is a file, not a socket.

     [ENOTCONN]    The socket is not connected.

     [ENOBUFS]     Insufficient resources were available in the system to per-
                   form the operation.

     [EFAULT]      The name parameter points to memory not in a valid part of
                   the process address space.

SEE ALSO
     accept(2),  bind(2),  getsockname(2),  getpeereid(2),  socket(2)

HISTORY
     The getpeername() function call appeared in 4.2BSD.

BSD Experimental                 July 17, 1999                               2
    </screen>
  </sect1>

  <sect1 id="GETSOCKNAME">
    <title>GETSOCKNAME</title>
    <screen>

GETSOCKNAME(2)            System Programmer's Manual            GETSOCKNAME(2)

NAME
     getsockname - get socket name

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>

     int
     getsockname(int s, struct sockaddr *name, socklen_t *namelen)

DESCRIPTION
     getsockname() returns the locally bound address information for a speci-
     fied socket.

     Common uses of this function are as follows:

     o   When bind(2) is called with a port number of 0 (indicating the kernel
         should pick an ephemeral port) getsockname() is used to retrieve the
         kernel-assigned port number.

     o   When a process calls bind(2) on a wildcard IP address, getsockname()
         is used to retrieve the local IP address for the connection.

     o   When a function wishes to know the address family of a socket,
         getsockname() can be used.

     getsockname() takes three parameters:

     s, Contains the file desriptor for the socket to be looked up.

     name points to a sockaddr structure which will hold the resulting address
     information.  Normal use requires one to use a structure specific to the
     protocol family in use, such as sockaddr_in (IPv4) or sockaddr_in6
     (IPv6), cast to a (struct sockaddr *).

     For greater portability (such as newer protocol families) the new struc-
     ture sockaddr_storage exists.  sockaddr_storage is large enough to hold
     any of the other sockaddr_* variants.  On return, it should be cast to
     the correct sockaddr type, according to the current protocol family.

     namelen Indicates the amount of space pointed to by name, in bytes.  Upon
     return, namelen is set to the actual size of the returned address infor-
     mation.

     If the address of the destination socket for a given socket connection is
     needed, the getpeername(2) function should be used instead.

     If name does not point to enough space to hold the entire socket address,
     the result will be truncated to namelen bytes.

RETURN VALUES
     On success, getsockname() returns a 0, and namelen is set to the actual
     size of the socket address returned in name. Otherwise, errno is set, and
     a value of -1 is returned.

ERRORS
     If getsockname() fails, errno is set to one of the following:

     [EBADF]       The argument s is not a valid descriptor.



     [ENOTSOCK]    The argument s is a file, not a socket.

     [ENOBUFS]     Insufficient resources were available in the system to per-
                   form the operation.

     [EFAULT]      The name parameter points to memory not in a valid part of
                   the process address space.

SEE ALSO
     accept(2),  bind(2),  getpeername(2),  getpeereid(2),  socket(2)

BUGS
     Names bound to sockets in the UNIX domain are inaccessible; getsockname
     returns a zero length name.

HISTORY
     The getsockname() function call appeared in 4.2BSD.

BSD Experimental                 July 17, 1999                               2
    </screen>
  </sect1>

  <sect1 id="GETSOCKOPT">
    <title>GETSOCKOPT</title>
    <screen>

GETSOCKOPT(2)             System Programmer's Manual             GETSOCKOPT(2)

NAME
     getsockopt, setsockopt - get and set options on sockets

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>

     int
     getsockopt(int s, int level, int optname, void *optval,
             socklen_t *optlen)

     int
     setsockopt(int s, int level, int optname, const void *optval,
             socklen_t optlen)

DESCRIPTION
     getsockopt() and setsockopt() manipulate the options associated with a
     socket.  Options may exist at multiple protocol levels; they are always
     present at the uppermost ``socket'' level.

     When manipulating socket options the level at which the option resides
     and the name of the option must be specified.  To manipulate options at
     the socket level, level is specified as SOL_SOCKET. To manipulate options
     at any other level the protocol number of the appropriate protocol con-
     trolling the option is supplied.  For example, to indicate that an option
     is to be interpreted by the TCP protocol, level should be set to the pro-
     tocol number of TCP; see getprotoent(3).

     The parameters optval and optlen are used to access option values for
     setsockopt().  For getsockopt() they identify a buffer in which the value
     for the requested option(s) are to be returned.  For getsockopt(), optlen
     is a value-result parameter, initially containing the size of the buffer
     pointed to by optval, and modified on return to indicate the actual size
     of the value returned.  If no option value is to be supplied or returned,
     optval may be NULL.

     optname and any specified options are passed uninterpreted to the appro-
     priate protocol module for interpretation.  The include file
     &lt;sys/socket.h> contains definitions for socket level options, described
     below.  Options at other protocol levels vary in format and name; consult
     the appropriate entries in section 4 of the manual.

     Most socket-level options utilize an int parameter for optval. For
     setsockopt(), the parameter should be non-zero to enable a boolean op-
     tion, or zero if the option is to be disabled.  SO_LINGER uses a struct
     linger parameter, defined in &lt;sys/socket.h>, which specifies the desired
     state of the option and the linger interval (see below).  SO_SNDTIMEO and
     SO_RCVTIMEO use a struct timeval parameter, defined in &lt;sys/time.h>.

     The following options are recognized at the socket level.  Except as not-
     ed, each may be examined with getsockopt() and set with setsockopt().

           SO_DEBUG        enables recording of debugging information
           SO_REUSEADDR    enables local address reuse
           SO_REUSEPORT    enables duplicate address and port bindings
           SO_KEEPALIVE    enables keep connections alive
           SO_DONTROUTE    enables routing bypass for outgoing messages
           SO_LINGER       linger on close if data present
           SO_BROADCAST    enables permission to transmit broadcast messages
           SO_OOBINLINE    enables reception of out-of-band data in band


           SO_SNDBUF       set buffer size for output
           SO_RCVBUF       set buffer size for input
           SO_SNDLOWAT     set minimum count for output
           SO_RCVLOWAT     set minimum count for input
           SO_SNDTIMEO     set timeout value for output
           SO_RCVTIMEO     set timeout value for input
           SO_TYPE         get the type of the socket (get only)
           SO_ERROR        get and clear error on the socket (get only)

     SO_DEBUG enables debugging in the underlying protocol modules.
     SO_REUSEADDR indicates that the rules used in validating addresses sup-
     plied in a bind(2) call should allow reuse of local addresses.
     SO_REUSEPORT allows completely duplicate bindings by multiple processes
     if they all set SO_REUSEPORT before binding the port.  This option per-
     mits multiple instances of a program to each receive UDP/IP multicast or
     broadcast datagrams destined for the bound port.  SO_KEEPALIVE enables
     the periodic transmission of messages on a connected socket.  Should the
     connected party fail to respond to these messages, the connection is con-
     sidered broken and processes using the socket are notified via a SIGPIPE
     signal when attempting to send data.  SO_DONTROUTE indicates that outgo-
     ing messages should bypass the standard routing facilities.  Instead,
     messages are directed to the appropriate network interface according to
     the network portion of the destination address.

     SO_LINGER controls the action taken when unsent messages are queued on
     socket and a close(2) is performed.  If the socket promises reliable de-
     livery of data and SO_LINGER is set, the system will block the process on
     the close(2) attempt until it is able to transmit the data or until it
     decides it is unable to deliver the information (a timeout period mea-
     sured in seconds, termed the linger interval, is specified in the
     setsockopt() call when SO_LINGER is requested).  If SO_LINGER is disabled
     and a close(2) is issued, the system will process the close in a manner
     that allows the process to continue as quickly as possible.

     The option SO_BROADCAST requests permission to send broadcast datagrams
     on the socket.  Broadcast was a privileged operation in earlier versions
     of the system.  With protocols that support out-of-band data, the
     SO_OOBINLINE option requests that out-of-band data be placed in the nor-
     mal data input queue as received; it will then be accessible with recv(2)
     or read(2) calls without the MSG_OOB flag.  Some protocols always behave
     as if this option is set.  SO_SNDBUF and SO_RCVBUF are options to adjust
     the normal buffer sizes allocated for output and input buffers, respec-
     tively.  The buffer size may be increased for high-volume connections, or
     may be decreased to limit the possible backlog of incoming data.  The
     system places an absolute limit on these values.

     SO_SNDLOWAT is an option to set the minimum count for output operations.
     Most output operations process all of the data supplied by the call, de-
     livering data to the protocol for transmission and blocking as necessary
     for flow control.  Nonblocking output operations will process as much da-
     ta as permitted subject to flow control without blocking, but will pro-
     cess no data if flow control does not allow the smaller of the low water
     mark value or the entire request to be processed.  A select(2) or poll(2)
     operation testing the ability to write to a socket will return true only
     if the low water mark amount could be processed.  The default value for
     SO_SNDLOWAT is set to a convenient size for network efficiency, often
     1024.  SO_RCVLOWAT is an option to set the minimum count for input opera-
     tions.  In general, receive calls will block until any (non-zero) amount
     of data is received, then return with the smaller of the amount available
     or the amount requested.  The default value for SO_RCVLOWAT is 1.  If
     SO_RCVLOWAT is set to a larger value, blocking receive calls normally
     wait until they have received the smaller of the low water mark value or
     the requested amount.  Receive calls may still return less than the low
     water mark if an error occurs, a signal is caught, or the type of data
     next in the receive queue is different than that returned.


     SO_SNDTIMEO is an option to set a timeout value for output operations.
     It accepts a struct timeval parameter with the number of seconds and mi-
     croseconds used to limit waits for output operations to complete.  If a
     send operation has blocked for this much time, it returns with a partial
     count or with the error EWOULDBLOCK if no data was sent.  In the current
     implementation, this timer is restarted each time additional data are de-
     livered to the protocol, implying that the limit applies to output por-
     tions ranging in size from the low water mark to the high water mark for
     output.  SO_RCVTIMEO is an option to set a timeout value for input opera-
     tions.  It accepts a struct timeval parameter with the number of seconds
     and microseconds used to limit waits for input operations to complete.
     In the current implementation, this timer is restarted each time addi-
     tional data are received by the protocol, and thus the limit is in effect
     an inactivity timer.  If a receive operation has been blocked for this
     much time without receiving additional data, it returns with a short
     count or with the error EWOULDBLOCK if no data were received.

     Finally, SO_TYPE and SO_ERROR are options used only with getsockopt().
     SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful
     for servers that inherit sockets on startup.  SO_ERROR returns any pend-
     ing error on the socket and clears the error status.  It may be used to
     check for asynchronous errors on connected datagram sockets or for other
     asynchronous errors.

RETURN VALUES
     A 0 is returned if the call succeeds, -1 if it fails.

ERRORS
     The call succeeds unless:

     [EBADF]       The argument s is not a valid descriptor.

     [ENOTSOCK]    The argument s is a file, not a socket.

     [ENOPROTOOPT]
                   The option is unknown at the level indicated.

     [EFAULT]      The address pointed to by optval is not in a valid part of
                   the process address space.  For getsockopt(), this error
                   may also be returned if optlen is not in a valid part of
                   the process address space.

SEE ALSO
     connect(2),  ioctl(2),  poll(2),  select(2),  poll(2),  socket(2),
     getprotoent(3),  protocols(5)

BUGS
     Several of the socket options should be handled at lower levels of the
     system.

HISTORY
     The getsockopt() system call appeared in 4.2BSD.

BSD Experimental               February 15, 1999                             3
    </screen>
  </sect1>

  <sect1 id="IOCTL">
    <title>IOCTL</title>
    <screen>

IOCTL(2)                  System Programmer's Manual                  IOCTL(2)

NAME
     ioctl - control device

SYNOPSIS
     #include &lt;sys/ioctl.h>

     int
     ioctl(int d, unsigned long request, ...)

DESCRIPTION
     The ioctl() function manipulates the underlying device parameters of spe-
     cial files.  In particular, many operating characteristics of character
     special files (e.g., terminals) may be controlled with ioctl() requests.

     The argument d must be an open file descriptor. The third argument is
     called arg and contains additional information needed by this device to
     perform the requested function.  arg is either an int or a pointer to a
     device-specific data structure, depending upon the given request.

     An ioctl request has encoded in it whether the argument is an ``in'' pa-
     rameter or ``out'' parameter, and the size of the third argument (arg) in
     bytes.  Macros and defines used in specifying an ioctl request are locat-
     ed in the file &lt;sys/ioctl.h>.

RETURN VALUES
     If an error has occurred, a value of -1 is returned and errno is set to
     indicate the error.

ERRORS
     ioctl() will fail if:

     [EBADF]       d is not a valid descriptor.

     [ENOTTY]      d is not associated with a character special device.

     [ENOTTY]      The specified request does not apply to the kind of object
                   that the descriptor d references.

     [EINVAL]      request or arg is not valid.

     [EFAULT]      arg points outside the process's allocated address space.

SEE ALSO
     cdio(1),  chio(1),  mt(1),  execve(2),  fcntl(2),  intro(4),  tty(4)

HISTORY
     An ioctl() function call appeared in Version 7 AT&amp;T UNIX.

BSD Experimental               December 11, 1993                             1
    </screen>
  </sect1>

  <sect1 id="POLL">
    <title>POLL</title>
    <screen>

POLL(2)                   System Programmer's Manual                   POLL(2)

NAME
     poll - synchronous I/O multiplexing

SYNOPSIS
     #include &lt;poll.h>

     int
     poll(struct pollfd *fds, int nfds, int timeout)

DESCRIPTION
     poll() provides a mechanism for reporting I/O conditions across a set of
     file descriptors.

     The arguments are as follows:

     fds      Points to an array of pollfd structures, which are defined as:

                    struct pollfd {
                            int fd;
                            short events;
                            short revents;
                    };

              The fd member is an open file descriptor.  The events and
              revents members are bitmasks of conditions to monitor and condi-
              tions found, respectively.

     nfds     The number of pollfd structures in the array.

     timeout  Maximum interval to wait for the poll to complete, in millisec-
              onds.  If this value is 0, then poll() will return immediately.
              If this value is INFTIM (-1), poll() will block indefinitely un-
              til a condition is found.

     The calling process sets the events bitmask and poll() sets the revents
     bitmask.  Each call to poll() resets the revents bitmask for accuracy.
     The condition flags in the bitmasks are defined as:

     POLLIN      Data is available on the file descriptor for reading.

     POLLNORM    Same as POLLIN.

     POLLPRI     Same as POLLIN.

     POLLOUT     Data can be written to the file descriptor without blocking.

     POLLERR     This flag is not used in this implementation and is provided
                 only for source code compatibility.

     POLLHUP     The file descriptor was valid before the polling process and
                 invalid after.  Presumably, this means that the file descrip-
                 tor was closed sometime during the poll.

     POLLNVAL    The corresponding file descriptor is invalid.

     POLLRDNORM  Same as POLLIN.

     POLLRDBAND  Same as POLLIN.

     POLLWRNORM  Same as POLLOUT.


     POLLWRBAND  Same as POLLOUT.

     POLLMSG     This flag is not used in this implementation and is provided
                 only for source code compatibility.

     All flags except POLLIN, POLLOUT, and their synonyms are for use only in
     the revents member of the pollfd structure.  An attempt to set any of
     these flags in the events member will generate an error condition.

     In addition to I/O multiplexing, poll() can be used to generate simple
     timeouts.  This functionality may be achieved by passing a null pointer
     for fds.

WARNINGS
     The POLLHUP flag is only a close approximation and may not always be ac-
     curate.

RETURN VALUES
     Upon error, poll() returns a -1 and sets the global variable errno to in-
     dicate the error.  If the timeout interval was reached before any events
     occurred, a 0 is returned.  Otherwise, poll() returns the number of file
     descriptors for which revents is non-zero.

ERRORS
     poll() will fail if:

     [EINVAL]   nfds was either a negative number or greater than the number
                of available file descriptors.

     [EINVAL]   An invalid flags was set in the events member of the pollfd
                structure.

     [EINVAL]   The timeout passed to poll() was too large.

     [EAGAIN]   Resource allocation failed inside of poll().  Subsequent calls
                to poll() may succeed.

     [EINTR]    poll() caught a signal during the polling process.

SEE ALSO
     poll(2),  select(2),  sysconf(3)

HISTORY
     A poll() system call appeared in AT&amp;T System V UNIX.

BSD Experimental               December 13, 1994                             2
    </screen>
  </sect1>

  <sect1 id="SELECT">
    <title>SELECT</title>
    <screen>

SELECT(2)                 System Programmer's Manual                 SELECT(2)

NAME
     select - synchronous I/O multiplexing

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/time.h>
     #include &lt;unistd.h>

     int
     select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
             struct timeval *timeout)

     FD_SET(fd, &amp;fdset)

     FD_CLR(fd, &amp;fdset)

     FD_ISSET(fd, &amp;fdset)

     FD_ZERO(&amp;fdset)

DESCRIPTION
     select() examines the I/O descriptor sets whose addresses are passed in
     readfds, writefds, and exceptfds to see if some of their descriptors are
     ready for reading, are ready for writing, or have an exceptional condi-
     tion pending, respectively.  The first nfds descriptors are checked in
     each set; i.e., the descriptors from 0 through nfds-1 in the descriptor
     sets are examined.  On return, select() replaces the given descriptor
     sets with subsets consisting of those descriptors that are ready for the
     requested operation.  select() returns the total number of ready descrip-
     tors in all the sets.

     The descriptor sets are stored as bit fields in arrays of integers.  The
     following macros are provided for manipulating such descriptor sets:
     FD_ZERO(&amp;fdset) initializes a descriptor set fdset to the null set.
     FD_SET(fd, &amp;fdset) includes a particular descriptor fd in fdset.
     FD_CLR(fd, &amp;fdset) removes fd from fdset. FD_ISSET(fd, &amp;fdset) is non-ze-
     ro if fd is a member of fdset, zero otherwise.  The behavior of these
     macros is undefined if a descriptor value is less than zero or greater
     than or equal to FD_SETSIZE, which is normally at least equal to the max-
     imum number of descriptors supported by the system.

     If timeout is a non-null pointer, it specifies a maximum interval to wait
     for the selection to complete.  If timeout is a null pointer, the select
     blocks indefinitely.  To effect a poll, the timeout argument should be
     non-null, pointing to a zero-valued timeval structure.  timeout is not
     changed by select(), and may be reused on subsequent calls; however, it
     is good style to re-initialize it before each invocation of select().

     Any of readfds, writefds, and exceptfds may be given as null pointers if
     no descriptors are of interest.

RETURN VALUES
     select() returns the number of ready descriptors that are contained in
     the descriptor sets, or -1 is an error occurred.  If the time limit ex-
     pires, select() returns 0.  If select() returns with an error, including
     one due to an interrupted call, the descriptor sets will be unmodified.

ERRORS
     An error return from select() indicates:

     [EFAULT]      One or more of readfds, writefds, or exceptfds points out-

                   side the process's allocated address space.

     [EBADF]       One of the descriptor sets specified an invalid descriptor.

     [EINTR]       A signal was delivered before the time limit expired and
                   before any of the selected events occurred.

     [EINVAL]      The specified time limit is invalid.  One of its components
                   is negative or too large.

SEE ALSO
     accept(2),  connect(2),  gettimeofday(2),  poll(2),  read(2),  recv(2),
     send(2),  write(2),  getdtablesize(3)

BUGS
     Although the provision of getdtablesize(3) was intended to allow user
     programs to be written independent of the kernel limit on the number of
     open files, the dimension of a sufficiently large bit field for select
     remains a problem.  The default bit size of fd_set is based on the symbol
     FD_SETSIZE (currently 256), but that is somewhat smaller than the current
     kernel limit to the number of open files.  However, in order to accommo-
     date programs which might potentially use a larger number of open files
     with select, it is possible to increase this size within a program by
     providing a larger definition of FD_SETSIZE before the inclusion of
     &lt;sys/types.h>. The kernel will cope, and the userland libraries provided
     with the system are also ready for large numbers of file descriptors.

     Alternatively, to be really safe, it is possible to allocate fd_set bit-
     arrays dynamically.  The idea is to permit a program to work properly
     even if it is execve(2)'d  with 4000 file descriptors pre-allocated.  The
     following illustrates the technique which is used by userland libraries:

                   fd_set *fdsr;
                   int max = fd;

                   fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS),
                       sizeof(fd_mask));
                   if (fdsr == NULL) {
                           ...
                           return (-1);
                   }
                   FD_SET(fd, fdsr);
                   n = select(max+1, fdsr, NULL, NULL, &amp;tv);
                   ...
                   free(fdsr);

     Alternatively, it is possible to use the poll(2) interface.  poll(2) is
     more efficient when the size of select()'s fd_set bit-arrays are very
     large, and for fixed numbers of file descriptors one need not size and
     dynamically allocate a memory object.

     select() should probably have been designed to return the time remaining
     from the original timeout, if any, by modifying the time value in place.
     Even though some systems stupidly act in this different way, it is un-
     likely this semantic will ever be commonly implemented, as the change
     causes massive source code compatibility problems.  Furthermore, recent
     new standards have dictated the current behaviour.  In general, due to
     the existence of those brain-damaged non-conforming systems, it is unwise
     to assume that the timeout value will be unmodified by the select() call,
     and the caller should reinitialize it on each invocation.  Calculating
     the delta is easily done by calling gettimeofday(2) before and after the
     call to select(), and using timersub() (as described in getitimer(2)).

     Internally to the kernel, select() works poorly if multiple processes
     wait on the same file descriptor.  Given that, it is rather surprising to
     see that many daemons are written that way (i.e., httpd(8)).

HISTORY
     The select() function call appeared in 4.2BSD.

BSD Experimental                March 25, 1994                               3
    </screen>
  </sect1>

  <sect1 id="SEND">
    <title>SEND</title>
    <screen>

SEND(2)                   System Programmer's Manual                   SEND(2)

NAME
     send, sendto, sendmsg - send a message from a socket

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>

     ssize_t
     send(int s, const void *msg, size_t len, int flags)

     ssize_t
     sendto(int s, const void *msg, size_t len, int flags,
             const struct sockaddr *to, socklen_t tolen)

     ssize_t
     sendmsg(int s, const struct msghdr *msg, int flags)

DESCRIPTION
     send(), sendto(), and sendmsg() are used to transmit a message to another
     socket.  send() may be used only when the socket is in a connected state,
     while sendto() and sendmsg() may be used at any time.

     The address of the target is given by to with tolen specifying its size.
     The length of the message is given by len. If the message is too long to
     pass atomically through the underlying protocol, the error EMSGSIZE is
     returned, and the message is not transmitted.

     No indication of failure to deliver is implicit in a send().  Locally de-
     tected errors are indicated by a return value of -1.

     If no messages space is available at the socket to hold the message to be
     transmitted, then send() normally blocks, unless the socket has been
     placed in non-blocking I/O mode.  The select(2) or poll(2) system calls
     may be used to determine when it is possible to send more data.

     The flags parameter may include one or more of the following:

     #define MSG_OOB        0x1  /* process out-of-band data */
     #define MSG_DONTROUTE  0x4  /* bypass routing, use direct interface */

     The flag MSG_OOB is used to send ``out-of-band'' data on sockets that
     support this notion (e.g., SOCK_STREAM); the underlying protocol must al-
     so support ``out-of-band'' data.  MSG_DONTROUTE is usually used only by
     diagnostic or routing programs.

     See recv(2) for a description of the msghdr structure.

RETURN VALUES
     The call returns the number of characters sent, or -1 if an error oc-
     curred.

ERRORS
     send(), sendto(), and sendmsg() fail if:

     [EBADF]       An invalid descriptor was specified.

     [ENOTSOCK]    The argument s is not a socket.

     [EFAULT]      An invalid user space address was specified for a parame-
                   ter.

     [EMSGSIZE]    The socket requires that message be sent atomically, and

                   the size of the message to be sent made this impossible.

     [EAGAIN]      The socket is marked non-blocking and the requested opera-
                   tion would block.

     [ENOBUFS]     The system was unable to allocate an internal buffer.  The
                   operation may succeed when buffers become available.

     [ENOBUFS]     The output queue for a network interface was full.  This
                   generally indicates that the interface has stopped sending,
                   but may be caused by transient congestion.

     [EACCES]      The SO_BROADCAST option is not set on the socket, and a
                   broadcast address was given as the destination.

     [EHOSTUNREACH]
                   The destination address specified an unreachable host.

     [EINVAL]      The flags parameter is invalid.

     [EHOSTDOWN]   The destination address specified a host that is down.

     [ENETDOWN]    The destination address specified a network that is down.

     [ECONNREFUSED]
                   The destination host rejected the message (or a previous
                   one).  This error can only be returned by connected sock-
                   ets.

     [ENOPROTOOPT]
                   There was a problem sending the message.  This error can
                   only be returned by connected sockets.

     [EDESTADDRREQ]
                   The socket is not connected, and no destination address was
                   specified.

     [EISCONN]     The socket is already connected, and a destination address
                   was specified.

     In addition, send() and sendto() may return the following error:

     [EINVAL]      len was larger than SSIZE_MAX.

     Also, sendmsg() may return the following errors:

     [EINVAL]      The sum of the iov_len values in the msg_iov array over-
                   flowed an ssize_t.

     [EMSGSIZE]    The msg_iovlen member of msg was less than 0 or larger than
                   IOV_MAX.

     [EAFNOSUPPORT]
                   Addresses in the specified address family cannot be used
                   with this socket.

SEE ALSO
     fcntl(2),  getsockopt(2),  poll(2),  recv(2),  select(2),  poll(2),
     socket(2),  write(2)

HISTORY
     The send() function call appeared in 4.2BSD.

BSD Experimental                 July 28, 1998                               2
    </screen>
  </sect1>

  <sect1 id="SHUTDOWN">
    <title>SHUTDOWN</title>
    <screen>

SHUTDOWN(2)               System Programmer's Manual               SHUTDOWN(2)

NAME
     shutdown - shut down part of a full-duplex connection

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>

     int
     shutdown(int s, int how)

DESCRIPTION
     The shutdown() call causes all or part of a full-duplex connection on the
     socket associated with s to be shut down.  If how is SHUT_RD, further re-
     ceives will be disallowed.  If how is SHUT_WR, further sends will be dis-
     allowed.  If how is SHUT_RDWR, further sends and receives will be disal-
     lowed.

RETURN VALUES
     A 0 is returned if the call succeeds, -1 if it fails.

ERRORS
     The call succeeds unless:

     [EINVAL]      how is not SHUT_RD, SHUT_WR, or SHUT_RDWR.

     [EBADF]       s is not a valid descriptor.

     [ENOTSOCK]    s is a file, not a socket.

     [ENOTCONN]    The specified socket is not connected.

SEE ALSO
     connect(2),  socket(2)

HISTORY
     The shutdown() function call appeared in 4.2BSD. The how arguments used
     to be simply 0, 1, and 2, but now have named values as specified by .

BSD Experimental                 June 4, 1993                                1
    </screen>
  </sect1>

  <sect1 id="SOCKET">
    <title>SOCKET</title>
    <screen>

SOCKET(2)                 System Programmer's Manual                 SOCKET(2)

NAME
     socket - create an endpoint for communication

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>

     int
     socket(int domain, int type, int protocol)

DESCRIPTION
     socket() creates an endpoint for communication and returns a descriptor.

     The domain parameter specifies a communications domain within which com-
     munication will take place; this selects the protocol family which should
     be used.  These families are defined in the include file &lt;sys/socket.h>.
     The currently understood formats are

           AF_UNIX         (UNIX internal protocols),
           AF_INET         (ARPA Internet protocols),
           AF_INET6        (ARPA IPv6 protocols),
           AF_ISO          (ISO protocols),
           AF_NS           (Xerox Network Systems protocols),
           AF_IPX          (Internetwork Packet Exchange), and
           AF_IMPLINK      (IMP host at IMP link layer).

     The socket has the indicated type, which specifies the semantics of com-
     munication.  Currently defined types are:

           SOCK_STREAM
           SOCK_DGRAM
           SOCK_RAW
           SOCK_SEQPACKET
           SOCK_RDM

     A SOCK_STREAM type provides sequenced, reliable, two-way connection based
     byte streams.  An out-of-band data transmission mechanism may be support-
     ed.  A SOCK_DGRAM socket supports datagrams (connectionless, unreliable
     messages of a fixed (typically small) maximum length).  A SOCK_SEQPACKET
     socket may provide a sequenced, reliable, two-way connection-based data
     transmission path for datagrams of fixed maximum length; a consumer may
     be required to read an entire packet with each read system call.  This
     facility is protocol specific, and presently implemented only for PF_NS.
     SOCK_RAW sockets provide access to internal network protocols and inter-
     faces.  The types SOCK_RAW, which is available only to the superuser, and
     SOCK_RDM, which is planned, but not yet implemented, are not described
     here.

     The protocol specifies a particular protocol to be used with the socket.
     Normally only a single protocol exists to support a particular socket
     type within a given protocol family.  However, it is possible that many
     protocols may exist, in which case a particular protocol must be speci-
     fied in this manner.  The protocol number to use is particular to the
     communication domain in which communication is to take place; see
     protocols(5).  A value of 0 for protocol will let the system select an
     appropriate protocol for the requested socket type.

     Sockets of type SOCK_STREAM are full-duplex byte streams, similar to
     pipes.  A stream socket must be in a connected state before any data may
     be sent or received on it.  A connection to another socket is created
     with a connect(2) call.  Once connected, data may be transferred using
     read(2) and write(2) calls or some variant of the send(2) and recv(2)
     calls.  When a session has been completed a close(2) may be performed.
     Out-of-band data may also be transmitted as described in send(2) and re-
     ceived as described in recv(2).

     The communications protocols used to implement a SOCK_STREAM ensure that
     data is not lost or duplicated.  If a piece of data for which the peer
     protocol has buffer space cannot be successfully transmitted within a
     reasonable length of time, then the connection is considered broken and
     calls will indicate an error with -1 returns and with ETIMEDOUT as the
     specific code in the global variable errno. The protocols optionally keep
     sockets ``warm'' by forcing transmissions roughly every minute in the ab-
     sence of other activity.  An error is then indicated if no response can
     be elicited on an otherwise idle connection for a extended period (e.g.,
     5 minutes).  A SIGPIPE signal is raised if a process sends on a broken
     stream; this causes naive processes, which do not handle the signal, to
     exit.

     SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM sock-
     ets.  The only difference is that read(2) calls will return only the
     amount of data requested, and any remaining in the arriving packet will
     be discarded.

     SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to correspon-
     dents named in send(2) calls.  Datagrams are generally received with
     recvfrom(2),  which returns the next datagram with its return address.

     An fcntl(2) call can be used to specify a process group to receive a
     SIGURG signal when the out-of-band data arrives.  It may also enable non-
     blocking I/O and asynchronous notification of I/O events via SIGIO.

     The operation of sockets is controlled by socket level options. These op-
     tions are defined in the file &lt;sys/socket.h>. setsockopt(2) and getsock-
     opt(2) are used to set and get options, respectively.

RETURN VALUES
     A -1 is returned if an error occurs, otherwise the return value is a de-
     scriptor referencing the socket.

ERRORS
     The socket() call fails if:

     [EPROTONOSUPPORT]
                   The protocol type or the specified protocol is not support-
                   ed within this domain.

     [EMFILE]      The per-process descriptor table is full.

     [ENFILE]      The system file table is full.

     [EACCES]      Permission to create a socket of the specified type and/or
                   protocol is denied.

     [ENOBUFS]     Insufficient buffer space is available.  The socket cannot
                   be created until sufficient resources are freed.

SEE ALSO
     accept(2),  bind(2),  connect(2),  getsockname(2),  getsockopt(2),
     ioctl(2),  listen(2),  poll(2),  read(2),  recv(2),  select(2),  send(2),
      setsockopt(2),  shutdown(2),  socketpair(2),  write(2),  getprotoent(3),
      netintro(4)

     An Introductory 4.3 BSD Interprocess Communication Tutorial, reprinted in
     UNIX Programmer's Supplementary Documents Volume 1.

     BSD Interprocess Communication Tutorial, reprinted in UNIX Programmer's
     Supplementary Documents Volume 1.

HISTORY
     The socket() function call appeared in 4.2BSD.

BSD Experimental                 June 4, 1993                                3
    </screen>
  </sect1>

  <sect1 id="SOCKETPAIR">
    <title>SOCKETPAIR</title>
    <screen>

SOCKETPAIR(2)             System Programmer's Manual             SOCKETPAIR(2)

NAME
     socketpair - create a pair of connected sockets

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>

     int
     socketpair(int d, int type, int protocol, int *sv)

DESCRIPTION
     The socketpair() call creates an unnamed pair of connected sockets in the
     specified domain d, of the specified type, and using the optionally spec-
     ified protocol. The descriptors used in referencing the new sockets are
     returned in sv[0] and sv[1]. The two sockets are indistinguishable.

RETURN VALUES
     A 0 is returned if the call succeeds, -1 if it fails.

ERRORS
     The call succeeds unless:

     [EMFILE]      Too many descriptors are in use by this process.

     [EAFNOSUPPORT]
                   The specified address family is not supported on this ma-
                   chine.

     [EPROTONOSUPPORT]
                   The specified protocol is not supported on this machine.

     [EOPNOTSUPP]  The specified protocol does not support creation of socket
                   pairs.

     [EFAULT]      The address sv does not specify a valid part of the process
                   address space.

     [ENFILE]      The system file table is full.

SEE ALSO
     pipe(2),  read(2),  write(2)

BUGS
     This call is currently implemented only for the LOCAL domain.  Many oper-
     ating systems only accept a protocol of PF_UNSPEC, so that should be used
     instead of PF_LOCAL for maximal portability.

STANDARDS
     The socketpair() function conforms to .

HISTORY
     The socketpair() function call appeared in 4.2BSD.

BSD Experimental                 June 4, 1993                                1
    </screen>
  </sect1>


</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:("tcpip.sgml" "book" "chapter")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
sgml-doctype:"book"
End:
-->

