2918 lines
107 KiB
Plaintext
2918 lines
107 KiB
Plaintext
@node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top
|
|
@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. 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; @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.
|
|
|
|
@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.
|
|
@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}. This type was on almost all machines of this time 32
|
|
bits wide and so a de-factor standard required 32 bit variables. This
|
|
is important since references to variables of this type are passed to
|
|
the kernel.
|
|
|
|
But now the POSIX people came and unified the interface with their words
|
|
"all size values are of type @code{size_t}". But on 64 bit machines
|
|
@code{size_t} is 64 bits wide and so variable references are not anymore
|
|
possible.
|
|
|
|
A solution provides the Unix98 specification which finally introduces a
|
|
type @code{socklen_t}. This type is used in all of the cases that were
|
|
previously changed to use @code{size_t}. The only requirement of this
|
|
type is that it is an unsigned type of at least 32 bits. Therefore,
|
|
implementations which require references to 32 bit variables be passed
|
|
can be as happy as implementations which use right from the start 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 resend 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 is
|
|
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 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 @code{IPPORT_RESERVED} (@pxref{Ports}).
|
|
|
|
The details of socket addresses vary depending on what namespace you are
|
|
using. @xref{File 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 in 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 which 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 {Date 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 GNU
|
|
@item AF_FILE
|
|
@vindex AF_FILE
|
|
This designates the address format that goes with the file namespace.
|
|
(@code{PF_FILE} is the name of that namespace.) @xref{File Namespace
|
|
Details}, for information about this address format.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item AF_UNIX
|
|
@vindex AF_UNIX
|
|
This is a synonym for @code{AF_FILE}, for compatibility.
|
|
(@code{PF_UNIX} is likewise a synonym for @code{PF_FILE}.)
|
|
|
|
@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, 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.
|
|
|
|
@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{File Namespace}, 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 for
|
|
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 File Namespace
|
|
@section The File Namespace
|
|
@cindex file namespace, for sockets
|
|
|
|
This section describes the details of the file namespace, whose
|
|
symbolic name (required when you create a socket) is @code{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.
|
|
@end menu
|
|
|
|
@node File Namespace Concepts
|
|
@subsection 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 @file{/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 @code{unlink} or @code{remove} to
|
|
do this; see @ref{Deleting Files}.
|
|
|
|
The file namespace supports just one protocol for any communication
|
|
style; it is protocol number @code{0}.
|
|
|
|
@node File Namespace Details
|
|
@subsection Details of File Namespace
|
|
|
|
@pindex sys/socket.h
|
|
To create a socket in the file namespace, use the constant
|
|
@code{PF_FILE} 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 GNU
|
|
@deftypevr Macro int PF_FILE
|
|
This designates the file namespace, in which socket addresses are file
|
|
names, and its associated family of protocols.
|
|
@end deftypevr
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypevr Macro int PF_UNIX
|
|
This is a synonym for @code{PF_FILE}, for compatibility's sake.
|
|
@end deftypevr
|
|
|
|
The structure for specifying socket names in the file 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 file 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_FILE} to designate the file
|
|
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 example following 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 file 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.
|
|
|
|
@node File Socket Example
|
|
@subsection Example of File-Namespace Sockets
|
|
|
|
Here is an example showing how to create and name a socket in the file
|
|
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 the protocols and socket naming
|
|
conventions used in the Internet namespace.
|
|
|
|
To create a socket in the Internet namespace, use the symbolic name
|
|
@code{PF_INET} of this namespace as the @var{namespace} argument to
|
|
@code{socket} or @code{socketpair}. This macro is defined in
|
|
@file{sys/socket.h}.
|
|
@pindex sys/socket.h
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypevr Macro int PF_INET
|
|
This designates the 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 short int sin_family
|
|
This identifies the address family or format of the socket address.
|
|
You should store the value of @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 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 short int 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{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.
|
|
@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
|
|
|
|
@c I think this whole section could possibly be removed. It is slightly
|
|
@c misleading these days.
|
|
|
|
@cindex network number
|
|
@cindex local network address number
|
|
An Internet host address is a number containing four bytes of data.
|
|
These are divided into two parts, a @dfn{network number} and a
|
|
@dfn{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 @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>.
|
|
|
|
@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.
|
|
|
|
@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{c}, 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.
|
|
|
|
@node Host Address Data Type
|
|
@subsubsection Host Address Data Type
|
|
|
|
Internet host addresses are represented in some contexts as integers
|
|
(type @code{unsigned long int}). 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.
|
|
|
|
The following basic definitions for Internet addresses appear 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 Internet host
|
|
address. It has just one field, named @code{s_addr}, which records the
|
|
host address number as an @code{unsigned long int}.
|
|
@end deftp
|
|
|
|
@comment netinet/in.h
|
|
@comment BSD
|
|
@deftypevr Macro {unsigned 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
|
|
@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 {unsigned int} 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 {unsigned int} 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 {unsigned int} 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 initialise 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 initialise your
|
|
own variables to this value.
|
|
@end deftypevr
|
|
|
|
@node Host Address Functions
|
|
@subsubsection Host Address Functions
|
|
|
|
@pindex arpa/inet.h
|
|
These additional functions for manipulating Internet addresses are
|
|
declared in @file{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.
|
|
@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 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 {unsigned long int} inet_addr (const char *@var{name})
|
|
This function converts the 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 {unsigned long int} 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}.
|
|
@end deftypefun
|
|
|
|
@comment arpa/inet.h
|
|
@comment BSD
|
|
@deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
|
|
This function converts the 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.
|
|
@end deftypefun
|
|
|
|
@comment arpa/inet.h
|
|
@comment BSD
|
|
@deftypefun {struct in_addr} inet_makeaddr (int @var{net}, int @var{local})
|
|
This function makes an 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 int inet_lnaof (struct in_addr @var{addr})
|
|
This function returns the local-address-within-network part of the
|
|
Internet host address @var{addr}.
|
|
@end deftypefun
|
|
|
|
@comment arpa/inet.h
|
|
@comment BSD
|
|
@deftypefun int inet_netof (struct in_addr @var{addr})
|
|
This function returns the network number part of the Internet host
|
|
address @var{addr}.
|
|
@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 {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{128.52.46.32} is also known as
|
|
@samp{churchy.gnu.ai.mit.edu}; and other machines in the @samp{gnu.ai.mit.edu}
|
|
domain can refer to it simply as @samp{churchy}.
|
|
|
|
@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 data base 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 this to a @code{struct in_addr} or
|
|
an @code{unsigned long int}. 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}) for the result.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {struct hostent *} gethostbyaddr (const char *@var{addr}, int @var{length}, int @var{format})
|
|
The @code{gethostbyaddr} function returns information about the host
|
|
with Internet address @var{addr}. The @var{length} argument is the
|
|
size (in bytes) of the address at @var{addr}. @var{format} specifies
|
|
the address format; for an Internet address, specify a value of
|
|
@code{AF_INET}.
|
|
|
|
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.) Before using @code{h_errno}, you must declare it
|
|
like this:
|
|
|
|
@smallexample
|
|
extern int h_errno;
|
|
@end smallexample
|
|
|
|
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 data base.
|
|
|
|
@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
|
|
|
|
You can also scan the entire hosts database one entry at a time using
|
|
@code{sethostent}, @code{gethostent}, and @code{endhostent}. Be careful
|
|
in using these functions, because they are not reentrant.
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun void sethostent (int @var{stayopen})
|
|
This function opens the hosts database to begin scanning it. You can
|
|
then call @code{gethostent} to read the entries.
|
|
|
|
@c There was a rumor that this flag has different meaning if using the DNS,
|
|
@c but it appears this description is accurate in that case also.
|
|
If the @var{stayopen} argument is nonzero, this sets a flag so that
|
|
subsequent calls to @code{gethostbyname} or @code{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.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {struct hostent *} gethostent ()
|
|
This function returns the next entry in the hosts database. It
|
|
returns a null pointer if there are no more entries.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun void endhostent ()
|
|
This function closes the hosts database.
|
|
@end deftypefun
|
|
|
|
@node Ports
|
|
@subsection Internet Ports
|
|
@cindex port number
|
|
|
|
A socket address in the Internet namespace consists of a machine's
|
|
Internet address plus a @dfn{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 @code{IPPORT_RESERVED} are reserved for standard
|
|
servers, such as @code{finger} and @code{telnet}. There is a database
|
|
that keeps track of these, and you can use the @code{getservbyname}
|
|
function to map a service name onto a port number; see @ref{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 @code{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
|
|
@code{IPPORT_RESERVED} and @code{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; @code{bind} normally insists on
|
|
distinct port numbers. To reuse a port number, you must set the
|
|
socket option @code{SO_REUSEADDR}. @xref{Socket-Level Options}.
|
|
|
|
@pindex netinet/in.h
|
|
These macros are defined in the header file @file{netinet/in.h}.
|
|
|
|
@comment netinet/in.h
|
|
@comment BSD
|
|
@deftypevr Macro int IPPORT_RESERVED
|
|
Port numbers less than @code{IPPORT_RESERVED} are reserved for
|
|
superuser use.
|
|
@end deftypevr
|
|
|
|
@comment netinet/in.h
|
|
@comment BSD
|
|
@deftypevr Macro int IPPORT_USERRESERVED
|
|
Port numbers greater than or equal to @code{IPPORT_USERRESERVED} are
|
|
reserved for explicit use; they will never be allocated automatically.
|
|
@end deftypevr
|
|
|
|
@node Services Database
|
|
@subsection The Services Database
|
|
@cindex services database
|
|
@cindex converting service name to port number
|
|
@cindex converting port number to service name
|
|
|
|
@pindex /etc/services
|
|
The database that keeps track of ``well-known'' services is usually
|
|
either the file @file{/etc/services} or an equivalent from a name server.
|
|
You can use these utilities, declared in @file{netdb.h}, to access
|
|
the services database.
|
|
@pindex netdb.h
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftp {Data Type} {struct servent}
|
|
This data type holds information about entries from the services database.
|
|
It has the following members:
|
|
|
|
@table @code
|
|
@item char *s_name
|
|
This is the ``official'' name of the service.
|
|
|
|
@item char **s_aliases
|
|
These are alternate names for the service, represented as an array of
|
|
strings. A null pointer terminates the array.
|
|
|
|
@item int s_port
|
|
This is the port number for the service. Port numbers are given in
|
|
network byte order; see @ref{Byte Order}.
|
|
|
|
@item char *s_proto
|
|
This is the name of the protocol to use with this service.
|
|
@xref{Protocols Database}.
|
|
@end table
|
|
@end deftp
|
|
|
|
To get information about a particular service, use the
|
|
@code{getservbyname} or @code{getservbyport} functions. The information
|
|
is returned in a statically-allocated structure; you must copy the
|
|
information if you need to save it across calls.
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto})
|
|
The @code{getservbyname} function returns information about the
|
|
service named @var{name} using protocol @var{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 (@pxref{Listening}).
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto})
|
|
The @code{getservbyport} function returns information about the
|
|
service at port @var{port} using protocol @var{proto}. If it can't
|
|
find such a service, it returns a null pointer.
|
|
@end deftypefun
|
|
|
|
You can also scan the services database using @code{setservent},
|
|
@code{getservent}, and @code{endservent}. Be careful in using these
|
|
functions, because they are not reentrant.
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun void setservent (int @var{stayopen})
|
|
This function opens the services database to begin scanning it.
|
|
|
|
If the @var{stayopen} argument is nonzero, this sets a flag so that
|
|
subsequent calls to @code{getservbyname} or @code{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.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {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.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun void endservent (void)
|
|
This function closes the services database.
|
|
@end deftypefun
|
|
|
|
@node Byte Order
|
|
@subsection Byte Order Conversion
|
|
@cindex byte order conversion, for socket
|
|
@cindex converting byte order
|
|
|
|
@cindex big-endian
|
|
@cindex little-endian
|
|
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).
|
|
|
|
@cindex network byte 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 @dfn{network byte order}.
|
|
|
|
When establishing an Internet socket connection, you must make sure that
|
|
the data in the @code{sin_port} and @code{sin_addr} members of the
|
|
@code{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 @code{getservbyname} and @code{gethostbyname} or
|
|
@code{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 @code{sockaddr_in} structure.
|
|
|
|
Otherwise, you have to convert the values explicitly. Use
|
|
@code{htons} and @code{ntohs} to convert values for the @code{sin_port}
|
|
member. Use @code{htonl} and @code{ntohl} to convert values for the
|
|
@code{sin_addr} member. (Remember, @code{struct in_addr} is equivalent
|
|
to @code{unsigned long int}.) These functions are declared in
|
|
@file{netinet/in.h}.
|
|
@pindex netinet/in.h
|
|
|
|
@comment netinet/in.h
|
|
@comment BSD
|
|
@deftypefun {unsigned short int} htons (unsigned short int @var{hostshort})
|
|
This function converts the @code{short} integer @var{hostshort} from
|
|
host byte order to network byte order.
|
|
@end deftypefun
|
|
|
|
@comment netinet/in.h
|
|
@comment BSD
|
|
@deftypefun {unsigned short int} ntohs (unsigned short int @var{netshort})
|
|
This function converts the @code{short} integer @var{netshort} from
|
|
network byte order to host byte order.
|
|
@end deftypefun
|
|
|
|
@comment netinet/in.h
|
|
@comment BSD
|
|
@deftypefun {unsigned long int} htonl (unsigned long int @var{hostlong})
|
|
This function converts the @code{long} integer @var{hostlong} from
|
|
host byte order to network byte order.
|
|
@end deftypefun
|
|
|
|
@comment netinet/in.h
|
|
@comment BSD
|
|
@deftypefun {unsigned long int} ntohl (unsigned long int @var{netlong})
|
|
This function converts the @code{long} integer @var{netlong} from
|
|
network byte order to host byte order.
|
|
@end deftypefun
|
|
|
|
@node Protocols Database
|
|
@subsection Protocols Database
|
|
@cindex 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.
|
|
|
|
@cindex TCP (Internet protocol)
|
|
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.
|
|
|
|
@pindex /etc/protocols
|
|
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
|
|
@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 @code{getprotobyname} function.
|
|
|
|
Here are detailed descriptions of the utilities for accessing the
|
|
protocols database. These are declared in @file{netdb.h}.
|
|
@pindex netdb.h
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftp {Data Type} {struct protoent}
|
|
This data type is used to represent entries in the network protocols
|
|
database. It has the following members:
|
|
|
|
@table @code
|
|
@item char *p_name
|
|
This is the official name of the protocol.
|
|
|
|
@item 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.
|
|
|
|
@item int p_proto
|
|
This is the protocol number (in host byte order); use this member as the
|
|
@var{protocol} argument to @code{socket}.
|
|
@end table
|
|
@end deftp
|
|
|
|
You can use @code{getprotobyname} and @code{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.
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {struct protoent *} getprotobyname (const char *@var{name})
|
|
The @code{getprotobyname} function returns information about the
|
|
network protocol named @var{name}. If there is no such protocol, it
|
|
returns a null pointer.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {struct protoent *} getprotobynumber (int @var{protocol})
|
|
The @code{getprotobynumber} function returns information about the
|
|
network protocol with number @var{protocol}. If there is no such
|
|
protocol, it returns a null pointer.
|
|
@end deftypefun
|
|
|
|
You can also scan the whole protocols database one protocol at a time by
|
|
using @code{setprotoent}, @code{getprotoent}, and @code{endprotoent}.
|
|
Be careful in using these functions, because they are not reentrant.
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun void setprotoent (int @var{stayopen})
|
|
This function opens the protocols database to begin scanning it.
|
|
|
|
If the @var{stayopen} argument is nonzero, this sets a flag so that
|
|
subsequent calls to @code{getprotobyname} or @code{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.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {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.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun void endprotoent (void)
|
|
This function closes the protocols database.
|
|
@end deftypefun
|
|
|
|
@node Inet Example
|
|
@subsection Internet Socket Example
|
|
|
|
Here is an example showing how to create and name a socket in the
|
|
Internet namespace. The newly created socket exists on the machine that
|
|
the program is running on. Rather than finding and using the machine's
|
|
Internet address, this example specifies @code{INADDR_ANY} as the host
|
|
address; the system replaces that with the machine's actual address.
|
|
|
|
@smallexample
|
|
@include mkisock.c.texi
|
|
@end smallexample
|
|
|
|
Here is another example, showing how you can fill in a @code{sockaddr_in}
|
|
structure, given a host name string and a port number:
|
|
|
|
@smallexample
|
|
@include isockad.c.texi
|
|
@end smallexample
|
|
|
|
@node Misc Namespaces
|
|
@section Other Namespaces
|
|
|
|
@vindex PF_NS
|
|
@vindex PF_ISO
|
|
@vindex PF_CCITT
|
|
@vindex PF_IMPLINK
|
|
@vindex PF_ROUTE
|
|
Certain other namespaces and associated protocol families are supported
|
|
but not documented yet because they are not often used. @code{PF_NS}
|
|
refers to the Xerox Network Software protocols. @code{PF_ISO} stands
|
|
for Open Systems Interconnect. @code{PF_CCITT} refers to protocols from
|
|
CCITT. @file{socket.h} defines these symbols and others naming protocols
|
|
not actually implemented.
|
|
|
|
@code{PF_IMPLINK} is used for communicating between hosts and Internet
|
|
Message Processors. For information on this, and on @code{PF_ROUTE}, an
|
|
occasionally-used local area routing protocol, see the GNU Hurd Manual
|
|
(to appear in the future).
|
|
|
|
@node Open/Close Sockets
|
|
@section Opening and Closing Sockets
|
|
|
|
This section describes the actual library functions for opening and
|
|
closing sockets. The same functions work for all namespaces and
|
|
connection styles.
|
|
|
|
@menu
|
|
* Creating a Socket:: How to open a socket.
|
|
* Closing a Socket:: How to close a socket.
|
|
* Socket Pairs:: These are created like pipes.
|
|
@end menu
|
|
|
|
@node Creating a Socket
|
|
@subsection Creating a Socket
|
|
@cindex creating a socket
|
|
@cindex socket, creating
|
|
@cindex opening a socket
|
|
|
|
The primitive for creating a socket is the @code{socket} function,
|
|
declared in @file{sys/socket.h}.
|
|
@pindex sys/socket.h
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol})
|
|
This function creates a socket and specifies communication style
|
|
@var{style}, which should be one of the socket styles listed in
|
|
@ref{Communication Styles}. The @var{namespace} argument specifies
|
|
the namespace; it must be @code{PF_FILE} (@pxref{File Namespace}) or
|
|
@code{PF_INET} (@pxref{Internet Namespace}). @var{protocol}
|
|
designates the specific protocol (@pxref{Socket Concepts}); zero is
|
|
usually right for @var{protocol}.
|
|
|
|
The return value from @code{socket} is the file descriptor for the new
|
|
socket, or @code{-1} in case of error. The following @code{errno} error
|
|
conditions are defined for this function:
|
|
|
|
@table @code
|
|
@item EPROTONOSUPPORT
|
|
The @var{protocol} or @var{style} is not supported by the
|
|
@var{namespace} specified.
|
|
|
|
@item EMFILE
|
|
The process already has too many file descriptors open.
|
|
|
|
@item ENFILE
|
|
The system already has too many file descriptors open.
|
|
|
|
@item EACCESS
|
|
The process does not have privilege to create a socket of the specified
|
|
@var{style} or @var{protocol}.
|
|
|
|
@item ENOBUFS
|
|
The system ran out of internal buffer space.
|
|
@end table
|
|
|
|
The file descriptor returned by the @code{socket} function supports both
|
|
read and write operations. But, like pipes, sockets do not support file
|
|
positioning operations.
|
|
@end deftypefun
|
|
|
|
For examples of how to call the @code{socket} function,
|
|
see @ref{File Namespace}, or @ref{Inet Example}.
|
|
|
|
|
|
@node Closing a Socket
|
|
@subsection Closing a Socket
|
|
@cindex socket, closing
|
|
@cindex closing a socket
|
|
@cindex shutting down a socket
|
|
@cindex socket shutdown
|
|
|
|
When you are finished using a socket, you can simply close its
|
|
file descriptor with @code{close}; see @ref{Opening and Closing Files}.
|
|
If there is still data waiting to be transmitted over the connection,
|
|
normally @code{close} tries to complete this transmission. You
|
|
can control this behavior using the @code{SO_LINGER} socket option to
|
|
specify a timeout period; see @ref{Socket Options}.
|
|
|
|
@pindex sys/socket.h
|
|
You can also shut down only reception or only transmission on a
|
|
connection by calling @code{shutdown}, which is declared in
|
|
@file{sys/socket.h}.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int shutdown (int @var{socket}, int @var{how})
|
|
The @code{shutdown} function shuts down the connection of socket
|
|
@var{socket}. The argument @var{how} specifies what action to
|
|
perform:
|
|
|
|
@table @code
|
|
@item 0
|
|
Stop receiving data for this socket. If further data arrives,
|
|
reject it.
|
|
|
|
@item 1
|
|
Stop trying to transmit data from this socket. Discard any data
|
|
waiting to be sent. Stop looking for acknowledgement of data already
|
|
sent; don't retransmit it if it is lost.
|
|
|
|
@item 2
|
|
Stop both reception and transmission.
|
|
@end table
|
|
|
|
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
|
|
@var{socket} is not a valid file descriptor.
|
|
|
|
@item ENOTSOCK
|
|
@var{socket} is not a socket.
|
|
|
|
@item ENOTCONN
|
|
@var{socket} is not connected.
|
|
@end table
|
|
@end deftypefun
|
|
|
|
@node Socket Pairs
|
|
@subsection Socket Pairs
|
|
@cindex creating a socket pair
|
|
@cindex socket pair
|
|
@cindex opening a socket pair
|
|
|
|
@pindex sys/socket.h
|
|
A @dfn{socket pair} consists of a pair of connected (but unnamed)
|
|
sockets. It is very similar to a pipe and is used in much the same
|
|
way. Socket pairs are created with the @code{socketpair} function,
|
|
declared in @file{sys/socket.h}. A socket pair is much like a pipe; the
|
|
main difference is that the socket pair is bidirectional, whereas the
|
|
pipe has one input-only end and one output-only end (@pxref{Pipes and
|
|
FIFOs}).
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]})
|
|
This function creates a socket pair, returning the file descriptors in
|
|
@code{@var{filedes}[0]} and @code{@var{filedes}[1]}. The socket pair
|
|
is a full-duplex communications channel, so that both reading and writing
|
|
may be performed at either end.
|
|
|
|
The @var{namespace}, @var{style}, and @var{protocol} arguments are
|
|
interpreted as for the @code{socket} function. @var{style} should be
|
|
one of the communication styles listed in @ref{Communication Styles}.
|
|
The @var{namespace} argument specifies the namespace, which must be
|
|
@code{AF_FILE} (@pxref{File Namespace}); @var{protocol} specifies the
|
|
communications protocol, but zero is the only meaningful value.
|
|
|
|
If @var{style} specifies a connectionless communication style, then
|
|
the two sockets you get are not @emph{connected}, strictly speaking,
|
|
but each of them knows the other as the default destination address,
|
|
so they can send packets to each other.
|
|
|
|
The @code{socketpair} function returns @code{0} on success and @code{-1}
|
|
on failure. The following @code{errno} error conditions are defined
|
|
for this function:
|
|
|
|
@table @code
|
|
@item EMFILE
|
|
The process has too many file descriptors open.
|
|
|
|
@item EAFNOSUPPORT
|
|
The specified namespace is not supported.
|
|
|
|
@item EPROTONOSUPPORT
|
|
The specified protocol is not supported.
|
|
|
|
@item EOPNOTSUPP
|
|
The specified protocol does not support the creation of socket pairs.
|
|
@end table
|
|
@end deftypefun
|
|
|
|
@node Connections
|
|
@section Using Sockets with Connections
|
|
|
|
@cindex connection
|
|
@cindex client
|
|
@cindex server
|
|
The most common communication styles involve making a connection to a
|
|
particular other socket, and then exchanging data with that socket
|
|
over and over. Making a connection is asymmetric; one side (the
|
|
@dfn{client}) acts to request a connection, while the other side (the
|
|
@dfn{server}) makes a socket and waits for the connection request.
|
|
|
|
@iftex
|
|
@itemize @bullet
|
|
@item
|
|
@ref{Connecting}, describes what the client program must do to
|
|
initiate a connection with a server.
|
|
|
|
@item
|
|
@ref{Listening}, and @ref{Accepting Connections}, describe what the
|
|
server program must do to wait for and act upon connection requests
|
|
from clients.
|
|
|
|
@item
|
|
@ref{Transferring Data}, describes how data is transferred through the
|
|
connected socket.
|
|
@end itemize
|
|
@end iftex
|
|
|
|
@menu
|
|
* Connecting:: What the client program must do.
|
|
* Listening:: How a server program waits for requests.
|
|
* Accepting Connections:: What the server does when it gets a request.
|
|
* Who is Connected:: Getting the address of the
|
|
other side of a connection.
|
|
* Transferring Data:: How to send and receive data.
|
|
* Byte Stream Example:: An example program: a client for communicating
|
|
over a byte stream socket in the Internet namespace.
|
|
* Server Example:: A corresponding server program.
|
|
* Out-of-Band Data:: This is an advanced feature.
|
|
@end menu
|
|
|
|
@node Connecting
|
|
@subsection Making a Connection
|
|
@cindex connecting a socket
|
|
@cindex socket, connecting
|
|
@cindex socket, initiating a connection
|
|
@cindex socket, client actions
|
|
|
|
In making a connection, the client makes a connection while the server
|
|
waits for and accepts the connection. Here we discuss what the client
|
|
program must do, using the @code{connect} function, which is declared in
|
|
@file{sys/socket.h}.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
|
|
The @code{connect} function initiates a connection from the socket
|
|
with file descriptor @var{socket} to the socket whose address is
|
|
specified by the @var{addr} and @var{length} arguments. (This socket
|
|
is typically on another machine, and it must be already set up as a
|
|
server.) @xref{Socket Addresses}, for information about how these
|
|
arguments are interpreted.
|
|
|
|
Normally, @code{connect} waits until the server responds to the request
|
|
before it returns. You can set nonblocking mode on the socket
|
|
@var{socket} to make @code{connect} return immediately without waiting
|
|
for the response. @xref{File Status Flags}, for information about
|
|
nonblocking mode.
|
|
@c !!! how do you tell when it has finished connecting? I suspect the
|
|
@c way you do it is select for writing.
|
|
|
|
The normal return value from @code{connect} is @code{0}. If an error
|
|
occurs, @code{connect} returns @code{-1}. The following @code{errno}
|
|
error conditions are defined for this function:
|
|
|
|
@table @code
|
|
@item EBADF
|
|
The socket @var{socket} is not a valid file descriptor.
|
|
|
|
@item ENOTSOCK
|
|
File descriptor @var{socket} is not a socket.
|
|
|
|
@item EADDRNOTAVAIL
|
|
The specified address is not available on the remote machine.
|
|
|
|
@item EAFNOSUPPORT
|
|
The namespace of the @var{addr} is not supported by this socket.
|
|
|
|
@item EISCONN
|
|
The socket @var{socket} is already connected.
|
|
|
|
@item ETIMEDOUT
|
|
The attempt to establish the connection timed out.
|
|
|
|
@item ECONNREFUSED
|
|
The server has actively refused to establish the connection.
|
|
|
|
@item ENETUNREACH
|
|
The network of the given @var{addr} isn't reachable from this host.
|
|
|
|
@item EADDRINUSE
|
|
The socket address of the given @var{addr} is already in use.
|
|
|
|
@item EINPROGRESS
|
|
The socket @var{socket} is non-blocking and the connection could not be
|
|
established immediately. You can determine when the connection is
|
|
completely established with @code{select}; @pxref{Waiting for I/O}.
|
|
Another @code{connect} call on the same socket, before the connection is
|
|
completely established, will fail with @code{EALREADY}.
|
|
|
|
@item EALREADY
|
|
The socket @var{socket} is non-blocking and already has a pending
|
|
connection in progress (see @code{EINPROGRESS} above).
|
|
@end table
|
|
|
|
This function is defined as a cancelation point in multi-threaded
|
|
programs. So one has to be prepared for this and make sure that
|
|
possibly allocated resources (like memory, files descriptors,
|
|
semaphores or whatever) are freed even if the thread is cancel.
|
|
@c @xref{pthread_cleanup_push}, for a method how to do this.
|
|
@end deftypefun
|
|
|
|
@node Listening
|
|
@subsection Listening for Connections
|
|
@cindex listening (sockets)
|
|
@cindex sockets, server actions
|
|
@cindex sockets, listening
|
|
|
|
Now let us consider what the server process must do to accept
|
|
connections on a socket. First it must use the @code{listen} function
|
|
to enable connection requests on the socket, and then accept each
|
|
incoming connection with a call to @code{accept} (@pxref{Accepting
|
|
Connections}). Once connection requests are enabled on a server socket,
|
|
the @code{select} function reports when the socket has a connection
|
|
ready to be accepted (@pxref{Waiting for I/O}).
|
|
|
|
The @code{listen} function is not allowed for sockets using
|
|
connectionless communication styles.
|
|
|
|
You can write a network server that does not even start running until a
|
|
connection to it is requested. @xref{Inetd Servers}.
|
|
|
|
In the Internet namespace, there are no special protection mechanisms
|
|
for controlling access to connect to a port; any process on any machine
|
|
can make a connection to your server. If you want to restrict access to
|
|
your server, make it examine the addresses associated with connection
|
|
requests or implement some other handshaking or identification
|
|
protocol.
|
|
|
|
In the File namespace, the ordinary file protection bits control who has
|
|
access to connect to the socket.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int listen (int @var{socket}, unsigned int @var{n})
|
|
The @code{listen} function enables the socket @var{socket} to accept
|
|
connections, thus making it a server socket.
|
|
|
|
The argument @var{n} specifies the length of the queue for pending
|
|
connections. When the queue fills, new clients attempting to connect
|
|
fail with @code{ECONNREFUSED} until the server calls @code{accept} to
|
|
accept a connection from the queue.
|
|
|
|
The @code{listen} function returns @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 argument @var{socket} is not a valid file descriptor.
|
|
|
|
@item ENOTSOCK
|
|
The argument @var{socket} is not a socket.
|
|
|
|
@item EOPNOTSUPP
|
|
The socket @var{socket} does not support this operation.
|
|
@end table
|
|
@end deftypefun
|
|
|
|
@node Accepting Connections
|
|
@subsection Accepting Connections
|
|
@cindex sockets, accepting connections
|
|
@cindex accepting connections
|
|
|
|
When a server receives a connection request, it can complete the
|
|
connection by accepting the request. Use the function @code{accept}
|
|
to do this.
|
|
|
|
A socket that has been established as a server can accept connection
|
|
requests from multiple clients. The server's original socket
|
|
@emph{does not become part} of the connection; instead, @code{accept}
|
|
makes a new socket which participates in the connection.
|
|
@code{accept} returns the descriptor for this socket. The server's
|
|
original socket remains available for listening for further connection
|
|
requests.
|
|
|
|
The number of pending connection requests on a server socket is finite.
|
|
If connection requests arrive from clients faster than the server can
|
|
act upon them, the queue can fill up and additional requests are refused
|
|
with a @code{ECONNREFUSED} error. You can specify the maximum length of
|
|
this queue as an argument to the @code{listen} function, although the
|
|
system may also impose its own internal limit on the length of this
|
|
queue.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
|
|
This function is used to accept a connection request on the server
|
|
socket @var{socket}.
|
|
|
|
The @code{accept} function waits if there are no connections pending,
|
|
unless the socket @var{socket} has nonblocking mode set. (You can use
|
|
@code{select} to wait for a pending connection, with a nonblocking
|
|
socket.) @xref{File Status Flags}, for information about nonblocking
|
|
mode.
|
|
|
|
The @var{addr} and @var{length-ptr} arguments are used to return
|
|
information about the name of the client socket that initiated the
|
|
connection. @xref{Socket Addresses}, for information about the format
|
|
of the information.
|
|
|
|
Accepting a connection does not make @var{socket} part of the
|
|
connection. Instead, it creates a new socket which becomes
|
|
connected. The normal return value of @code{accept} is the file
|
|
descriptor for the new socket.
|
|
|
|
After @code{accept}, the original socket @var{socket} remains open and
|
|
unconnected, and continues listening until you close it. You can
|
|
accept further connections with @var{socket} by calling @code{accept}
|
|
again.
|
|
|
|
If an error occurs, @code{accept} returns @code{-1}. 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} argument is not a socket.
|
|
|
|
@item EOPNOTSUPP
|
|
The descriptor @var{socket} does not support this operation.
|
|
|
|
@item EWOULDBLOCK
|
|
@var{socket} has nonblocking mode set, and there are no pending
|
|
connections immediately available.
|
|
@end table
|
|
|
|
This function is defined as a cancelation point in multi-threaded
|
|
programs. So one has to be prepared for this and make sure that
|
|
possibly allocated resources (like memory, files descriptors,
|
|
semaphores or whatever) are freed even if the thread is cancel.
|
|
@c @xref{pthread_cleanup_push}, for a method how to do this.
|
|
@end deftypefun
|
|
|
|
The @code{accept} function is not allowed for sockets using
|
|
connectionless communication styles.
|
|
|
|
@node Who is Connected
|
|
@subsection Who is Connected to Me?
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, size_t *@var{length-ptr})
|
|
The @code{getpeername} function returns the address of the socket that
|
|
@var{socket} is connected to; it stores the address in the memory space
|
|
specified by @var{addr} and @var{length-ptr}. It stores the length of
|
|
the address in @code{*@var{length-ptr}}.
|
|
|
|
@xref{Socket Addresses}, for information about the format of the
|
|
address. In some operating systems, @code{getpeername} works only for
|
|
sockets in the Internet domain.
|
|
|
|
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 argument @var{socket} is not a valid file descriptor.
|
|
|
|
@item ENOTSOCK
|
|
The descriptor @var{socket} is not a socket.
|
|
|
|
@item ENOTCONN
|
|
The socket @var{socket} is not connected.
|
|
|
|
@item ENOBUFS
|
|
There are not enough internal buffers available.
|
|
@end table
|
|
@end deftypefun
|
|
|
|
|
|
@node Transferring Data
|
|
@subsection Transferring Data
|
|
@cindex reading from a socket
|
|
@cindex writing to a socket
|
|
|
|
Once a socket has been connected to a peer, you can use the ordinary
|
|
@code{read} and @code{write} operations (@pxref{I/O Primitives}) to
|
|
transfer data. A socket is a two-way communications channel, so read
|
|
and write operations can be performed at either end.
|
|
|
|
There are also some I/O modes that are specific to socket operations.
|
|
In order to specify these modes, you must use the @code{recv} and
|
|
@code{send} functions instead of the more generic @code{read} and
|
|
@code{write} functions. The @code{recv} and @code{send} functions take
|
|
an additional argument which you can use to specify various flags to
|
|
control the special I/O modes. For example, you can specify the
|
|
@code{MSG_OOB} flag to read or write out-of-band data, the
|
|
@code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag
|
|
to control inclusion of routing information on output.
|
|
|
|
@menu
|
|
* Sending Data:: Sending data with @code{send}.
|
|
* Receiving Data:: Reading data with @code{recv}.
|
|
* Socket Data Options:: Using @code{send} and @code{recv}.
|
|
@end menu
|
|
|
|
@node Sending Data
|
|
@subsubsection Sending Data
|
|
|
|
@pindex sys/socket.h
|
|
The @code{send} function is declared in the header file
|
|
@file{sys/socket.h}. If your @var{flags} argument is zero, you can just
|
|
as well use @code{write} instead of @code{send}; see @ref{I/O
|
|
Primitives}. If the socket was connected but the connection has broken,
|
|
you get a @code{SIGPIPE} signal for any use of @code{send} or
|
|
@code{write} (@pxref{Miscellaneous Signals}).
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int send (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags})
|
|
The @code{send} function is like @code{write}, but with the additional
|
|
flags @var{flags}. The possible values of @var{flags} are described
|
|
in @ref{Socket Data Options}.
|
|
|
|
This function returns the number of bytes transmitted, or @code{-1} on
|
|
failure. If the socket is nonblocking, then @code{send} (like
|
|
@code{write}) can return after sending just part of the data.
|
|
@xref{File Status Flags}, for information about nonblocking mode.
|
|
|
|
Note, however, that a successful return value merely indicates that
|
|
the message has been sent without error, not necessarily that it has
|
|
been received without error.
|
|
|
|
The following @code{errno} error conditions are defined for this function:
|
|
|
|
@table @code
|
|
@item EBADF
|
|
The @var{socket} argument is not a valid file descriptor.
|
|
|
|
@item EINTR
|
|
The operation was interrupted by a signal before any data was sent.
|
|
@xref{Interrupted Primitives}.
|
|
|
|
@item ENOTSOCK
|
|
The descriptor @var{socket} is not a socket.
|
|
|
|
@item EMSGSIZE
|
|
The socket type requires that the message be sent atomically, but the
|
|
message is too large for this to be possible.
|
|
|
|
@item EWOULDBLOCK
|
|
Nonblocking mode has been set on the socket, and the write operation
|
|
would block. (Normally @code{send} blocks until the operation can be
|
|
completed.)
|
|
|
|
@item ENOBUFS
|
|
There is not enough internal buffer space available.
|
|
|
|
@item ENOTCONN
|
|
You never connected this socket.
|
|
|
|
@item EPIPE
|
|
This socket was connected but the connection is now broken. In this
|
|
case, @code{send} generates a @code{SIGPIPE} signal first; if that
|
|
signal is ignored or blocked, or if its handler returns, then
|
|
@code{send} fails with @code{EPIPE}.
|
|
@end table
|
|
|
|
This function is defined as a cancelation point in multi-threaded
|
|
programs. So one has to be prepared for this and make sure that
|
|
possibly allocated resources (like memory, files descriptors,
|
|
semaphores or whatever) are freed even if the thread is cancel.
|
|
@c @xref{pthread_cleanup_push}, for a method how to do this.
|
|
@end deftypefun
|
|
|
|
@node Receiving Data
|
|
@subsubsection Receiving Data
|
|
|
|
@pindex sys/socket.h
|
|
The @code{recv} function is declared in the header file
|
|
@file{sys/socket.h}. If your @var{flags} argument is zero, you can
|
|
just as well use @code{read} instead of @code{recv}; see @ref{I/O
|
|
Primitives}.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags})
|
|
The @code{recv} function is like @code{read}, but with the additional
|
|
flags @var{flags}. The possible values of @var{flags} are described
|
|
In @ref{Socket Data Options}.
|
|
|
|
If nonblocking mode is set for @var{socket}, and no data is available to
|
|
be read, @code{recv} fails immediately rather than waiting. @xref{File
|
|
Status Flags}, for information about nonblocking mode.
|
|
|
|
This function returns the number of bytes received, or @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 EWOULDBLOCK
|
|
Nonblocking mode has been set on the socket, and the read operation
|
|
would block. (Normally, @code{recv} blocks until there is input
|
|
available to be read.)
|
|
|
|
@item EINTR
|
|
The operation was interrupted by a signal before any data was read.
|
|
@xref{Interrupted Primitives}.
|
|
|
|
@item ENOTCONN
|
|
You never connected this socket.
|
|
@end table
|
|
|
|
This function is defined as a cancelation point in multi-threaded
|
|
programs. So one has to be prepared for this and make sure that
|
|
possibly allocated resources (like memory, files descriptors,
|
|
semaphores or whatever) are freed even if the thread is cancel.
|
|
@c @xref{pthread_cleanup_push}, for a method how to do this.
|
|
@end deftypefun
|
|
|
|
@node Socket Data Options
|
|
@subsubsection Socket Data Options
|
|
|
|
@pindex sys/socket.h
|
|
The @var{flags} argument to @code{send} and @code{recv} is a bit
|
|
mask. You can bitwise-OR the values of the following macros together
|
|
to obtain a value for this argument. All are defined in the header
|
|
file @file{sys/socket.h}.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypevr Macro int MSG_OOB
|
|
Send or receive out-of-band data. @xref{Out-of-Band Data}.
|
|
@end deftypevr
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypevr Macro int MSG_PEEK
|
|
Look at the data but don't remove it from the input queue. This is
|
|
only meaningful with input functions such as @code{recv}, not with
|
|
@code{send}.
|
|
@end deftypevr
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypevr Macro int MSG_DONTROUTE
|
|
Don't include routing information in the message. This is only
|
|
meaningful with output operations, and is usually only of interest for
|
|
diagnostic or routing programs. We don't try to explain it here.
|
|
@end deftypevr
|
|
|
|
@node Byte Stream Example
|
|
@subsection Byte Stream Socket Example
|
|
|
|
Here is an example client program that makes a connection for a byte
|
|
stream socket in the Internet namespace. It doesn't do anything
|
|
particularly interesting once it has connected to the server; it just
|
|
sends a text string to the server and exits.
|
|
|
|
@smallexample
|
|
@include inetcli.c.texi
|
|
@end smallexample
|
|
|
|
@node Server Example
|
|
@subsection Byte Stream Connection Server Example
|
|
|
|
The server end is much more complicated. Since we want to allow
|
|
multiple clients to be connected to the server at the same time, it
|
|
would be incorrect to wait for input from a single client by simply
|
|
calling @code{read} or @code{recv}. Instead, the right thing to do is
|
|
to use @code{select} (@pxref{Waiting for I/O}) to wait for input on
|
|
all of the open sockets. This also allows the server to deal with
|
|
additional connection requests.
|
|
|
|
This particular server doesn't do anything interesting once it has
|
|
gotten a message from a client. It does close the socket for that
|
|
client when it detects an end-of-file condition (resulting from the
|
|
client shutting down its end of the connection).
|
|
|
|
This program uses @code{make_socket} and @code{init_sockaddr} to set
|
|
up the socket address; see @ref{Inet Example}.
|
|
|
|
@smallexample
|
|
@include inetsrv.c.texi
|
|
@end smallexample
|
|
|
|
@node Out-of-Band Data
|
|
@subsection Out-of-Band Data
|
|
|
|
@cindex out-of-band data
|
|
@cindex high-priority data
|
|
Streams with connections permit @dfn{out-of-band} data that is
|
|
delivered with higher priority than ordinary data. Typically the
|
|
reason for sending out-of-band data is to send notice of an
|
|
exceptional condition. The way to send out-of-band data is using
|
|
@code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending
|
|
Data}).
|
|
|
|
Out-of-band data is received with higher priority because the
|
|
receiving process need not read it in sequence; to read the next
|
|
available out-of-band data, use @code{recv} with the @code{MSG_OOB}
|
|
flag (@pxref{Receiving Data}). Ordinary read operations do not read
|
|
out-of-band data; they read only the ordinary data.
|
|
|
|
@cindex urgent socket condition
|
|
When a socket finds that out-of-band data is on its way, it sends a
|
|
@code{SIGURG} signal to the owner process or process group of the
|
|
socket. You can specify the owner using the @code{F_SETOWN} command
|
|
to the @code{fcntl} function; see @ref{Interrupt Input}. You must
|
|
also establish a handler for this signal, as described in @ref{Signal
|
|
Handling}, in order to take appropriate action such as reading the
|
|
out-of-band data.
|
|
|
|
Alternatively, you can test for pending out-of-band data, or wait
|
|
until there is out-of-band data, using the @code{select} function; it
|
|
can wait for an exceptional condition on the socket. @xref{Waiting
|
|
for I/O}, for more information about @code{select}.
|
|
|
|
Notification of out-of-band data (whether with @code{SIGURG} or with
|
|
@code{select}) indicates that out-of-band data is on the way; the data
|
|
may not actually arrive until later. If you try to read the
|
|
out-of-band data before it arrives, @code{recv} fails with an
|
|
@code{EWOULDBLOCK} error.
|
|
|
|
Sending out-of-band data automatically places a ``mark'' in the stream
|
|
of ordinary data, showing where in the sequence the out-of-band data
|
|
``would have been''. This is useful when the meaning of out-of-band
|
|
data is ``cancel everything sent so far''. Here is how you can test,
|
|
in the receiving process, whether any ordinary data was sent before
|
|
the mark:
|
|
|
|
@smallexample
|
|
success = ioctl (socket, SIOCATMARK, &result);
|
|
@end smallexample
|
|
|
|
Here's a function to discard any ordinary data preceding the
|
|
out-of-band mark:
|
|
|
|
@smallexample
|
|
int
|
|
discard_until_mark (int socket)
|
|
@{
|
|
while (1)
|
|
@{
|
|
/* @r{This is not an arbitrary limit; any size will do.} */
|
|
char buffer[1024];
|
|
int result, success;
|
|
|
|
/* @r{If we have reached the mark, return.} */
|
|
success = ioctl (socket, SIOCATMARK, &result);
|
|
if (success < 0)
|
|
perror ("ioctl");
|
|
if (result)
|
|
return;
|
|
|
|
/* @r{Otherwise, read a bunch of ordinary data and discard it.}
|
|
@r{This is guaranteed not to read past the mark}
|
|
@r{if it starts before the mark.} */
|
|
success = read (socket, buffer, sizeof buffer);
|
|
if (success < 0)
|
|
perror ("read");
|
|
@}
|
|
@}
|
|
@end smallexample
|
|
|
|
If you don't want to discard the ordinary data preceding the mark, you
|
|
may need to read some of it anyway, to make room in internal system
|
|
buffers for the out-of-band data. If you try to read out-of-band data
|
|
and get an @code{EWOULDBLOCK} error, try reading some ordinary data
|
|
(saving it so that you can use it when you want it) and see if that
|
|
makes room. Here is an example:
|
|
|
|
@smallexample
|
|
struct buffer
|
|
@{
|
|
char *buffer;
|
|
int size;
|
|
struct buffer *next;
|
|
@};
|
|
|
|
/* @r{Read the out-of-band data from SOCKET and return it}
|
|
@r{as a `struct buffer', which records the address of the data}
|
|
@r{and its size.}
|
|
|
|
@r{It may be necessary to read some ordinary data}
|
|
@r{in order to make room for the out-of-band data.}
|
|
@r{If so, the ordinary data is saved as a chain of buffers}
|
|
@r{found in the `next' field of the value.} */
|
|
|
|
struct buffer *
|
|
read_oob (int socket)
|
|
@{
|
|
struct buffer *tail = 0;
|
|
struct buffer *list = 0;
|
|
|
|
while (1)
|
|
@{
|
|
/* @r{This is an arbitrary limit.}
|
|
@r{Does anyone know how to do this without a limit?} */
|
|
char *buffer = (char *) xmalloc (1024);
|
|
struct buffer *link;
|
|
int success;
|
|
int result;
|
|
|
|
/* @r{Try again to read the out-of-band data.} */
|
|
success = recv (socket, buffer, sizeof buffer, MSG_OOB);
|
|
if (success >= 0)
|
|
@{
|
|
/* @r{We got it, so return it.} */
|
|
struct buffer *link
|
|
= (struct buffer *) xmalloc (sizeof (struct buffer));
|
|
link->buffer = buffer;
|
|
link->size = success;
|
|
link->next = list;
|
|
return link;
|
|
@}
|
|
|
|
/* @r{If we fail, see if we are at the mark.} */
|
|
success = ioctl (socket, SIOCATMARK, &result);
|
|
if (success < 0)
|
|
perror ("ioctl");
|
|
if (result)
|
|
@{
|
|
/* @r{At the mark; skipping past more ordinary data cannot help.}
|
|
@r{So just wait a while.} */
|
|
sleep (1);
|
|
continue;
|
|
@}
|
|
|
|
/* @r{Otherwise, read a bunch of ordinary data and save it.}
|
|
@r{This is guaranteed not to read past the mark}
|
|
@r{if it starts before the mark.} */
|
|
success = read (socket, buffer, sizeof buffer);
|
|
if (success < 0)
|
|
perror ("read");
|
|
|
|
/* @r{Save this data in the buffer list.} */
|
|
@{
|
|
struct buffer *link
|
|
= (struct buffer *) xmalloc (sizeof (struct buffer));
|
|
link->buffer = buffer;
|
|
link->size = success;
|
|
|
|
/* @r{Add the new link to the end of the list.} */
|
|
if (tail)
|
|
tail->next = link;
|
|
else
|
|
list = link;
|
|
tail = link;
|
|
@}
|
|
@}
|
|
@}
|
|
@end smallexample
|
|
|
|
@node Datagrams
|
|
@section Datagram Socket Operations
|
|
|
|
@cindex datagram socket
|
|
This section describes how to use communication styles that don't use
|
|
connections (styles @code{SOCK_DGRAM} and @code{SOCK_RDM}). Using
|
|
these styles, you group data into packets and each packet is an
|
|
independent communication. You specify the destination for each
|
|
packet individually.
|
|
|
|
Datagram packets are like letters: you send each one independently,
|
|
with its own destination address, and they may arrive in the wrong
|
|
order or not at all.
|
|
|
|
The @code{listen} and @code{accept} functions are not allowed for
|
|
sockets using connectionless communication styles.
|
|
|
|
@menu
|
|
* Sending Datagrams:: Sending packets on a datagram socket.
|
|
* Receiving Datagrams:: Receiving packets on a datagram socket.
|
|
* Datagram Example:: An example program: packets sent over a
|
|
datagram socket in the file namespace.
|
|
* Example Receiver:: Another program, that receives those packets.
|
|
@end menu
|
|
|
|
@node Sending Datagrams
|
|
@subsection Sending Datagrams
|
|
@cindex sending a datagram
|
|
@cindex transmitting datagrams
|
|
@cindex datagrams, transmitting
|
|
|
|
@pindex sys/socket.h
|
|
The normal way of sending data on a datagram socket is by using the
|
|
@code{sendto} function, declared in @file{sys/socket.h}.
|
|
|
|
You can call @code{connect} on a datagram socket, but this only
|
|
specifies a default destination for further data transmission on the
|
|
socket. When a socket has a default destination, then you can use
|
|
@code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O
|
|
Primitives}) to send a packet there. You can cancel the default
|
|
destination by calling @code{connect} using an address format of
|
|
@code{AF_UNSPEC} in the @var{addr} argument. @xref{Connecting}, for
|
|
more information about the @code{connect} function.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int sendto (int @var{socket}, void *@var{buffer}. size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length})
|
|
The @code{sendto} function transmits the data in the @var{buffer}
|
|
through the socket @var{socket} to the destination address specified
|
|
by the @var{addr} and @var{length} arguments. The @var{size} argument
|
|
specifies the number of bytes to be transmitted.
|
|
|
|
The @var{flags} are interpreted the same way as for @code{send}; see
|
|
@ref{Socket Data Options}.
|
|
|
|
The return value and error conditions are also the same as for
|
|
@code{send}, but you cannot rely on the system to detect errors and
|
|
report them; the most common error is that the packet is lost or there
|
|
is no one at the specified address to receive it, and the operating
|
|
system on your machine usually does not know this.
|
|
|
|
It is also possible for one call to @code{sendto} to report an error
|
|
due to a problem related to a previous call.
|
|
|
|
This function is defined as a cancelation point in multi-threaded
|
|
programs. So one has to be prepared for this and make sure that
|
|
possibly allocated resources (like memory, files descriptors,
|
|
semaphores or whatever) are freed even if the thread is cancel.
|
|
@c @xref{pthread_cleanup_push}, for a method how to do this.
|
|
@end deftypefun
|
|
|
|
@node Receiving Datagrams
|
|
@subsection Receiving Datagrams
|
|
@cindex receiving datagrams
|
|
|
|
The @code{recvfrom} function reads a packet from a datagram socket and
|
|
also tells you where it was sent from. This function is declared in
|
|
@file{sys/socket.h}.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
|
|
The @code{recvfrom} function reads one packet from the socket
|
|
@var{socket} into the buffer @var{buffer}. The @var{size} argument
|
|
specifies the maximum number of bytes to be read.
|
|
|
|
If the packet is longer than @var{size} bytes, then you get the first
|
|
@var{size} bytes of the packet, and the rest of the packet is lost.
|
|
There's no way to read the rest of the packet. Thus, when you use a
|
|
packet protocol, you must always know how long a packet to expect.
|
|
|
|
The @var{addr} and @var{length-ptr} arguments are used to return the
|
|
address where the packet came from. @xref{Socket Addresses}. For a
|
|
socket in the file domain, the address information won't be meaningful,
|
|
since you can't read the address of such a socket (@pxref{File
|
|
Namespace}). You can specify a null pointer as the @var{addr} argument
|
|
if you are not interested in this information.
|
|
|
|
The @var{flags} are interpreted the same way as for @code{recv}
|
|
(@pxref{Socket Data Options}). The return value and error conditions
|
|
are also the same as for @code{recv}.
|
|
|
|
This function is defined as a cancelation point in multi-threaded
|
|
programs. So one has to be prepared for this and make sure that
|
|
possibly allocated resources (like memory, files descriptors,
|
|
semaphores or whatever) are freed even if the thread is cancel.
|
|
@c @xref{pthread_cleanup_push}, for a method how to do this.
|
|
@end deftypefun
|
|
|
|
You can use plain @code{recv} (@pxref{Receiving Data}) instead of
|
|
@code{recvfrom} if you know don't need to find out who sent the packet
|
|
(either because you know where it should come from or because you
|
|
treat all possible senders alike). Even @code{read} can be used if
|
|
you don't want to specify @var{flags} (@pxref{I/O Primitives}).
|
|
|
|
@ignore
|
|
@c sendmsg and recvmsg are like readv and writev in that they
|
|
@c use a series of buffers. It's not clear this is worth
|
|
@c supporting or that we support them.
|
|
@c !!! they can do more; it is hairy
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftp {Data Type} {struct msghdr}
|
|
@end deftp
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags})
|
|
|
|
This function is defined as a cancelation point in multi-threaded
|
|
programs. So one has to be prepared for this and make sure that
|
|
possibly allocated resources (like memory, files descriptors,
|
|
semaphores or whatever) are freed even if the thread is cancel.
|
|
@c @xref{pthread_cleanup_push}, for a method how to do this.
|
|
@end deftypefun
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
|
|
|
|
This function is defined as a cancelation point in multi-threaded
|
|
programs. So one has to be prepared for this and make sure that
|
|
possibly allocated resources (like memory, files descriptors,
|
|
semaphores or whatever) are freed even if the thread is cancel.
|
|
@c @xref{pthread_cleanup_push}, for a method how to do this.
|
|
@end deftypefun
|
|
@end ignore
|
|
|
|
@node Datagram Example
|
|
@subsection Datagram Socket Example
|
|
|
|
Here is a set of example programs that send messages over a datagram
|
|
stream in the file namespace. Both the client and server programs use the
|
|
@code{make_named_socket} function that was presented in @ref{File
|
|
Namespace}, to create and name their sockets.
|
|
|
|
First, here is the server program. It sits in a loop waiting for
|
|
messages to arrive, bouncing each message back to the sender.
|
|
Obviously, this isn't a particularly useful program, but it does show
|
|
the general ideas involved.
|
|
|
|
@smallexample
|
|
@include filesrv.c.texi
|
|
@end smallexample
|
|
|
|
@node Example Receiver
|
|
@subsection Example of Reading Datagrams
|
|
|
|
Here is the client program corresponding to the server above.
|
|
|
|
It sends a datagram to the server and then waits for a reply. Notice
|
|
that the socket for the client (as well as for the server) in this
|
|
example has to be given a name. This is so that the server can direct
|
|
a message back to the client. Since the socket has no associated
|
|
connection state, the only way the server can do this is by
|
|
referencing the name of the client.
|
|
|
|
@smallexample
|
|
@include filecli.c.texi
|
|
@end smallexample
|
|
|
|
Keep in mind that datagram socket communications are unreliable. In
|
|
this example, the client program waits indefinitely if the message
|
|
never reaches the server or if the server's response never comes
|
|
back. It's up to the user running the program to kill it and restart
|
|
it, if desired. A more automatic solution could be to use
|
|
@code{select} (@pxref{Waiting for I/O}) to establish a timeout period
|
|
for the reply, and in case of timeout either resend the message or
|
|
shut down the socket and exit.
|
|
|
|
@node Inetd
|
|
@section The @code{inetd} Daemon
|
|
|
|
We've explained above how to write a server program that does its own
|
|
listening. Such a server must already be running in order for anyone
|
|
to connect to it.
|
|
|
|
Another way to provide service for an Internet port is to let the daemon
|
|
program @code{inetd} do the listening. @code{inetd} is a program that
|
|
runs all the time and waits (using @code{select}) for messages on a
|
|
specified set of ports. When it receives a message, it accepts the
|
|
connection (if the socket style calls for connections) and then forks a
|
|
child process to run the corresponding server program. You specify the
|
|
ports and their programs in the file @file{/etc/inetd.conf}.
|
|
|
|
@menu
|
|
* Inetd Servers::
|
|
* Configuring Inetd::
|
|
@end menu
|
|
|
|
@node Inetd Servers
|
|
@subsection @code{inetd} Servers
|
|
|
|
Writing a server program to be run by @code{inetd} is very simple. Each time
|
|
someone requests a connection to the appropriate port, a new server
|
|
process starts. The connection already exists at this time; the
|
|
socket is available as the standard input descriptor and as the
|
|
standard output descriptor (descriptors 0 and 1) in the server
|
|
process. So the server program can begin reading and writing data
|
|
right away. Often the program needs only the ordinary I/O facilities;
|
|
in fact, a general-purpose filter program that knows nothing about
|
|
sockets can work as a byte stream server run by @code{inetd}.
|
|
|
|
You can also use @code{inetd} for servers that use connectionless
|
|
communication styles. For these servers, @code{inetd} does not try to accept
|
|
a connection, since no connection is possible. It just starts the
|
|
server program, which can read the incoming datagram packet from
|
|
descriptor 0. The server program can handle one request and then
|
|
exit, or you can choose to write it to keep reading more requests
|
|
until no more arrive, and then exit. You must specify which of these
|
|
two techniques the server uses, when you configure @code{inetd}.
|
|
|
|
@node Configuring Inetd
|
|
@subsection Configuring @code{inetd}
|
|
|
|
The file @file{/etc/inetd.conf} tells @code{inetd} which ports to listen to
|
|
and what server programs to run for them. Normally each entry in the
|
|
file is one line, but you can split it onto multiple lines provided
|
|
all but the first line of the entry start with whitespace. Lines that
|
|
start with @samp{#} are comments.
|
|
|
|
Here are two standard entries in @file{/etc/inetd.conf}:
|
|
|
|
@smallexample
|
|
ftp stream tcp nowait root /libexec/ftpd ftpd
|
|
talk dgram udp wait root /libexec/talkd talkd
|
|
@end smallexample
|
|
|
|
An entry has this format:
|
|
|
|
@smallexample
|
|
@var{service} @var{style} @var{protocol} @var{wait} @var{username} @var{program} @var{arguments}
|
|
@end smallexample
|
|
|
|
The @var{service} field says which service this program provides. It
|
|
should be the name of a service defined in @file{/etc/services}.
|
|
@code{inetd} uses @var{service} to decide which port to listen on for
|
|
this entry.
|
|
|
|
The fields @var{style} and @var{protocol} specify the communication
|
|
style and the protocol to use for the listening socket. The style
|
|
should be the name of a communication style, converted to lower case
|
|
and with @samp{SOCK_} deleted---for example, @samp{stream} or
|
|
@samp{dgram}. @var{protocol} should be one of the protocols listed in
|
|
@file{/etc/protocols}. The typical protocol names are @samp{tcp} for
|
|
byte stream connections and @samp{udp} for unreliable datagrams.
|
|
|
|
The @var{wait} field should be either @samp{wait} or @samp{nowait}.
|
|
Use @samp{wait} if @var{style} is a connectionless style and the
|
|
server, once started, handles multiple requests, as many as come in.
|
|
Use @samp{nowait} if @code{inetd} should start a new process for each message
|
|
or request that comes in. If @var{style} uses connections, then
|
|
@var{wait} @strong{must} be @samp{nowait}.
|
|
|
|
@var{user} is the user name that the server should run as. @code{inetd} runs
|
|
as root, so it can set the user ID of its children arbitrarily. It's
|
|
best to avoid using @samp{root} for @var{user} if you can; but some
|
|
servers, such as Telnet and FTP, read a username and password
|
|
themselves. These servers need to be root initially so they can log
|
|
in as commanded by the data coming over the network.
|
|
|
|
@var{program} together with @var{arguments} specifies the command to
|
|
run to start the server. @var{program} should be an absolute file
|
|
name specifying the executable file to run. @var{arguments} consists
|
|
of any number of whitespace-separated words, which become the
|
|
command-line arguments of @var{program}. The first word in
|
|
@var{arguments} is argument zero, which should by convention be the
|
|
program name itself (sans directories).
|
|
|
|
If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the
|
|
file and obey its new contents by sending the @code{inetd} process the
|
|
@code{SIGHUP} signal. You'll have to use @code{ps} to determine the
|
|
process ID of the @code{inetd} process, as it is not fixed.
|
|
|
|
@c !!! could document /etc/inetd.sec
|
|
|
|
@node Socket Options
|
|
@section Socket Options
|
|
@cindex socket options
|
|
|
|
This section describes how to read or set various options that modify
|
|
the behavior of sockets and their underlying communications protocols.
|
|
|
|
@cindex level, for socket options
|
|
@cindex socket option level
|
|
When you are manipulating a socket option, you must specify which
|
|
@dfn{level} the option pertains to. This describes whether the option
|
|
applies to the socket interface, or to a lower-level communications
|
|
protocol interface.
|
|
|
|
@menu
|
|
* Socket Option Functions:: The basic functions for setting and getting
|
|
socket options.
|
|
* Socket-Level Options:: Details of the options at the socket level.
|
|
@end menu
|
|
|
|
@node Socket Option Functions
|
|
@subsection Socket Option Functions
|
|
|
|
@pindex sys/socket.h
|
|
Here are the functions for examining and modifying socket options.
|
|
They are declared in @file{sys/socket.h}.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr})
|
|
The @code{getsockopt} function gets information about the value of
|
|
option @var{optname} at level @var{level} for socket @var{socket}.
|
|
|
|
The option value is stored in a buffer that @var{optval} points to.
|
|
Before the call, you should supply in @code{*@var{optlen-ptr}} the
|
|
size of this buffer; on return, it contains the number of bytes of
|
|
information actually stored in the buffer.
|
|
|
|
Most options interpret the @var{optval} buffer as a single @code{int}
|
|
value.
|
|
|
|
The actual return value of @code{getsockopt} is @code{0} on success
|
|
and @code{-1} on failure. The following @code{errno} error conditions
|
|
are defined:
|
|
|
|
@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 ENOPROTOOPT
|
|
The @var{optname} doesn't make sense for the given @var{level}.
|
|
@end table
|
|
@end deftypefun
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t @var{optlen})
|
|
This function is used to set the socket option @var{optname} at level
|
|
@var{level} for socket @var{socket}. The value of the option is passed
|
|
in the buffer @var{optval}, which has size @var{optlen}.
|
|
|
|
The return value and error codes for @code{setsockopt} are the same as
|
|
for @code{getsockopt}.
|
|
@end deftypefun
|
|
|
|
@node Socket-Level Options
|
|
@subsection Socket-Level Options
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftypevr Constant int SOL_SOCKET
|
|
Use this constant as the @var{level} argument to @code{getsockopt} or
|
|
@code{setsockopt} to manipulate the socket-level options described in
|
|
this section.
|
|
@end deftypevr
|
|
|
|
@pindex sys/socket.h
|
|
Here is a table of socket-level option names; all are defined in the
|
|
header file @file{sys/socket.h}.
|
|
|
|
@table @code
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item SO_DEBUG
|
|
@c Extra blank line here makes the table look better.
|
|
|
|
This option toggles recording of debugging information in the underlying
|
|
protocol modules. The value has type @code{int}; a nonzero value means
|
|
``yes''.
|
|
@c !!! should say how this is used
|
|
@c Ok, anyone who knows, please explain.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item SO_REUSEADDR
|
|
This option controls whether @code{bind} (@pxref{Setting Address})
|
|
should permit reuse of local addresses for this socket. If you enable
|
|
this option, you can actually have two sockets with the same Internet
|
|
port number; but the system won't allow you to use the two
|
|
identically-named sockets in a way that would confuse the Internet. The
|
|
reason for this option is that some higher-level Internet protocols,
|
|
including FTP, require you to keep reusing the same socket number.
|
|
|
|
The value has type @code{int}; a nonzero value means ``yes''.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item SO_KEEPALIVE
|
|
This option controls whether the underlying protocol should
|
|
periodically transmit messages on a connected socket. If the peer
|
|
fails to respond to these messages, the connection is considered
|
|
broken. The value has type @code{int}; a nonzero value means
|
|
``yes''.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item SO_DONTROUTE
|
|
This option controls whether outgoing messages bypass the normal
|
|
message routing facilities. If set, messages are sent directly to the
|
|
network interface instead. The value has type @code{int}; a nonzero
|
|
value means ``yes''.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item SO_LINGER
|
|
This option specifies what should happen when the socket of a type
|
|
that promises reliable delivery still has untransmitted messages when
|
|
it is closed; see @ref{Closing a Socket}. The value has type
|
|
@code{struct linger}.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@deftp {Data Type} {struct linger}
|
|
This structure type has the following members:
|
|
|
|
@table @code
|
|
@item int l_onoff
|
|
This field is interpreted as a boolean. If nonzero, @code{close}
|
|
blocks until the data is transmitted or the timeout period has expired.
|
|
|
|
@item int l_linger
|
|
This specifies the timeout period, in seconds.
|
|
@end table
|
|
@end deftp
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item SO_BROADCAST
|
|
This option controls whether datagrams may be broadcast from the socket.
|
|
The value has type @code{int}; a nonzero value means ``yes''.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item SO_OOBINLINE
|
|
If this option is set, out-of-band data received on the socket is
|
|
placed in the normal input queue. This permits it to be read using
|
|
@code{read} or @code{recv} without specifying the @code{MSG_OOB}
|
|
flag. @xref{Out-of-Band Data}. The value has type @code{int}; a
|
|
nonzero value means ``yes''.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item SO_SNDBUF
|
|
This option gets or sets the size of the output buffer. The value is a
|
|
@code{size_t}, which is the size in bytes.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item SO_RCVBUF
|
|
This option gets or sets the size of the input buffer. The value is a
|
|
@code{size_t}, which is the size in bytes.
|
|
|
|
@comment sys/socket.h
|
|
@comment GNU
|
|
@item SO_STYLE
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@itemx SO_TYPE
|
|
This option can be used with @code{getsockopt} only. It is used to
|
|
get the socket's communication style. @code{SO_TYPE} is the
|
|
historical name, and @code{SO_STYLE} is the preferred name in GNU.
|
|
The value has type @code{int} and its value designates a communication
|
|
style; see @ref{Communication Styles}.
|
|
|
|
@comment sys/socket.h
|
|
@comment BSD
|
|
@item SO_ERROR
|
|
@c Extra blank line here makes the table look better.
|
|
|
|
This option can be used with @code{getsockopt} only. It is used to reset
|
|
the error status of the socket. The value is an @code{int}, which represents
|
|
the previous error status.
|
|
@c !!! what is "socket error status"? this is never defined.
|
|
@end table
|
|
|
|
@node Networks Database
|
|
@section Networks Database
|
|
@cindex networks database
|
|
@cindex converting network number to network name
|
|
@cindex converting network name to network number
|
|
|
|
@pindex /etc/networks
|
|
@pindex netdb.h
|
|
Many systems come with a database that records a list of networks known
|
|
to the system developer. This is usually kept either in the file
|
|
@file{/etc/networks} or in an equivalent from a name server. This data
|
|
base is useful for routing programs such as @code{route}, but it is not
|
|
useful for programs that simply communicate over the network. We
|
|
provide functions to access this data base, which are declared in
|
|
@file{netdb.h}.
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftp {Data Type} {struct netent}
|
|
This data type is used to represent information about entries in the
|
|
networks database. It has the following members:
|
|
|
|
@table @code
|
|
@item char *n_name
|
|
This is the ``official'' name of the network.
|
|
|
|
@item char **n_aliases
|
|
These are alternative names for the network, represented as a vector
|
|
of strings. A null pointer terminates the array.
|
|
|
|
@item int n_addrtype
|
|
This is the type of the network number; this is always equal to
|
|
@code{AF_INET} for Internet networks.
|
|
|
|
@item unsigned long int n_net
|
|
This is the network number. Network numbers are returned in host
|
|
byte order; see @ref{Byte Order}.
|
|
@end table
|
|
@end deftp
|
|
|
|
Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search
|
|
the networks database for information about a specific network. The
|
|
information is returned in a statically-allocated structure; you must
|
|
copy the information if you need to save it.
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {struct netent *} getnetbyname (const char *@var{name})
|
|
The @code{getnetbyname} function returns information about the network
|
|
named @var{name}. It returns a null pointer if there is no such
|
|
network.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {struct netent *} getnetbyaddr (long @var{net}, int @var{type})
|
|
The @code{getnetbyaddr} function returns information about the network
|
|
of type @var{type} with number @var{net}. You should specify a value of
|
|
@code{AF_INET} for the @var{type} argument for Internet networks.
|
|
|
|
@code{getnetbyaddr} returns a null pointer if there is no such
|
|
network.
|
|
@end deftypefun
|
|
|
|
You can also scan the networks database using @code{setnetent},
|
|
@code{getnetent}, and @code{endnetent}. Be careful in using these
|
|
functions, because they are not reentrant.
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun void setnetent (int @var{stayopen})
|
|
This function opens and rewinds the networks database.
|
|
|
|
If the @var{stayopen} argument is nonzero, this sets a flag so that
|
|
subsequent calls to @code{getnetbyname} or @code{getnetbyaddr} 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.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun {struct netent *} getnetent (void)
|
|
This function returns the next entry in the networks database. It
|
|
returns a null pointer if there are no more entries.
|
|
@end deftypefun
|
|
|
|
@comment netdb.h
|
|
@comment BSD
|
|
@deftypefun void endnetent (void)
|
|
This function closes the networks database.
|
|
@end deftypefun
|