socket.texi

一个C源代码分析器

@comment sys/socket.h
@comment BSD
@deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, size_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}, size_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 Format}, @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 Format::     How socket addresses are specified in the
                                 Internet namespace.
* Host Addresses::	        All about host addresses of internet host.
* Protocols Database::		Referring to protocols by name.
* Ports::			Internet port numbers.
* Services Database::           Ports may have symbolic names.
* Byte Order::		        Different hosts may use different byte
                                 ordering conventions; you need to
                                 canonicalize host address and port number. 
* Inet Example::	        Putting it all together.
@end menu

@node Internet Address Format
@subsection Internet Socket Address Format

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

The data type for representing socket addresses in the Internet namespace
is defined in the header file @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.

@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 numeric host addresses as sequences of four
numbers, separated by periods, as in @samp{128.52.46.32}.

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

@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}