socket.texi

一个C源代码分析器

@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