This is Info file libc.info, produced by Makeinfo version 1.67 from the
input file libc.texinfo.

   This file documents the GNU C library.

   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
Library Reference Manual', for Version 2.00 Beta.

   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.

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

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

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


File: libc.info,  Node: FIFO Special Files,  Next: Pipe Atomicity,  Prev: Pipe to a Subprocess,  Up: Pipes and FIFOs

FIFO Special Files
==================

   A FIFO special file is similar to a pipe, except that it is created
in a different way.  Instead of being an anonymous communications
channel, a FIFO special file is entered into the file system by calling
`mkfifo'.

   Once you have created a FIFO special file in this way, any process
can open it for reading or writing, in the same way as an ordinary file.
However, it has to be open at both ends simultaneously before you can
proceed to do any input or output operations on it.  Opening a FIFO for
reading normally blocks until some other process opens the same FIFO for
writing, and vice versa.

   The `mkfifo' function is declared in the header file `sys/stat.h'.

 - Function: int mkfifo (const char *FILENAME, mode_t MODE)
     The `mkfifo' function makes a FIFO special file with name
     FILENAME.  The MODE argument is used to set the file's
     permissions; see *Note Setting Permissions::.

     The normal, successful return value from `mkfifo' is `0'.  In the
     case of an error, `-1' is returned.  In addition to the usual file
     name errors (*note File Name Errors::.), the following `errno'
     error conditions are defined for this function:

    `EEXIST'
          The named file already exists.

    `ENOSPC'
          The directory or file system cannot be extended.

    `EROFS'
          The directory that would contain the file resides on a
          read-only file system.


File: libc.info,  Node: Pipe Atomicity,  Prev: FIFO Special Files,  Up: Pipes and FIFOs

Atomicity of Pipe I/O
=====================

   Reading or writing pipe data is "atomic" if the size of data written
is not greater than `PIPE_BUF'.  This means that the data transfer
seems to be an instantaneous unit, in that nothing else in the system
can observe a state in which it is partially complete.  Atomic I/O may
not begin right away (it may need to wait for buffer space or for data),
but once it does begin, it finishes immediately.

   Reading or writing a larger amount of data may not be atomic; for
example, output data from other processes sharing the descriptor may be
interspersed.  Also, once `PIPE_BUF' characters have been written,
further writes will block until some characters are read.

   *Note Limits for Files::, for information about the `PIPE_BUF'
parameter.


File: libc.info,  Node: Sockets,  Next: Low-Level Terminal Interface,  Prev: Pipes and FIFOs,  Up: Top

Sockets
*******

   This chapter describes the GNU facilities for interprocess
communication using sockets.

   A "socket" is a generalized interprocess communication channel.
Like a pipe, a socket is represented as a file descriptor.  But, unlike
pipes, sockets support communication between unrelated processes, and
even between processes running on different machines that communicate
over a network.  Sockets are the primary means of communicating with
other machines; `telnet', `rlogin', `ftp', `talk', and the other
familiar network programs use sockets.

   Not all operating systems support sockets.  In the GNU library, the
header file `sys/socket.h' exists regardless of the operating system,
and the socket functions always exist, but if the system does not
really support sockets, these functions always fail.

   *Incomplete:* We do not currently document the facilities for
broadcast messages or for configuring Internet interfaces.

* Menu:

* Socket Concepts::	Basic concepts you need to know about.
* Communication Styles::Stream communication, datagrams, and other styles.
* Socket Addresses::	How socket names ("addresses") work.
* File Namespace::	Details about the file namespace.
* Internet Namespace::	Details about the Internet namespace.
* Misc Namespaces::	Other namespaces not documented fully here.
* Open/Close Sockets::  Creating sockets and destroying them.
* Connections::		Operations on sockets with connection state.
* Datagrams::		Operations on datagram sockets.
* Inetd::		Inetd is a daemon that starts servers on request.
			   The most convenient way to write a server
			   is to make it work with Inetd.
* Socket Options::	Miscellaneous low-level socket options.
* Networks Database::   Accessing the database of network names.


File: libc.info,  Node: Socket Concepts,  Next: Communication Styles,  Up: Sockets

Socket Concepts
===============

   When you create a socket, you must specify the style of communication
