socket.texi

一个C源代码分析器

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 long int} INADDR_LOOPBACK
You can use this constant to stand for ``the address of this machine,''
instead of finding its actual address.  It is the Internet address
@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 long 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 long 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 long int} INADDR_NONE
This constant is returned by some functions to indicate an error.
@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.
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.
@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

@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
@code{AF_INET}.  In principle other kinds of addresses could be
represented in the data base as well as Internet addresses; if this were
done, you might find a value in this field other than @code{AF_INET}.
@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} 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.

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