This is libc.info, produced by makeinfo version 4.0b from libc.texinfo.

INFO-DIR-SECTION GNU libraries
START-INFO-DIR-ENTRY
* Libc: (libc).                 C library.
END-INFO-DIR-ENTRY

   This file documents the GNU C library.

   This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
Reference Manual', for Version 2.2.x.

   Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001 Free
Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU Lesser General Public License", the
Front-Cover texts being (a) (see below), and with the Back-Cover Texts
being (b) (see below).  A copy of the license is included in the section
entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.


File: libc.info,  Node: Interface Naming,  Next: Local Namespace,  Prev: Socket Addresses,  Up: Sockets

Interface Naming
================

   Each network interface has a name.  This usually consists of a few
letters that relate to the type of interface, which may be followed by a
number if there is more than one interface of that type.  Examples
might be `lo' (the loopback interface) and `eth0' (the first Ethernet
interface).

   Although such names are convenient for humans, it would be clumsy to
have to use them whenever a program needs to refer to an interface.  In
such situations an interface is referred to by its "index", which is an
arbitrarily-assigned small positive integer.

   The following functions, constants and data types are declared in the
header file `net/if.h'.

 - Constant: size_t IFNAMSIZ
     This constant defines the maximum buffer size needed to hold an
     interface name, including its terminating zero byte.

 - Function: unsigned int if_nametoindex (const char *ifname)
     This function yields the interface index corresponding to a
     particular name.  If no interface exists with the name given, it
     returns 0.

 - Function: char * if_indextoname (unsigned int ifindex, char *ifname)
     This function maps an interface index to its corresponding name.
     The returned name is placed in the buffer pointed to by `ifname',
     which must be at least `IFNAMSIZ' bytes in length.  If the index
     was invalid, the function's return value is a null pointer,
     otherwise it is `ifname'.

 - Data Type: struct if_nameindex
     This data type is used to hold the information about a single
     interface.  It has the following members:

    `unsigned int if_index;'
          This is the interface index.

    `char *if_name'
          This is the null-terminated index name.


 - Function: struct if_nameindex * if_nameindex (void)
     This function returns an array of `if_nameindex' structures, one
     for every interface that is present.  The end of the list is
     indicated by a structure with an interface of 0 and a null name
     pointer.  If an error occurs, this function returns a null pointer.

     The returned structure must be freed with `if_freenameindex' after
     use.

 - Function: void if_freenameindex (struct if_nameindex *ptr)
     This function frees the structure returned by an earlier call to
     `if_nameindex'.


File: libc.info,  Node: Local Namespace,  Next: Internet Namespace,  Prev: Interface Naming,  Up: Sockets

The Local Namespace
===================

   This section describes the details of the local namespace, whose
symbolic name (required when you create a socket) is `PF_LOCAL'.  The
local namespace is also known as "Unix domain sockets".  Another name
is file namespace since socket addresses are normally implemented as
file names.

* Menu:

* Concepts: Local Namespace Concepts. What you need to understand.
* Details: Local Namespace Details.   Address format, symbolic names, etc.
* Example: Local Socket Example.      Example of creating a socket.


File: libc.info,  Node: Local Namespace Concepts,  Next: Local Namespace Details,  Up: Local Namespace

Local Namespace Concepts
------------------------

   In the local namespace socket addresses are file names.  You can
specify any file name you want as the address of the socket, but you
must have write permission on the directory containing it.  It's common
to put these files in the `/tmp' directory.

   One peculiarity of the local namespace is that the name is only used
when opening the connection; once open the address is not meaningful and
may not exist.

   Another peculiarity is that you cannot connect to such a socket from
another machine-not even if the other machine shares the file system
which contains the name of the socket.  You can see the socket in a
directory listing, but connecting to it never succeeds.  Some programs
take advantage of this, such as by asking the client to send its own
process ID, and using the process IDs to distinguish between clients.
However, we recommend you not use this method in protocols you design,
as we might someday permit connections from other machines that mount
the same file systems.  Instead, send each new client an identifying
number if you want it to have one.

   After you close a socket in the local namespace, you should delete
the file name from the file system.  Use `unlink' or `remove' to do
this; see *Note Deleting Files::.

   The local namespace supports just one protocol for any communication