you want to use and the type of protocol that should implement it.  The
"communication style" of a socket defines the user-level semantics of
sending and receiving data on the socket.  Choosing a communication
style specifies the answers to questions such as these:

   * *What are the units of data transmission?*  Some communication
     styles regard the data as a sequence of bytes, with no larger
     structure; others group the bytes into records (which are known in
     this context as "packets").

   * *Can data be lost during normal operation?*  Some communication
     styles guarantee that all the data sent arrives in the order it was
     sent (barring system or network crashes); other styles occasionally
     lose data as a normal part of operation, and may sometimes deliver
     packets more than once or in the wrong order.

     Designing a program to use unreliable communication styles usually
     involves taking precautions to detect lost or misordered packets
     and to retransmit data as needed.

   * *Is communication entirely with one partner?*  Some communication
     styles are like a telephone call--you make a "connection" with one
     remote socket, and then exchange data freely.  Other styles are
     like mailing letters--you specify a destination address for each
     message you send.

   You must also choose a "namespace" for naming the socket.  A socket
name ("address") is meaningful only in the context of a particular
namespace.  In fact, even the data type to use for a socket name may
depend on the namespace.  Namespaces are also called "domains", but we
avoid that word as it can be confused with other usage of the same
term.  Each namespace has a symbolic name that starts with `PF_'.  A
corresponding symbolic name starting with `AF_' designates the address
format for that namespace.

   Finally you must choose the "protocol" to carry out the
communication.  The protocol determines what low-level mechanism is used
to transmit and receive data.  Each protocol is valid for a particular
namespace and communication style; a namespace is sometimes called a
"protocol family" because of this, which is why the namespace names
start with `PF_'.

   The rules of a protocol apply to the data passing between two
programs, perhaps on different computers; most of these rules are
handled by the operating system, and you need not know about them.
What you do need to know about protocols is this:

   * In order to have communication between two sockets, they must
     specify the *same* protocol.

   * Each protocol is meaningful with particular style/namespace
     combinations and cannot be used with inappropriate combinations.
     For example, the TCP protocol fits only the byte stream style of
     communication and the Internet namespace.

   * For each combination of style and namespace, there is a "default
     protocol" which you can request by specifying 0 as the protocol
     number.  And that's what you should normally do--use the default.


File: libc.info,  Node: Communication Styles,  Next: Socket Addresses,  Prev: Socket Concepts,  Up: Sockets

Communication Styles
====================

   The GNU library includes support for several different kinds of
sockets, each with different characteristics.  This section describes
the supported socket types.  The symbolic constants listed here are
defined in `sys/socket.h'.

 - Macro: int SOCK_STREAM
     The `SOCK_STREAM' style is like a pipe (*note Pipes and FIFOs::.);
     it operates over a connection with a particular remote socket, and
     transmits data reliably as a stream of bytes.

     Use of this style is covered in detail in *Note Connections::.

 - Macro: int SOCK_DGRAM
     The `SOCK_DGRAM' style is used for sending individually-addressed
     packets, unreliably.  It is the diametrical opposite of
     `SOCK_STREAM'.

     Each time you write data to a socket of this kind, that data
     becomes one packet.  Since `SOCK_DGRAM' sockets do not have
     connections, you must specify the recipient address with each
     packet.

     The only guarantee that the system makes about your requests to
     transmit data is that it will try its best to deliver each packet
     you send.  It may succeed with the sixth packet after failing with
     the fourth and fifth packets; the seventh packet may arrive before
     the sixth, and may arrive a second time after the sixth.

     The typical use for `SOCK_DGRAM' is in situations where it is
     acceptable to simply resend a packet if no response is seen in a
     reasonable amount of time.

     *Note Datagrams::, for detailed information about how to use
     datagram sockets.

 - Macro: int SOCK_RAW
     This style provides access to low-level network protocols and
     interfaces.  Ordinary user programs usually have no need to use
     this style.


File: libc.info,  Node: Socket Addresses,  Next: File Namespace,  Prev: Communication Styles,  Up: Sockets

Socket Addresses
================

   The name of a socket is normally called an "address".  The functions
and symbols for dealing with socket addresses were named
inconsistently, sometimes using the term "name" and sometimes using
"address".  You can regard these terms as synonymous where sockets are
concerned.

   A socket newly created with the `socket' function has no address.
Other processes can find it for communication only if you give it an
address.  We call this "binding" the address to the socket, and the way
to do it is with the `bind' function.

   You need be concerned with the address of a socket if other processes
are to find it and start communicating with it.  You can specify an
address for other sockets, but this is usually pointless; the first time
you send data from a socket, or use it to initiate a connection, the
system assigns an address automatically if you have not specified one.

   Occasionally a client needs to specify an address because the server
discriminates based on addresses; for example, the rsh and rlogin
protocols look at the client's socket address and don't bypass password
checking unless it is less than `IPPORT_RESERVED' (*note Ports::.).

   The details of socket addresses vary depending on what namespace you
