/Sources/selp_glibc-2.5.90-19.0.46/manual/socket.texi
Unknown | 3196 lines | 2626 code | 570 blank | 0 comment | 0 complexity | 6717c0fed79090fee0ef8abd53cda7a7 MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.0, LGPL-2.1, AGPL-1.0, CC-BY-SA-3.0, BSD-3-Clause
Large files files are truncated, but you can click here to view the full file
- @node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top
- @c %MENU% A more complicated IPC mechanism, with networking support
- @chapter Sockets
- This chapter describes the GNU facilities for interprocess
- communication using sockets.
- @cindex socket
- @cindex interprocess communication, with sockets
- A @dfn{socket} is a generalized interprocess communication channel.
- Like a pipe, a socket is represented as a file descriptor. Unlike pipes
- sockets support communication between unrelated processes, and even
- between processes running on different machines that communicate over a
- network. Sockets are the primary means of communicating with other
- machines; @code{telnet}, @code{rlogin}, @code{ftp}, @code{talk} and the
- other familiar network programs use sockets.
- Not all operating systems support sockets. In the GNU library, the
- header file @file{sys/socket.h} exists regardless of the operating
- system, and the socket functions always exist, but if the system does
- not really support sockets these functions always fail.
- @strong{Incomplete:} We do not currently document the facilities for
- broadcast messages or for configuring Internet interfaces. The
- reentrant functions and some newer functions that are related to IPv6
- aren't documented either so far.
- @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.
- * Interface Naming:: Identifying specific network interfaces.
- * Local Namespace:: Details about the local namespace.
- * Internet Namespace:: Details about the Internet namespace.
- * Misc Namespaces:: Other namespaces not documented fully here.
- * Open/Close Sockets:: Creating sockets and destroying them.
- * Connections:: Operations on sockets with connection state.
- * Datagrams:: Operations on datagram sockets.
- * Inetd:: Inetd is a daemon that starts servers on request.
- The most convenient way to write a server
- is to make it work with Inetd.
- * Socket Options:: Miscellaneous low-level socket options.
- * Networks Database:: Accessing the database of network names.
- @end menu
- @node Socket Concepts
- @section Socket Concepts
- @cindex communication style (of a socket)
- @cindex style of communication (of a socket)
- When you create a socket, you must specify the style of communication
- you want to use and the type of protocol that should implement it.
- The @dfn{communication style} of a socket defines the user-level
- semantics of sending and receiving data on the socket. Choosing a
- communication style specifies the answers to questions such as these:
- @itemize @bullet
- @item
- @cindex packet
- @cindex byte stream
- @cindex stream (sockets)
- @strong{What are the units of data transmission?} Some communication
- styles regard the data as a sequence of bytes with no larger
- structure; others group the bytes into records (which are known in
- this context as @dfn{packets}).
- @item
- @cindex loss of data on sockets
- @cindex data loss on sockets
- @strong{Can data be lost during normal operation?} Some communication
- styles guarantee that all the data sent arrives in the order it was
- sent (barring system or network crashes); other styles occasionally
- lose data as a normal part of operation, and may sometimes deliver
- packets more than once or in the wrong order.
- Designing a program to use unreliable communication styles usually
- involves taking precautions to detect lost or misordered packets and
- to retransmit data as needed.
- @item
- @strong{Is communication entirely with one partner?} Some
- communication styles are like a telephone call---you make a
- @dfn{connection} with one remote socket and then exchange data
- freely. Other styles are like mailing letters---you specify a
- destination address for each message you send.
- @end itemize
- @cindex namespace (of socket)
- @cindex domain (of socket)
- @cindex socket namespace
- @cindex socket domain
- You must also choose a @dfn{namespace} for naming the socket. A socket
- name (``address'') is meaningful only in the context of a particular
- namespace. In fact, even the data type to use for a socket name may
- depend on the namespace. Namespaces are also called ``domains'', but we
- avoid that word as it can be confused with other usage of the same
- term. Each namespace has a symbolic name that starts with @samp{PF_}.
- A corresponding symbolic name starting with @samp{AF_} designates the
- address format for that namespace.
- @cindex network protocol
- @cindex protocol (of socket)
- @cindex socket protocol
- @cindex protocol family
- Finally you must choose the @dfn{protocol} to carry out the
- communication. The protocol determines what low-level mechanism is used
- to transmit and receive data. Each protocol is valid for a particular
- namespace and communication style; a namespace is sometimes called a
- @dfn{protocol family} because of this, which is why the namespace names
- start with @samp{PF_}.
- The rules of a protocol apply to the data passing between two programs,
- perhaps on different computers; most of these rules are handled by the
- operating system and you need not know about them. What you do need to
- know about protocols is this:
- @itemize @bullet
- @item
- In order to have communication between two sockets, they must specify
- the @emph{same} protocol.
- @item
- Each protocol is meaningful with particular style/namespace
- combinations and cannot be used with inappropriate combinations. For
- example, the TCP protocol fits only the byte stream style of
- communication and the Internet namespace.
- @item
- For each combination of style and namespace there is a @dfn{default
- protocol}, which you can request by specifying 0 as the protocol
- number. And that's what you should normally do---use the default.
- @end itemize
- Throughout the following description at various places
- variables/parameters to denote sizes are required. And here the trouble
- starts. In the first implementations the type of these variables was
- simply @code{int}. On most machines at that time an @code{int} was 32
- bits wide, which created a @emph{de facto} standard requiring 32-bit
- variables. This is important since references to variables of this type
- are passed to the kernel.
- Then the POSIX people came and unified the interface with the words "all
- size values are of type @code{size_t}". On 64-bit machines
- @code{size_t} is 64 bits wide, so pointers to variables were no longer
- possible.
- The Unix98 specification provides a solution by introducing a type
- @code{socklen_t}. This type is used in all of the cases that POSIX
- changed to use @code{size_t}. The only requirement of this type is that
- it be an unsigned type of at least 32 bits. Therefore, implementations
- which require that references to 32-bit variables be passed can be as
- happy as implementations which use 64-bit values.
- @node Communication Styles
- @section Communication Styles
- The GNU library includes support for several different kinds of sockets,
- each with different characteristics. This section describes the
- supported socket types. The symbolic constants listed here are
- defined in @file{sys/socket.h}.
- @pindex sys/socket.h
- @comment sys/socket.h
- @comment BSD
- @deftypevr Macro int SOCK_STREAM
- The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}).
- It operates over a connection with a particular remote socket and
- transmits data reliably as a stream of bytes.
- Use of this style is covered in detail in @ref{Connections}.
- @end deftypevr
- @comment sys/socket.h
- @comment BSD
- @deftypevr Macro int SOCK_DGRAM
- The @code{SOCK_DGRAM} style is used for sending
- individually-addressed packets unreliably.
- It is the diametrical opposite of @code{SOCK_STREAM}.
- Each time you write data to a socket of this kind, that data becomes
- one packet. Since @code{SOCK_DGRAM} sockets do not have connections,
- you must specify the recipient address with each packet.
- The only guarantee that the system makes about your requests to
- transmit data is that it will try its best to deliver each packet you
- send. It may succeed with the sixth packet after failing with the
- fourth and fifth packets; the seventh packet may arrive before the
- sixth, and may arrive a second time after the sixth.
- The typical use for @code{SOCK_DGRAM} is in situations where it is
- acceptable to simply re-send a packet if no response is seen in a
- reasonable amount of time.
- @xref{Datagrams}, for detailed information about how to use datagram
- sockets.
- @end deftypevr
- @ignore
- @c This appears to be only for the NS domain, which we aren't
- @c discussing and probably won't support either.
- @comment sys/socket.h
- @comment BSD
- @deftypevr Macro int SOCK_SEQPACKET
- This style is like @code{SOCK_STREAM} except that the data are
- structured into packets.
- A program that receives data over a @code{SOCK_SEQPACKET} socket
- should be prepared to read the entire message packet in a single call
- to @code{read}; if it only reads part of the message, the remainder of
- the message is simply discarded instead of being available for
- subsequent calls to @code{read}.
- Many protocols do not support this communication style.
- @end deftypevr
- @end ignore
- @ignore
- @comment sys/socket.h
- @comment BSD
- @deftypevr Macro int SOCK_RDM
- This style is a reliable version of @code{SOCK_DGRAM}: it sends
- individually addressed packets, but guarantees that each packet sent
- arrives exactly once.
- @strong{Warning:} It is not clear this is actually supported
- by any operating system.
- @end deftypevr
- @end ignore
- @comment sys/socket.h
- @comment BSD
- @deftypevr Macro int SOCK_RAW
- This style provides access to low-level network protocols and
- interfaces. Ordinary user programs usually have no need to use this
- style.
- @end deftypevr
- @node Socket Addresses
- @section Socket Addresses
- @cindex address of socket
- @cindex name of socket
- @cindex binding a socket address
- @cindex socket address (name) binding
- The name of a socket is normally called an @dfn{address}. The
- functions and symbols for dealing with socket addresses were named
- inconsistently, sometimes using the term ``name'' and sometimes using
- ``address''. You can regard these terms as synonymous where sockets
- are concerned.
- A socket newly created with the @code{socket} function has no
- address. Other processes can find it for communication only if you
- give it an address. We call this @dfn{binding} the address to the
- socket, and the way to do it is with the @code{bind} function.
- You need be concerned with the address of a socket if other processes
- are to find it and start communicating with it. You can specify an
- address for other sockets, but this is usually pointless; the first time
- you send data from a socket, or use it to initiate a connection, the
- system assigns an address automatically if you have not specified one.
- Occasionally a client needs to specify an address because the server
- discriminates based on address; for example, the rsh and rlogin
- protocols look at the client's socket address and only bypass password
- checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
- The details of socket addresses vary depending on what namespace you are
- using. @xref{Local Namespace}, or @ref{Internet Namespace}, for specific
- information.
- Regardless of the namespace, you use the same functions @code{bind} and
- @code{getsockname} to set and examine a socket's address. These
- functions use a phony data type, @code{struct sockaddr *}, to accept the
- address. In practice, the address lives in a structure of some other
- data type appropriate to the address format you are using, but you cast
- its address to @code{struct sockaddr *} when you pass it to
- @code{bind}.
- @menu
- * Address Formats:: About @code{struct sockaddr}.
- * Setting Address:: Binding an address to a socket.
- * Reading Address:: Reading the address of a socket.
- @end menu
- @node Address Formats
- @subsection Address Formats
- The functions @code{bind} and @code{getsockname} use the generic data
- type @code{struct sockaddr *} to represent a pointer to a socket
- address. You can't use this data type effectively to interpret an
- address or construct one; for that, you must use the proper data type
- for the socket's namespace.
- Thus, the usual practice is to construct an address of the proper
- namespace-specific type, then cast a pointer to @code{struct sockaddr *}
- when you call @code{bind} or @code{getsockname}.
- The one piece of information that you can get from the @code{struct
- sockaddr} data type is the @dfn{address format designator}. This tells
- you which data type to use to understand the address fully.
- @pindex sys/socket.h
- The symbols in this section are defined in the header file
- @file{sys/socket.h}.
- @comment sys/socket.h
- @comment BSD
- @deftp {Data Type} {struct sockaddr}
- The @code{struct sockaddr} type itself has the following members:
- @table @code
- @item short int sa_family
- This is the code for the address format of this address. It
- identifies the format of the data which follows.
- @item char sa_data[14]
- This is the actual socket address data, which is format-dependent. Its
- length also depends on the format, and may well be more than 14. The
- length 14 of @code{sa_data} is essentially arbitrary.
- @end table
- @end deftp
- Each address format has a symbolic name which starts with @samp{AF_}.
- Each of them corresponds to a @samp{PF_} symbol which designates the
- corresponding namespace. Here is a list of address format names:
- @table @code
- @comment sys/socket.h
- @comment POSIX
- @item AF_LOCAL
- @vindex AF_LOCAL
- This designates the address format that goes with the local namespace.
- (@code{PF_LOCAL} is the name of that namespace.) @xref{Local Namespace
- Details}, for information about this address format.
- @comment sys/socket.h
- @comment BSD, Unix98
- @item AF_UNIX
- @vindex AF_UNIX
- This is a synonym for @code{AF_LOCAL}. Although @code{AF_LOCAL} is
- mandated by POSIX.1g, @code{AF_UNIX} is portable to more systems.
- @code{AF_UNIX} was the traditional name stemming from BSD, so even most
- POSIX systems support it. It is also the name of choice in the Unix98
- specification. (The same is true for @code{PF_UNIX}
- vs. @code{PF_LOCAL}).
- @comment sys/socket.h
- @comment GNU
- @item AF_FILE
- @vindex AF_FILE
- This is another synonym for @code{AF_LOCAL}, for compatibility.
- (@code{PF_FILE} is likewise a synonym for @code{PF_LOCAL}.)
- @comment sys/socket.h
- @comment BSD
- @item AF_INET
- @vindex AF_INET
- This designates the address format that goes with the Internet
- namespace. (@code{PF_INET} is the name of that namespace.)
- @xref{Internet Address Formats}.
- @comment sys/socket.h
- @comment IPv6 Basic API
- @item AF_INET6
- This is similar to @code{AF_INET}, but refers to the IPv6 protocol.
- (@code{PF_INET6} is the name of the corresponding namespace.)
- @comment sys/socket.h
- @comment BSD
- @item AF_UNSPEC
- @vindex AF_UNSPEC
- This designates no particular address format. It is used only in rare
- cases, such as to clear out the default destination address of a
- ``connected'' datagram socket. @xref{Sending Datagrams}.
- The corresponding namespace designator symbol @code{PF_UNSPEC} exists
- for completeness, but there is no reason to use it in a program.
- @end table
- @file{sys/socket.h} defines symbols starting with @samp{AF_} for many
- different kinds of networks, most or all of which are not actually
- implemented. We will document those that really work as we receive
- information about how to use them.
- @node Setting Address
- @subsection Setting the Address of a Socket
- @pindex sys/socket.h
- Use the @code{bind} function to assign an address to a socket. The
- prototype for @code{bind} is in the header file @file{sys/socket.h}.
- For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}.
- @comment sys/socket.h
- @comment BSD
- @deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
- The @code{bind} function assigns an address to the socket
- @var{socket}. The @var{addr} and @var{length} arguments specify the
- address; the detailed format of the address depends on the namespace.
- The first part of the address is always the format designator, which
- specifies a namespace, and says that the address is in the format of
- that namespace.
- The return value is @code{0} on success and @code{-1} on failure. The
- following @code{errno} error conditions are defined for this function:
- @table @code
- @item EBADF
- The @var{socket} argument is not a valid file descriptor.
- @item ENOTSOCK
- The descriptor @var{socket} is not a socket.
- @item EADDRNOTAVAIL
- The specified address is not available on this machine.
- @item EADDRINUSE
- Some other socket is already using the specified address.
- @item EINVAL
- The socket @var{socket} already has an address.
- @item EACCES
- You do not have permission to access the requested address. (In the
- Internet domain, only the super-user is allowed to specify a port number
- in the range 0 through @code{IPPORT_RESERVED} minus one; see
- @ref{Ports}.)
- @end table
- Additional conditions may be possible depending on the particular namespace
- of the socket.
- @end deftypefun
- @node Reading Address
- @subsection Reading the Address of a Socket
- @pindex sys/socket.h
- Use the function @code{getsockname} to examine the address of an
- Internet socket. The prototype for this function is in the header file
- @file{sys/socket.h}.
- @comment sys/socket.h
- @comment BSD
- @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
- The @code{getsockname} function returns information about the
- address of the socket @var{socket} in the locations specified by the
- @var{addr} and @var{length-ptr} arguments. Note that the
- @var{length-ptr} is a pointer; you should initialize it to be the
- allocation size of @var{addr}, and on return it contains the actual
- size of the address data.
- The format of the address data depends on the socket namespace. The
- length of the information is usually fixed for a given namespace, so
- normally you can know exactly how much space is needed and can provide
- that much. The usual practice is to allocate a place for the value
- using the proper data type for the socket's namespace, then cast its
- address to @code{struct sockaddr *} to pass it to @code{getsockname}.
- The return value is @code{0} on success and @code{-1} on error. The
- following @code{errno} error conditions are defined for this function:
- @table @code
- @item EBADF
- The @var{socket} argument is not a valid file descriptor.
- @item ENOTSOCK
- The descriptor @var{socket} is not a socket.
- @item ENOBUFS
- There are not enough internal buffers available for the operation.
- @end table
- @end deftypefun
- You can't read the address of a socket in the file namespace. This is
- consistent with the rest of the system; in general, there's no way to
- find a file's name from a descriptor for that file.
- @node Interface Naming
- @section 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 @code{lo} (the loopback interface) and @code{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 @dfn{index}, which is
- an arbitrarily-assigned small positive integer.
- The following functions, constants and data types are declared in the
- header file @file{net/if.h}.
- @comment net/if.h
- @deftypevr Constant size_t IFNAMSIZ
- This constant defines the maximum buffer size needed to hold an
- interface name, including its terminating zero byte.
- @end deftypevr
- @comment net/if.h
- @comment IPv6 basic API
- @deftypefun {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.
- @end deftypefun
- @comment net/if.h
- @comment IPv6 basic API
- @deftypefun {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 @code{ifname}, which
- must be at least @code{IFNAMSIZ} bytes in length. If the index was
- invalid, the function's return value is a null pointer, otherwise it is
- @code{ifname}.
- @end deftypefun
- @comment net/if.h
- @comment IPv6 basic API
- @deftp {Data Type} {struct if_nameindex}
- This data type is used to hold the information about a single
- interface. It has the following members:
- @table @code
- @item unsigned int if_index;
- This is the interface index.
- @item char *if_name
- This is the null-terminated index name.
- @end table
- @end deftp
- @comment net/if.h
- @comment IPv6 basic API
- @deftypefun {struct if_nameindex *} if_nameindex (void)
- This function returns an array of @code{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 @code{if_freenameindex} after
- use.
- @end deftypefun
- @comment net/if.h
- @comment IPv6 basic API
- @deftypefun void if_freenameindex (struct if_nameindex *ptr)
- This function frees the structure returned by an earlier call to
- @code{if_nameindex}.
- @end deftypefun
- @node Local Namespace
- @section The Local Namespace
- @cindex local namespace, for sockets
- This section describes the details of the local namespace, whose
- symbolic name (required when you create a socket) is @code{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.
- @end menu
- @node Local Namespace Concepts
- @subsection 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.
- @c XXX The following was said to be wrong.
- @c In order to connect to a socket you must have read permission for it.
- It's common to put these files in the @file{/tmp} directory.
- One peculiarity of the 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 @code{unlink} or @code{remove} to
- do this; see @ref{Deleting Files}.
- The local namespace supports just one protocol for any communication
- style; it is protocol number @code{0}.
- @node Local Namespace Details
- @subsection Details of Local Namespace
- @pindex sys/socket.h
- To create a socket in the local namespace, use the constant
- @code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or
- @code{socketpair}. This constant is defined in @file{sys/socket.h}.
- @comment sys/socket.h
- @comment POSIX
- @deftypevr Macro int PF_LOCAL
- This designates the local namespace, in which socket addresses are local
- names, and its associated family of protocols. @code{PF_Local} is the
- macro used by Posix.1g.
- @end deftypevr
- @comment sys/socket.h
- @comment BSD
- @deftypevr Macro int PF_UNIX
- This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
- @end deftypevr
- @comment sys/socket.h
- @comment GNU
- @deftypevr Macro int PF_FILE
- This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
- @end deftypevr
- The structure for specifying socket names in the local namespace is
- defined in the header file @file{sys/un.h}:
- @pindex sys/un.h
- @comment sys/un.h
- @comment BSD
- @deftp {Data Type} {struct sockaddr_un}
- This structure is used to specify local namespace socket addresses. It has
- the following members:
- @table @code
- @item short int sun_family
- This identifies the address family or format of the socket address.
- You should store the value @code{AF_LOCAL} to designate the local
- namespace. @xref{Socket Addresses}.
- @item char sun_path[108]
- This is the file name to use.
- @strong{Incomplete:} Why is 108 a magic number? RMS suggests making
- this a zero-length array and tweaking the following example to use
- @code{alloca} to allocate an appropriate amount of storage based on
- the length of the filename.
- @end table
- @end deftp
- You should compute the @var{length} parameter for a socket address in
- the local namespace as the sum of the size of the @code{sun_family}
- component and the string length (@emph{not} the allocation size!) of
- the file name string. This can be done using the macro @code{SUN_LEN}:
- @comment sys/un.h
- @comment BSD
- @deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr})
- The macro computes the length of socket address in the local namespace.
- @end deftypefn
- @node Local Socket Example
- @subsection Example of Local-Namespace Sockets
- Here is an example showing how to create and name a socket in the local
- namespace.
- @smallexample
- @include mkfsock.c.texi
- @end smallexample
- @node Internet Namespace
- @section The Internet Namespace
- @cindex Internet namespace, for sockets
- This section describes the details 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
- @code{PF_INET} of this namespace as the @var{namespace} argument to
- @code{socket} or @code{socketpair}. For IPv6 addresses you need the
- macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}.
- @pindex sys/socket.h
- @comment sys/socket.h
- @comment BSD
- @deftypevr Macro int PF_INET
- This designates the IPv4 Internet namespace and associated family of
- protocols.
- @end deftypevr
- @comment sys/socket.h
- @comment X/Open
- @deftypevr Macro int PF_INET6
- This designates the IPv6 Internet namespace and associated family of
- protocols.
- @end deftypevr
- A socket address for the Internet namespace includes the following components:
- @itemize @bullet
- @item
- The address of the machine you want to connect to. Internet addresses
- can be specified in several ways; these are discussed in @ref{Internet
- Address Formats}, @ref{Host Addresses} and @ref{Host Names}.
- @item
- A port number for that machine. @xref{Ports}.
- @end itemize
- You must ensure that the address and port number are represented in a
- canonical format called @dfn{network byte order}. @xref{Byte Order},
- for information about this.
- @menu
- * Internet Address 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.
- @end menu
- @node Internet Address Formats
- @subsection Internet Socket Address Formats
- In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6
- (@code{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 @file{netinet/in.h}.
- @pindex netinet/in.h
- @comment netinet/in.h
- @comment BSD
- @deftp {Data Type} {struct sockaddr_in}
- This is the data type used to represent socket addresses in the
- Internet namespace. It has the following members:
- @table @code
- @item sa_family_t sin_family
- This identifies the address family or format of the socket address.
- You should store the value @code{AF_INET} in this member.
- @xref{Socket Addresses}.
- @item struct in_addr sin_addr
- This is the Internet address of the host machine. @xref{Host
- Addresses}, and @ref{Host Names}, for how to get a value to store
- here.
- @item unsigned short int sin_port
- This is the port number. @xref{Ports}.
- @end table
- @end deftp
- When you call @code{bind} or @code{getsockname}, you should specify
- @code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
- you are using an IPv4 Internet namespace socket address.
- @deftp {Data Type} {struct sockaddr_in6}
- This is the data type used to represent socket addresses in the IPv6
- namespace. It has the following members:
- @table @code
- @item sa_family_t sin6_family
- This identifies the address family or format of the socket address.
- You should store the value of @code{AF_INET6} in this member.
- @xref{Socket Addresses}.
- @item struct in6_addr sin6_addr
- This is the IPv6 address of the host machine. @xref{Host
- Addresses}, and @ref{Host Names}, for how to get a value to store
- here.
- @item uint32_t sin6_flowinfo
- This is a currently unimplemented field.
- @item uint16_t sin6_port
- This is the port number. @xref{Ports}.
- @end table
- @end deftp
- @node Host Addresses
- @subsection Host Addresses
- Each computer on the Internet has one or more @dfn{Internet addresses},
- numbers which identify that computer among all those on the Internet.
- Users typically write IPv4 numeric host addresses as sequences of four
- numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6
- numeric host addresses as sequences of up to eight numbers separated by
- colons, as in @samp{5f03:1200:836f:c100::1}.
- Each computer also has one or more @dfn{host names}, which are strings
- of words separated by periods, as in @samp{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.
- @end menu
- @node Abstract Host Addresses
- @subsubsection Internet Host Addresses
- @cindex host address, Internet
- @cindex Internet host address
- @ifinfo
- Each computer on the Internet has one or more Internet addresses,
- numbers which identify that computer among all those on the Internet.
- @end ifinfo
- @cindex network number
- @cindex local network address number
- An IPv4 Internet host address is a number containing four bytes of data.
- Historically these are divided into two parts, a @dfn{network number} and a
- @dfn{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 @samp{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.
- @c !!! this section could document the IN_CLASS* macros in <netinet/in.h>.
- @c No, it shouldn't since they're obsolete.
- @cindex standard dot notation, for Internet addresses
- @cindex dot notation, for Internet addresses
- There are four forms of the @dfn{standard numbers-and-dots notation}
- for Internet addresses:
- @table @code
- @item @var{a}.@var{b}.@var{c}.@var{d}
- This specifies all four bytes of the address individually and is the
- commonly used representation.
- @item @var{a}.@var{b}.@var{c}
- The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
- This is useful for specifying host addresses in a Class B network with
- network address number @code{@var{a}.@var{b}}.
- @item @var{a}.@var{b}
- The last part of the address, @var{b}, is interpreted as a 3-byte quantity.
- This is useful for specifying host addresses in a Class A network with
- network address number @var{a}.
- @item @var{a}
- If only one part is given, this corresponds directly to the host address
- number.
- @end table
- Within each part of the address, the usual C conventions for specifying
- the radix apply. In other words, a leading @samp{0x} or @samp{0X} implies
- hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
- radix is assumed.
- @subsubheading 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 @samp{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 @samp{10.0.0.0/8}.
- @subsubheading 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
- @samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}.
- @node Host Address Data Type
- @subsubsection Host Address Data Type
- IPv4 Internet host addresses are represented in some contexts as integers
- (type @code{uint32_t}). In other contexts, the integer is
- packaged inside a structure of type @code{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 @code{unsigned long int} for
- IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct
- in_addr}. Historically @code{unsigned long int} was a 32-bit number but
- with 64-bit machines this has changed. Using @code{unsigned long int}
- might break the code if it is used on machines where this type doesn't
- have 32 bits. @code{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 @code{struct in6_addr}.
- The following basic definitions for Internet addresses are declared in
- the header file @file{netinet/in.h}:
- @pindex netinet/in.h
- @comment netinet/in.h
- @comment BSD
- @deftp {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 @code{s_addr}, which records
- the host address number as an @code{uint32_t}.
- @end deftp
- @comment netinet/in.h
- @comment BSD
- @deftypevr 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
- @samp{127.0.0.1}, which is usually called @samp{localhost}. This
- special constant saves you the trouble of looking up the address of your
- own machine. Also, the system usually implements @code{INADDR_LOOPBACK}
- specially, avoiding any network traffic for the case of one machine
- talking to itself.
- @end deftypevr
- @comment netinet/in.h
- @comment BSD
- @deftypevr Macro {uint32_t} INADDR_ANY
- You can use this constant to stand for ``any incoming address'' when
- binding to an address. @xref{Setting Address}. This is the usual
- address to give in the @code{sin_addr} member of @w{@code{struct
- sockaddr_in}} when you want to accept Internet connections.
- @end deftypevr
- @comment netinet/in.h
- @comment BSD
- @deftypevr Macro {uint32_t} INADDR_BROADCAST
- This constant is the address you use to send a broadcast message.
- @c !!! broadcast needs further documented
- @end deftypevr
- @comment netinet/in.h
- @comment BSD
- @deftypevr Macro {uint32_t} INADDR_NONE
- This constant is returned by some functions to indicate an error.
- @end deftypevr
- @comment netinet/in.h
- @comment IPv6 basic API
- @deftp {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.
- @end deftp
- @comment netinet/in.h
- @comment IPv6 basic API
- @deftypevr Constant {struct in6_addr} in6addr_loopback
- This constant is the IPv6 address @samp{::1}, the loopback address. See
- above for a description of what this means. The macro
- @code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your
- own variables to this value.
- @end deftypevr
- @comment netinet/in.h
- @comment IPv6 basic API
- @deftypevr Constant {struct in6_addr} in6addr_any
- This constant is the IPv6 address @samp{::}, the unspecified address. See
- above for a description of what this means. The macro
- @code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your
- own variables to this value.
- @end deftypevr
- @node Host Address Functions
- @subsubsection Host Address Functions
- @pindex arpa/inet.h
- @noindent
- These additional functions for manipulating Internet addresses are
- declared in the header file @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. @xref{Byte
- Order}, for an explanation of network and host byte order.
- @comment arpa/inet.h
- @comment BSD
- @deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr})
- This function converts the IPv4 Internet host address @var{name}
- from the standard numbers-and-dots notation into binary data and stores
- it in the @code{struct in_addr} that @var{addr} points to.
- @code{inet_aton} returns nonzero if the address is valid, zero if not.
- @end deftypefun
- @comment arpa/inet.h
- @comment BSD
- @deftypefun {uint32_t} inet_addr (const char *@var{name})
- This function converts the IPv4 Internet host address @var{name} from the
- standard numbers-and-dots notation into binary data. If the input is
- not valid, @code{inet_addr} returns @code{INADDR_NONE}. This is an
- obsolete interface to @code{inet_aton}, described immediately above. It
- is obsolete because @code{INADDR_NONE} is a valid address
- (255.255.255.255), and @code{inet_aton} provides a cleaner way to
- indicate error return.
- @end deftypefun
- @comment arpa/inet.h
- @comment BSD
- @deftypefun {uint32_t} inet_network (const char *@var{name})
- This function extracts the network number from the address @var{name},
- given in the standard numbers-and-dots notation. The returned address is
- in host order. If the input is not valid, @code{inet_network} returns
- @code{-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.
- @end deftypefun
- @comment arpa/inet.h
- @comment BSD
- @deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
- This function converts the IPv4 Internet host address @var{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 @code{inet_ntoa} in the same
- thread will overwrite the result of the last call.
- Instead of @code{inet_ntoa} the newer function @code{inet_ntop} which is
- described below should be used since it handles both IPv4 and IPv6
- addresses.
- @end deftypefun
- @comment arpa/inet.h
- @comment BSD
- @deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local})
- This function makes an IPv4 Internet host address by combining the network
- number @var{net} with the local-address-within-network number
- @var{local}.
- @end deftypefun
- @comment arpa/inet.h
- @comment BSD
- @deftypefun uint32_t inet_lnaof (struct in_addr @var{addr})
- This function returns the local-address-within-network part of the
- Internet host address @var{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.
- @end deftypefun
- @comment arpa/inet.h
- @comment BSD
- @deftypefun uint32_t inet_netof (struct in_addr @var{addr})
- This function returns the network number part of the Internet host
- address @var{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.
- @end deftypefun
- @comment arpa/inet.h
- @comment IPv6 basic API
- @deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf})
- This function converts an Internet address (either IPv4 or IPv6) from
- presentation (textual) to network (binary) format. @var{af} should be
- either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of
- address being converted. @var{cp} is a pointer to the input string, and
- @var{buf} is a pointer to a buffer for the result. It is the caller's
- responsibility to make sure the buffer is large enough.
- @end deftypefun
- @comment arpa/inet.h
- @comment IPv6 basic API
- @deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, size_t @var{len})
- This function converts an Internet address (either IPv4 or IPv6) from
- network (binary) to presentation (textual) form. @var{af} should be
- either @code{AF_INET} or @code{AF_INET6}, as appropriate. @var{cp} is a
- pointer to the address to be converted. @var{buf} should be a pointer
- to a buffer to hold the result, and @var{len} is the length of this
- buffer. The return value from the function will be this buffer address.
- @end deftypefun
- @node Host Names
- @subsubsection Host Names
- @cindex hosts database
- @cindex converting host name to address
- @cindex converting host address to name
- 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 @samp{158.121.106.19} is also known as
- @samp{alpha.gnu.org}; and other machines in the @samp{gnu.org}
- domain can refer to it simply as @samp{alpha}.
- @pindex /etc/hosts
- @pindex netdb.h
- 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 @file{/etc/hosts} or an equivalent provided by a name server.
- The functions and other symbols for accessing this database are declared
- in @file{netdb.h}. They are BSD features, defined unconditionally if
- you include @file{netdb.h}.
- @comment netdb.h
- @comment BSD
- @deftp {Data Type} {struct hostent}
- This data type is used to represent an entry in the hosts database. It
- has the following members:
- @table @code
- @item char *h_name
- This is the ``official'' name of the host.
- @item char **h_aliases
- These are alternative names for the host, represented as a null-terminated
- vector of strings.
- @item int h_addrtype
- This is the host address type; in practice, its value is always either
- @code{AF_INET} or @code{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 @code{AF_INET} or
- @code{AF_INET6}. @xref{Socket Addresses}.
- @item int h_length
- This is the length, in bytes, of each address.
- @item 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.
- @item char *h_addr
- This is a synonym for @code{h_addr_list[0]}; in other words, it is the
- first host address.
- @end table
- @end deftp
- As far as the host database is concerned, each address is just a block
- of memory @code{h_length} bytes long. But in other contexts there is an
- implicit assumption that you can convert IPv4 addresses to a
- @code{struct in_addr} or an @code{uint32_t}. Host addresses in
- a @code{struct hostent} structure are always given in network byte
- order; see @ref{Byte Order}.
- You can use @code{gethostbyname}, @code{gethostbyname2} or
- @code{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 @code{getaddrinfo} and
- @code{getnameinfo} to obtain this information.
- @comment netdb.h
- @comment BSD
- @deftypefun {struct hostent *} gethostbyname (const char *@var{name})
- The @code{gethostbyname} function returns information about the host
- named @var{name}. If the lookup fails, it returns a null pointer.
- @end deftypefun
- @comment netdb.h
- @comment IPv6 Basic API
- @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
- The @code{gethostbyname2} function is like @code{gethostbyname}, but
- allows the caller to specify the desired address family (e.g.@:
- @code{AF_INET} or @code{AF_INET6}) of the result.
- @end deftypefun
- @comment netdb.h
- @comment BSD
- @deftypefun {struct hostent *} gethostbyaddr (const char *@var{addr}, size_t @var{length}, int @var{format})
- The @code{gethostbyaddr} function returns information about the host
- with Internet address @var{addr}. The parameter @var{addr} is not
- really a pointer to char - it can be a pointer to an IPv4 or an IPv6
- address. The @var{length} argument is the size (in bytes) of the address
- at @var{addr}. @var{format} specifies the address format; for an IPv4
- Internet address, specify a value of @code{AF_INET}; for an IPv6
- Internet address, use @code{AF_INET6}.
- If the lookup fails, @code{gethostbyaddr} returns a null pointer.
- @end deftypefun
- @vindex h_errno
- If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
- fails, you can find out the reason by looking at the value of the
- variable @code{h_errno}. (It would be cleaner design for these
- functions to set @code{errno}, but use of @code{h_errno} is compatible
- with other systems.)
- Here are the error codes that you may find in @code{h_errno}:
- @table @code
- @comment netdb.h
- @comment BSD
- @item HOST_NOT_FOUND
- @vindex HOST_NOT_FOUND
- No such host is known in the database.
- @comment netdb.h
- @comment BSD
- @item TRY_AGAIN
- @vindex TRY_AGAIN
- This condition happens when the name server could not be contacted. If
- you try again later, you may succeed then.
- @comment netdb.h
- @comment BSD
- @item NO_RECOVERY
- @vindex NO_RECOVERY
- A non-recoverable error occurred.
- @comment netdb.h
- @comment BSD
- @item NO_ADDRESS
- @vindex NO_ADDRESS
- The host database contains an entry for the name, but it doesn't have an
- associated Internet address.
- @end table
- 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.
- @comment netdb.h
- @comment GNU
- @deftypefun int gethostbyname_r (const char *restrict @var{name}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop})
- The @code{gethos…
Large files files are truncated, but you can click here to view the full file