style; it is protocol number `0'.


File: libc.info,  Node: Local Namespace Details,  Next: Local Socket Example,  Prev: Local Namespace Concepts,  Up: Local Namespace

Details of Local Namespace
--------------------------

   To create a socket in the local namespace, use the constant
`PF_LOCAL' as the NAMESPACE argument to `socket' or `socketpair'.  This
constant is defined in `sys/socket.h'.

 - Macro: int PF_LOCAL
     This designates the local namespace, in which socket addresses are
     local names, and its associated family of protocols.  `PF_Local'
     is the macro used by Posix.1g.

 - Macro: int PF_UNIX
     This is a synonym for `PF_LOCAL', for compatibility's sake.

 - Macro: int PF_FILE
     This is a synonym for `PF_LOCAL', for compatibility's sake.

   The structure for specifying socket names in the local namespace is
defined in the header file `sys/un.h':

 - Data Type: struct sockaddr_un
     This structure is used to specify local namespace socket
     addresses.  It has the following members:

    `short int sun_family'
          This identifies the address family or format of the socket
          address.  You should store the value `AF_LOCAL' to designate
          the local namespace.  *Note Socket Addresses::.

    `char sun_path[108]'
          This is the file name to use.

          *Incomplete:*  Why is 108 a magic number?  RMS suggests making
          this a zero-length array and tweaking the following example
          to use `alloca' to allocate an appropriate amount of storage
          based on the length of the filename.

   You should compute the LENGTH parameter for a socket address in the
local namespace as the sum of the size of the `sun_family' component
and the string length (_not_ the allocation size!) of the file name
string.  This can be done using the macro `SUN_LEN':

 - Macro: int SUN_LEN (_struct sockaddr_un *_ PTR)
     The macro computes the length of socket address in the local
     namespace.


File: libc.info,  Node: Local Socket Example,  Prev: Local Namespace Details,  Up: Local Namespace

Example of Local-Namespace Sockets
----------------------------------

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

     #include <stddef.h>
     #include <stdio.h>
     #include <errno.h>
     #include <stdlib.h>
     #include <sys/socket.h>
     #include <sys/un.h>
     
     int
     make_named_socket (const char *filename)
     {
       struct sockaddr_un name;
       int sock;
       size_t size;
     
       /* Create the socket. */
       sock = socket (PF_LOCAL, SOCK_DGRAM, 0);
       if (sock < 0)
         {
           perror ("socket");
           exit (EXIT_FAILURE);
         }
     
       /* Bind a name to the socket. */
       name.sun_family = AF_LOCAL;
       strncpy (name.sun_path, filename, sizeof (name.sun_path));
     
       /* The size of the address is
          the offset of the start of the filename,
          plus its length,
          plus one for the terminating null byte.
          Alternatively you can just do:
          size = SUN_LEN (&name);
      */
       size = (offsetof (struct sockaddr_un, sun_path)
               + strlen (name.sun_path) + 1);
     
       if (bind (sock, (struct sockaddr *) &name, size) < 0)
         {
           perror ("bind");
           exit (EXIT_FAILURE);
         }
     
       return sock;
     }


File: libc.info,  Node: Internet Namespace,  Next: Misc Namespaces,  Prev: Local Namespace,  Up: Sockets

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

   This section describes the details of the protocols and socket naming
conventions used in the Internet namespace.

   Originally the Internet namespace used only IP version 4 (IPv4).
With the growing number of hosts on the Internet, a new protocol with a
larger address space was necessary: IP version 6 (IPv6).  IPv6
introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
features, and will eventually replace IPv4.

   To create a socket in the IPv4 Internet namespace, use the symbolic