are using.  *Note File Namespace::, or *Note Internet Namespace::, for
specific information.

   Regardless of the namespace, you use the same functions `bind' and
`getsockname' to set and examine a socket's address.  These functions
use a phony data type, `struct sockaddr *', to accept the address.  In
practice, the address lives in a structure of some other data type
appropriate to the address format you are using, but you cast its
address to `struct sockaddr *' when you pass it to `bind'.

* Menu:

* Address Formats::		About `struct sockaddr'.
* Setting Address::		Binding an address to a socket.
* Reading Address::		Reading the address of a socket.


File: libc.info,  Node: Address Formats,  Next: Setting Address,  Up: Socket Addresses

Address Formats
---------------

   The functions `bind' and `getsockname' use the generic data type
`struct sockaddr *' to represent a pointer to a socket address.  You
can't use this data type effectively to interpret an address or
construct one; for that, you must use the proper data type for the
socket's namespace.

   Thus, the usual practice is to construct an address in the proper
namespace-specific type, then cast a pointer to `struct sockaddr *'
when you call `bind' or `getsockname'.

   The one piece of information that you can get from the `struct
sockaddr' data type is the "address format" designator which tells you
which data type to use to understand the address fully.

   The symbols in this section are defined in the header file
`sys/socket.h'.

 - Date Type: struct sockaddr
     The `struct sockaddr' type itself has the following members:

    `short int sa_family'
          This is the code for the address format of this address.  It
          identifies the format of the data which follows.

    `char sa_data[14]'
          This is the actual socket address data, which is
          format-dependent.  Its length also depends on the format, and
          may well be more than 14.  The length 14 of `sa_data' is
          essentially arbitrary.

   Each address format has a symbolic name which starts with `AF_'.
Each of them corresponds to a `PF_' symbol which designates the
corresponding namespace.  Here is a list of address format names:

`AF_FILE'
     This designates the address format that goes with the file
     namespace.  (`PF_FILE' is the name of that namespace.)  *Note File
     Namespace Details::, for information about this address format.

