socket.texi

一个C源代码分析器

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}, size_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
The socket @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.

@item EALREADY
The socket @var{socket} is non-blocking and already has a pending
connection in progress.
@end table
@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}, size_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