name `PF_INET' of this namespace as the NAMESPACE argument to `socket'
or `socketpair'.  For IPv6 addresses you need the macro `PF_INET6'.
These macros are defined in `sys/socket.h'.

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

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

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

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

   * A port number for that machine.  *Note Ports::.

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

* Menu:

* Internet Address Formats::    How socket addresses are specified in the
                                 Internet namespace.
* Host Addresses::	        All about host addresses of Internet host.
* Protocols Database::		Referring to protocols by name.
* Ports::			Internet port numbers.
* Services Database::           Ports may have symbolic names.
* Byte Order::		        Different hosts may use different byte
                                 ordering conventions; you need to
                                 canonicalize host address and port number.
* Inet Example::	        Putting it all together.


File: libc.info,  Node: Internet Address Formats,  Next: Host Addresses,  Up: Internet Namespace

Internet Socket Address Formats
-------------------------------

   In the Internet namespace, for both IPv4 (`AF_INET') and IPv6
(`AF_INET6'), a socket address consists of a host address and a port on
that host.  In addition, the protocol you choose serves effectively as
a part of the address because local port numbers are meaningful only
within a particular protocol.

   The data types for representing socket addresses in the Internet
namespace are defined in the header file `netinet/in.h'.

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

    `sa_family_t sin_family'
          This identifies the address family or format of the socket
          address.  You should store the value `AF_INET' in this member.
          *Note Socket Addresses::.

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

    `unsigned short int sin_port'
          This is the port number.  *Note Ports::.

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

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

    `sa_family_t sin6_family'
          This identifies the address family or format of the socket
          address.  You should store the value of `AF_INET6' in this
          member.  *Note Socket Addresses::.

    `struct in6_addr sin6_addr'
          This is the IPv6 address of the host machine.  *Note Host
          Addresses::, and *Note Host Names::, for how to get a value
          to store here.

    `uint32_t sin6_flowinfo'
          This is a currently unimplemented field.

    `uint16_t sin6_port'
          This is the port number.  *Note Ports::.



File: libc.info,  Node: Host Addresses,  Next: Protocols Database,  Prev: Internet Address Formats,  Up: Internet Namespace

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

   Each computer on the Internet has one or more "Internet addresses",
numbers which identify that computer among all those on the Internet.
Users typically write IPv4 numeric host addresses as sequences of four
numbers, separated by periods, as in `128.52.46.32', and IPv6 numeric
host addresses as sequences of up to eight numbers separated by colons,
as in `5f03:1200:836f:c100::1'.

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

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

* Menu:

* Abstract Host Addresses::	What a host number consists of.
* Data type: Host Address Data Type.	Data type for a host number.
* Functions: Host Address Functions.	Functions to operate on them.
* Names: Host Names.		Translating host names to host numbers.


File: libc.info,  Node: Abstract Host Addresses,  Next: Host Address Data Type,  Up: Host Addresses

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

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

   An IPv4 Internet host address is a number containing four bytes of
data.  Historically these are divided into two parts, a "network
number" and a "local network address number" within that network.  In
the mid-1990s classless addresses were introduced which changed this
behavior.  Since some functions implicitly expect the old definitions,
we first describe the class-based network and will then describe
classless addresses.  IPv6 uses only classless addresses and therefore
the following paragraphs don't apply.

   The class-based IPv4 network number consists of the first one, two or
three bytes; the rest of the bytes are the local address.

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

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

   The Class A network 0 is reserved for broadcast to all networks.  In
addition, the host number 0 within each network is reserved for
broadcast to all hosts in that network.  These uses are obsolete now
but for compatibility reasons you shouldn't use network 0 and host
number 0.

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

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

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

`A.B.C.D'
     This specifies all four bytes of the address individually and is
     the commonly used representation.

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

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

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

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

Classless Addresses
...................

   IPv4 addresses (and IPv6 addresses also) are now considered
classless; the distinction between classes A, B and C can be ignored.
Instead an IPv4 host address consists of a 32-bit address and a 32-bit
mask.  The mask contains set bits for the network part and cleared bits
for the host part.  The network part is contiguous from the left, with
the remaining bits representing the host.  As a consequence, the
netmask can simply be specified as the number of set bits.  Classes A,
B and C are just special cases of this general rule.  For example,
class A addresses have a netmask of `255.0.0.0' or a prefix length of 8.

   Classless IPv4 network addresses are written in numbers-and-dots
notation with the prefix length appended and a slash as separator.  For
example the class A network 10 is written as `10.0.0.0/8'.

IPv6 Addresses
..............

   IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data.  A host
address is usually written as eight 16-bit hexadecimal numbers that are
separated by colons.  Two colons are used to abbreviate strings of
consecutive zeros.  For example, the IPv6 loopback address
`0:0:0:0:0:0:0:1' can just be written as `::1'.


File: libc.info,  Node: Host Address Data Type,  Next: Host Address Functions,  Prev: Abstract Host Addresses,  Up: Host Addresses

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

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

   You will find older code that uses `unsigned long int' for IPv4
Internet host addresses instead of `uint32_t' or `struct in_addr'.
Historically `unsigned long int' was a 32-bit number but with 64-bit
machines this has changed.  Using `unsigned long int' might break the
code if it is used on machines where this type doesn't have 32 bits.
`uint32_t' is specified by Unix98 and guaranteed to have 32 bits.

   IPv6 Internet host addresses have 128 bits and are packaged inside a
structure of type `struct in6_addr'.

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

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

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

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

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

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

 - Data Type: struct in6_addr
     This data type is used to store an IPv6 address.  It stores 128
     bits of data, which can be accessed (via a union) in a variety of
     ways.

 - Constant: struct in6_addr in6addr_loopback
     This constant is the IPv6 address `::1', the loopback address.  See
     above for a description of what this means.  The macro
     `IN6ADDR_LOOPBACK_INIT' is provided to allow you to initialize your
     own variables to this value.

 - Constant: struct in6_addr in6addr_any
     This constant is the IPv6 address `::', the unspecified address.
     See above for a description of what this means.  The macro
     `IN6ADDR_ANY_INIT' is provided to allow you to initialize your own
     variables to this value.


File: libc.info,  Node: Host Address Functions,  Next: Host Names,  Prev: Host Address Data Type,  Up: Host Addresses

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

These additional functions for manipulating Internet addresses are
declared in the header file `arpa/inet.h'.  They represent Internet
addresses in network byte order, and network numbers and
local-address-within-network numbers in host byte order.  *Note Byte
Order::, for an explanation of network and host byte order.

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

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

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

     The function works only with traditional IPv4 class A, B and C
     network types.  It doesn't work with classless addresses and
     shouldn't be used anymore.

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

     In multi-threaded programs each thread has an own
     statically-allocated buffer.  But still subsequent calls of
     `inet_ntoa' in the same thread will overwrite the result of the
     last call.

     Instead of `inet_ntoa' the newer function `inet_ntop' which is
     described below should be used since it handles both IPv4 and IPv6
     addresses.

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

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

     The function works only with traditional IPv4 class A, B and C
     network types.  It doesn't work with classless addresses and
     shouldn't be used anymore.

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

     The function works only with traditional IPv4 class A, B and C
     network types.  It doesn't work with classless addresses and
     shouldn't be used anymore.

 - Function: int inet_pton (int AF, const char *CP, void *BUF)
     This function converts an Internet address (either IPv4 or IPv6)
     from presentation (textual) to network (binary) format.  AF should
     be either `AF_INET' or `AF_INET6', as appropriate for the type of
     address being converted.  CP is a pointer to the input string, and
     BUF is a pointer to a buffer for the result.  It is the caller's
     responsibility to make sure the buffer is large enough.

 - Function: const char * inet_ntop (int AF, const void *CP, char *BUF,
          size_t LEN)
     This function converts an Internet address (either IPv4 or IPv6)
     from network (binary) to presentation (textual) form.  AF should be
     either `AF_INET' or `AF_INET6', as appropriate.  CP is a pointer
     to the address to be converted.  BUF should be a pointer to a
     buffer to hold the result, and LEN is the length of this buffer.
     The return value from the function will be this buffer address.


File: libc.info,  Node: Host Names,  Prev: Host Address Functions,  Up: Host Addresses

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

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

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

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

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

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

    `int h_addrtype'
          This is the host address type; in practice, its value is
          always either `AF_INET' or `AF_INET6', with the latter being
          used for IPv6 hosts.  In principle other kinds of addresses
          could be represented in the database as well as Internet
          addresses; if this were done, you might find a value in this
          field other than `AF_INET' or `AF_INET6'.  *Note Socket
          Addresses::.

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

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

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

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

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

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

 - Function: struct hostent * gethostbyname2 (const char *NAME, int AF)
     The `gethostbyname2' function is like `gethostbyname', but allows
     the caller to specify the desired address family (e.g.  `AF_INET'
     or `AF_INET6') of the result.

 - Function: struct hostent * gethostbyaddr (const char *ADDR, size_t
          LENGTH, int FORMAT)
     The `gethostbyaddr' function returns information about the host
     with Internet address ADDR.  The parameter ADDR is not really a
     pointer to char - it can be a pointer to an IPv4 or an IPv6
     address. The LENGTH argument is the size (in bytes) of the address
     at ADDR.  FORMAT specifies the address format; for an IPv4
     Internet address, specify a value of `AF_INET'; for an IPv6
     Internet address, use `AF_INET6'.

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

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

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

`HOST_NOT_FOUND'
     No such host is known in the database.

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

`NO_RECOVERY'
     A non-recoverable error occurred.

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

   The lookup functions above all have one in common: they are not
reentrant and therefore unusable in multi-threaded applications.
Therefore provides the GNU C library a new set of functions which can be
used in this context.

 - Function: int gethostbyname_r (const char *restrict NAME, struct
          hostent *restrict RESULT_BUF, char *restrict BUF, size_t
          BUFLEN, struct hostent **restrict RESULT, int *restrict
          H_ERRNOP)
     The `gethostbyname_r' function returns information about the host
     named NAME.  The caller must pass a pointer to an object of type
     `struct hostent' in the RESULT_BUF parameter.  In addition the
     function may need extra buffer space and the caller must pass an
     pointer and the size of the buffer in the BUF and BUFLEN
     parameters.

     A pointer to the buffer, in which the result is stored, is
     available in `*RESULT' after the function call successfully
     returned.  If an error occurs or if no entry is found, the pointer
     `*RESULT' is a null pointer.  Success is signalled by a zero
     return value.  If the function failed the return value is an error
     number.  In addition to the errors defined for `gethostbyname' it
     can also be `ERANGE'.  In this case the call should be repeated
     with a larger buffer.  Additional error information is not stored
     in the global variable `h_errno' but instead in the object pointed
     to by H_ERRNOP.

     Here's a small example:
          struct hostent *
          gethostname (char *host)
          {
            struct hostent hostbuf, *hp;
            size_t hstbuflen;
            char *tmphstbuf;
            int res;
            int herr;
          
            hstbuflen = 1024;
            /* Allocate buffer, remember to free it to avoid memory leakage.  */
            tmphstbuf = malloc (hstbuflen);
          
            while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen,
                                           &hp, &herr)) == ERANGE)
              {
                /* Enlarge the buffer.  */
                hstbuflen *= 2;
                tmphstbuf = realloc (tmphstbuf, hstbuflen);
              }
            /*  Check for errors.  */
            if (res || hp == NULL)
              return NULL;
            return hp;
          }

 - Function: int gethostbyname2_r (const char *NAME, int AF, struct
          hostent *restrict RESULT_BUF, char *restrict BUF, size_t
          BUFLEN, struct hostent **restrict RESULT, int *restrict
          H_ERRNOP)
     The `gethostbyname2_r' function is like `gethostbyname_r', but
     allows the caller to specify the desired address family (e.g.
     `AF_INET' or `AF_INET6') for the result.

 - Function: int gethostbyaddr_r (const char *ADDR, size_t LENGTH, int
          FORMAT, struct hostent *restrict RESULT_BUF, char *restrict
          BUF, size_t BUFLEN, struct hostent **restrict RESULT, int
          *restrict H_ERRNOP)
     The `gethostbyaddr_r' function returns information about the host
     with Internet address ADDR.  The parameter ADDR is not really a
     pointer to char - it can be a pointer to an IPv4 or an IPv6
     address. The LENGTH argument is the size (in bytes) of the address
     at ADDR.  FORMAT specifies the address format; for an IPv4
     Internet address, specify a value of `AF_INET'; for an IPv6
     Internet address, use `AF_INET6'.

     Similar to the `gethostbyname_r' function, the caller must provide
     buffers for the result and memory used internally.  In case of
     success the function returns zero.  Otherwise the value is an
     error number where `ERANGE' has the special meaning that the
     caller-provided buffer is too small.

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

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

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

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

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


File: libc.info,  Node: Ports,  Next: Services Database,  Prev: Protocols Database,  Up: Internet Namespace

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

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

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

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

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

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

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

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

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


File: libc.info,  Node: Services Database,  Next: Byte Order,  Prev: Ports,  Up: Internet Namespace

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


File: libc.info,  Node: Byte Order,  Next: Inet Example,  Prev: Services Database,  Up: Internet Namespace

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

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

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

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

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

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

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

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

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

     This is used for IPv4 Internet addresses.

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

     This is used for IPv4 Internet addresses.


File: libc.info,  Node: Protocols Database,  Next: Ports,  Prev: Host Addresses,  Up: Internet Namespace

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


File: libc.info,  Node: Inet Example,  Prev: Byte Order,  Up: Internet Namespace

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

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

     #include <stdio.h>
     #include <stdlib.h>
     #include <sys/socket.h>
     #include <netinet/in.h>
     
     int
     make_socket (uint16_t port)
     {
       int sock;
       struct sockaddr_in name;
     
       /* Create the socket. */
       sock = socket (PF_INET, SOCK_STREAM, 0);
       if (sock < 0)
         {
           perror ("socket");
           exit (EXIT_FAILURE);
         }
     
       /* Give the socket a name. */
       name.sin_family = AF_INET;
       name.sin_port = htons (port);
       name.sin_addr.s_addr = htonl (INADDR_ANY);
       if (bind (sock, (struct sockaddr *) &name, sizeof (name)) < 0)
         {
           perror ("bind");
           exit (EXIT_FAILURE);
         }
     
       return sock;
     }

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

     #include <stdio.h>
     #include <stdlib.h>
     #include <sys/socket.h>
     #include <netinet/in.h>
     #include <netdb.h>
     
     void
     init_sockaddr (struct sockaddr_in *name,
                    const char *hostname,
                    uint16_t port)
     {
       struct hostent *hostinfo;
     
       name->sin_family = AF_INET;
       name->sin_port = htons (port);
       hostinfo = gethostbyname (hostname);
       if (hostinfo == NULL)
         {
           fprintf (stderr, "Unknown host %s.\n", hostname);
           exit (EXIT_FAILURE);
         }
       name->sin_addr = *(struct in_addr *) hostinfo->h_addr;
     }


File: libc.info,  Node: Misc Namespaces,  Next: Open/Close Sockets,  Prev: Internet Namespace,  Up: Sockets

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

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

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


File: libc.info,  Node: Open/Close Sockets,  Next: Connections,  Prev: Misc Namespaces,  Up: Sockets

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

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

* Menu:

* Creating a Socket::           How to open a socket.
* Closing a Socket::            How to close a socket.
* Socket Pairs::                These are created like pipes.