`AF_UNIX'
     This is a synonym for `AF_FILE', for compatibility.  (`PF_UNIX' is
     likewise a synonym for `PF_FILE'.)

`AF_INET'
     This designates the address format that goes with the Internet
     namespace.  (`PF_INET' is the name of that namespace.) *Note
     Internet Address Format::.

`AF_UNSPEC'
     This designates no particular address format.  It is used only in
     rare cases, such as to clear out the default destination address
     of a "connected" datagram socket.  *Note Sending Datagrams::.

     The corresponding namespace designator symbol `PF_UNSPEC' exists
     for completeness, but there is no reason to use it in a program.

   `sys/socket.h' defines symbols starting with `AF_' for many
different kinds of networks, all or most of which are not actually
implemented.  We will document those that really work, as we receive
information about how to use them.


File: libc.info,  Node: Setting Address,  Next: Reading Address,  Prev: Address Formats,  Up: Socket Addresses

Setting the Address of a Socket
-------------------------------

   Use the `bind' function to assign an address to a socket.  The
prototype for `bind' is in the header file `sys/socket.h'.  For
examples of use, see *Note File Namespace::, or see *Note Inet
Example::.

 - Function: int bind (int SOCKET, struct sockaddr *ADDR, size_t LENGTH)
     The `bind' function assigns an address to the socket SOCKET.  The
     ADDR and LENGTH arguments specify the address; the detailed format
     of the address depends on the namespace.  The first part of the
     address is always the format designator, which specifies a
     namespace, and says that the address is in the format for that
     namespace.

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

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

    `ENOTSOCK'
          The descriptor SOCKET is not a socket.

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

    `EADDRINUSE'
          Some other socket is already using the specified address.

    `EINVAL'
          The socket SOCKET already has an address.

    `EACCES'
          You do not have permission to access the requested address.
          (In the Internet domain, only the super-user is allowed to
          specify a port number in the range 0 through
          `IPPORT_RESERVED' minus one; see *Note Ports::.)

     Additional conditions may be possible depending on the particular
     namespace of the socket.


File: libc.info,  Node: Reading Address,  Prev: Setting Address,  Up: Socket Addresses

Reading the Address of a Socket
-------------------------------

   Use the function `getsockname' to examine the address of an Internet
socket.  The prototype for this function is in the header file
`sys/socket.h'.

 - Function: int getsockname (int SOCKET, struct sockaddr *ADDR, size_t
          *LENGTH-PTR)
     The `getsockname' function returns information about the address
     of the socket SOCKET in the locations specified by the ADDR and
     LENGTH-PTR arguments.  Note that the LENGTH-PTR is a pointer; you
     should initialize it to be the allocation size of ADDR, and on
     return it contains the actual size of the address data.

     The format of the address data depends on the socket namespace.
     The length of the information is usually fixed for a given
     namespace, so normally you can know exactly how much space is
     needed and can provide that much.  The usual practice is to
     allocate a place for the value using the proper data type for the
     socket's namespace, then cast its address to `struct sockaddr *'
     to pass it to `getsockname'.

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

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

    `ENOTSOCK'
          The descriptor SOCKET is not a socket.

    `ENOBUFS'
          There are not enough internal buffers available for the
          operation.

   You can't read the address of a socket in the file namespace.  This
is consistent with the rest of the system; in general, there's no way to
find a file's name from a descriptor for that file.


File: libc.info,  Node: File Namespace,  Next: Internet Namespace,  Prev: Socket Addresses,  Up: Sockets

The File Namespace
==================

   This section describes the details of the file namespace, whose
symbolic name (required when you create a socket) is `PF_FILE'.

* Menu:

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


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

File Namespace Concepts
-----------------------

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

   One peculiarity of the file namespace is that the name is only used
when opening the connection; once that is over with, the address is not
meaningful and may not exist.

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

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

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


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

Details of File Namespace
-------------------------

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

 - Macro: int PF_FILE
     This designates the file namespace, in which socket addresses are
     file names, and its associated family of protocols.

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

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

 - Data Type: struct sockaddr_un
     This structure is used to specify file 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_FILE' to designate
          the file 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 example following
          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
file 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.


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

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

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

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


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

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

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

   To create a socket in the Internet namespace, use the symbolic name
`PF_INET' of this namespace as the NAMESPACE argument to `socket' or
`socketpair'.  This macro is defined in `sys/socket.h'.

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

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

   * The address of the machine you want to connect to.  Internet
     addresses can be specified in several ways; these are discussed in
     *Note Internet Address Format::, *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 Format::     How socket addresses are specified in the
                                 Internet namespace.
* Host Addresses::	        All about host addresses of internet host.
* Protocols Database::		Referring to protocols by name.
* Ports::			Internet port numbers.
* Services Database::           Ports may have symbolic names.
* Byte Order::		        Different hosts may use different byte
                                 ordering conventions; you need to
                                 canonicalize host address and port number.
* Inet Example::	        Putting it all together.


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

Internet Socket Address Format
------------------------------

   In the Internet namespace, a socket address consists of a host
address and a port on that host.  In addition, the protocol you choose
serves effectively as a part of the address because local port numbers
are meaningful only within a particular protocol.

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

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

    `short int sin_family'
          This identifies the address family or format of the socket
          address.  You should store the value of `AF_INET' in this
          member.  *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
Internet namespace socket address.


File: libc.info,  Node: Host Addresses,  Next: Protocols Database,  Prev: Internet Address Format,  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 numeric host addresses as sequences of four
numbers, separated by periods, as in `128.52.46.32'.

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

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

* 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 Internet host address is a number containing four bytes of data.
These are divided into two parts, a "network number" and a "local
network address number" within that network.  The network number
consists of the first one, two or three bytes; the rest of the bytes
are the local address.

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

 - Macro: unsigned long int INADDR_ANY
     You can use this constant to stand for "any incoming address," when
     binding to an address.  *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: unsigned long int INADDR_BROADCAST
     This constant is the address you use to send a broadcast message.

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


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 `arpa/inet.h'.  They represent Internet addresses in
network byte order; they represent network numbers and
local-address-within-network numbers in host byte order.  *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 Internet host address NAME from the
     standard numbers-and-dots notation into binary data and stores it
     in the `struct in_addr' that ADDR points to.  `inet_aton' returns
     nonzero if the address is valid, zero if not.

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

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

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

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

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

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


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 `128.52.46.32' is also
known as `churchy.gnu.ai.mit.edu'; and other machines in the
`gnu.ai.mit.edu' domain can refer to it simply as `churchy'.

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

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

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

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

    `int h_addrtype'
          This is the host address type; in practice, its value is
          always `AF_INET'.  In principle other kinds of addresses
          could be represented in the data base as well as Internet
          addresses; if this were done, you might find a value in this
          field other than `AF_INET'.  *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 this to a `struct in_addr'
or an `unsigned long int'.  Host addresses in a `struct hostent'
structure are always given in network byte order; see *Note Byte
Order::.

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

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

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

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

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

     extern int h_errno;

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

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

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

`NO_RECOVERY'
     A non-recoverable error occurred.

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

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

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

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

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

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


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 in using these functions,
because they are not reentrant.

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

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

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

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


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 the
"network byte order".

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

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

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

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

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

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

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


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 is exchanged.  For example, the protocol implements
things like checksums to detect errors in transmissions, and routing
instructions for messages.  Normal user programs have little reason to
mess with these details directly.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

