library_15.html

Linux程序员的工作手册

information if you need to save it across calls.
<P>
<A NAME="IDX997"></A>
<U>Function:</U> struct protoent * <B>getprotobyname</B> <I>(const char *<VAR>name</VAR>)</I><P>
The <CODE>getprotobyname</CODE> function returns information about the
network protocol named <VAR>name</VAR>.  If there is no such protocol, it
returns a null pointer.
<P>
<A NAME="IDX998"></A>
<U>Function:</U> struct protoent * <B>getprotobynumber</B> <I>(int <VAR>protocol</VAR>)</I><P>
The <CODE>getprotobynumber</CODE> function returns information about the
network protocol with number <VAR>protocol</VAR>.  If there is no such
protocol, it returns a null pointer.
<P>
You can also scan the whole protocols database one protocol at a time by
using <CODE>setprotoent</CODE>, <CODE>getprotoent</CODE>, and <CODE>endprotoent</CODE>.
Be careful in using these functions, because they are not reentrant.
<P>
<A NAME="IDX999"></A>
<U>Function:</U> void <B>setprotoent</B> <I>(int <VAR>stayopen</VAR>)</I><P>
This function opens the protocols database to begin scanning it.
<P>
If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that
subsequent calls to <CODE>getprotobyname</CODE> or <CODE>getprotobynumber</CODE> 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.
<P>
<A NAME="IDX1000"></A>
<U>Function:</U> struct protoent * <B>getprotoent</B> <I>(void)</I><P>
This function returns the next entry in the protocols database.  It
returns a null pointer if there are no more entries.
<P>
<A NAME="IDX1001"></A>
<U>Function:</U> void <B>endprotoent</B> <I>(void)</I><P>
This function closes the protocols database.
<P>
<H3><A NAME="SEC238" HREF="library_toc.html#SEC238" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC238">Internet Socket Example</A></H3>
<P>
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</CODE> as the host
address; the system replaces that with the machine's actual address.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;sys/socket.h&#62;
#include &#60;netinet/in.h&#62;

int 
make_socket (unsigned short int port)
{
  int sock;
  struct sockaddr_in name;

  /* Create the socket.  */
  sock = socket (PF_INET, SOCK_STREAM, 0);
  if (sock &#60; 0)
    {
      perror ("socket");
      exit (EXIT_FAILURE);
    }

  /* Give the socket a name.  */
  name.sin_family = AF_INET;
  name.sin_port = htons (port);
  name.sin_addr.s_addr = htonl (INADDR_ANY);
  if (bind (sock, (struct sockaddr *) &#38;name, sizeof (name)) &#60; 0)
    {
      perror ("bind");
      exit (EXIT_FAILURE);
    }

  return sock;
}
</PRE>
<P>
Here is another example, showing how you can fill in a <CODE>sockaddr_in</CODE>
structure, given a host name string and a port number:
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;sys/socket.h&#62;
#include &#60;netinet/in.h&#62;
#include &#60;netdb.h&#62;

void 
init_sockaddr (struct sockaddr_in *name,
	       const char *hostname, unsigned short int port)
{
  struct hostent *hostinfo;

  name-&#62;sin_family = AF_INET;
  name-&#62;sin_port = htons (port);
  hostinfo = gethostbyname (serverhost);
  if (hostinfo == NULL) 
    {
      fprintf (stderr, "Unknown host %s.\n", hostname);
      exit (EXIT_FAILURE);
    }
  name-&#62;sin_addr = *(struct in_addr *) hostinfo-&#62;h_addr;
}
</PRE>
<P>
<H2><A NAME="SEC239" HREF="library_toc.html#SEC239" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC239">Other Namespaces</A></H2>
<A NAME="IDX1002"></A>
<A NAME="IDX1003"></A>
<A NAME="IDX1004"></A>
<A NAME="IDX1005"></A>
<A NAME="IDX1006"></A>
<P>
Certain other namespaces and associated protocol families are supported
but not documented yet because they are not often used.  <CODE>PF_NS</CODE>
refers to the Xerox Network Software protocols.  <CODE>PF_ISO</CODE> stands
for Open Systems Interconnect.  <CODE>PF_CCITT</CODE> refers to protocols from
CCITT.  <TT>`socket.h'</TT> defines these symbols and others naming protocols
not actually implemented.
<P>
<CODE>PF_IMPLINK</CODE> is used for communicating between hosts and Internet
Message Processors.  For information on this, and on <CODE>PF_ROUTE</CODE>, an
occasionally-used local area routing protocol, see the GNU Hurd Manual
(to appear in the future).
<P>
<H2><A NAME="SEC240" HREF="library_toc.html#SEC240" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC240">Opening and Closing Sockets</A></H2>
<P>
This section describes the actual library functions for opening and
closing sockets.  The same functions work for all namespaces and
connection styles.
<P>
<A NAME="IDX1007"></A>
<A NAME="IDX1008"></A>
<A NAME="IDX1009"></A>
<H3><A NAME="SEC241" HREF="library_toc.html#SEC241" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC241">Creating a Socket</A></H3>
<P>
The primitive for creating a socket is the <CODE>socket</CODE> function,
declared in <TT>`sys/socket.h'</TT>.
<A NAME="IDX1010"></A>
<P>
<A NAME="IDX1011"></A>
<U>Function:</U> int <B>socket</B> <I>(int <VAR>namespace</VAR>, int <VAR>style</VAR>, int <VAR>protocol</VAR>)</I><P>
This function creates a socket and specifies communication style
<VAR>style</VAR>, which should be one of the socket styles listed in
section <A HREF="library_15.html#SEC218" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC218">Communication Styles</A>.  The <VAR>namespace</VAR> argument specifies
the namespace; it must be <CODE>PF_FILE</CODE> (see section <A HREF="library_15.html#SEC223" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC223">The File Namespace</A>) or
<CODE>PF_INET</CODE> (see section <A HREF="library_15.html#SEC227" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC227">The Internet Namespace</A>).  <VAR>protocol</VAR>
designates the specific protocol (see section <A HREF="library_15.html#SEC217" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC217">Socket Concepts</A>); zero is
usually right for <VAR>protocol</VAR>.
<P>
The return value from <CODE>socket</CODE> is the file descriptor for the new
socket, or <CODE>-1</CODE> in case of error.  The following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EPROTONOSUPPORT</CODE>
<DD>The <VAR>protocol</VAR> or <VAR>style</VAR> is not supported by the
<VAR>namespace</VAR> specified.
<P>
<DT><CODE>EMFILE</CODE>
<DD>The process already has too many file descriptors open.
<P>
<DT><CODE>ENFILE</CODE>
<DD>The system already has too many file descriptors open.
<P>
<DT><CODE>EACCESS</CODE>
<DD>The process does not have privilege to create a socket of the specified
<VAR>style</VAR> or <VAR>protocol</VAR>.
<P>
<DT><CODE>ENOBUFS</CODE>
<DD>The system ran out of internal buffer space.
</DL>
<P>
The file descriptor returned by the <CODE>socket</CODE> function supports both
read and write operations.  But, like pipes, sockets do not support file
positioning operations.
<P>
For examples of how to call the <CODE>socket</CODE> function, 
see section <A HREF="library_15.html#SEC223" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC223">The File Namespace</A>, or section <A HREF="library_15.html#SEC238" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC238">Internet Socket Example</A>.
<P>
<A NAME="IDX1012"></A>
<A NAME="IDX1013"></A>
<A NAME="IDX1014"></A>
<A NAME="IDX1015"></A>
<H3><A NAME="SEC242" HREF="library_toc.html#SEC242" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC242">Closing a Socket</A></H3>
<P>
When you are finished using a socket, you can simply close its
file descriptor with <CODE>close</CODE>; see section <A HREF="library_12.html#SEC172" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC172">Opening and Closing Files</A>.
If there is still data waiting to be transmitted over the connection,
normally <CODE>close</CODE> tries to complete this transmission.  You
can control this behavior using the <CODE>SO_LINGER</CODE> socket option to
specify a timeout period; see section <A HREF="library_15.html#SEC264" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC264">Socket Options</A>.
<A NAME="IDX1016"></A>
<P>
You can also shut down only reception or only transmission on a
connection by calling <CODE>shutdown</CODE>, which is declared in
<TT>`sys/socket.h'</TT>.
<P>
<A NAME="IDX1017"></A>
<U>Function:</U> int <B>shutdown</B> <I>(int <VAR>socket</VAR>, int <VAR>how</VAR>)</I><P>
The <CODE>shutdown</CODE> function shuts down the connection of socket
<VAR>socket</VAR>.  The argument <VAR>how</VAR> specifies what action to
perform:
<P>
<DL COMPACT>
<DT><CODE>0</CODE>
<DD>Stop receiving data for this socket.  If further data arrives,
reject it.
<P>
<DT><CODE>1</CODE>
<DD>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.
<P>
<DT><CODE>2</CODE>
<DD>Stop both reception and transmission.
</DL>
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD><VAR>socket</VAR> is not a valid file descriptor.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD><VAR>socket</VAR> is not a socket.
<P>
<DT><CODE>ENOTCONN</CODE>
<DD><VAR>socket</VAR> is not connected.
</DL>
<P>
<A NAME="IDX1018"></A>
<A NAME="IDX1019"></A>
<A NAME="IDX1020"></A>
<H3><A NAME="SEC243" HREF="library_toc.html#SEC243" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC243">Socket Pairs</A></H3>
<A NAME="IDX1021"></A>
<P>
A <DFN>socket pair</DFN> 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</CODE> function,
declared in <TT>`sys/socket.h'</TT>.  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 (see section <A HREF="library_14.html#SEC211" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_14.html#SEC211">Pipes and FIFOs</A>).
<P>
<A NAME="IDX1022"></A>
<U>Function:</U> int <B>socketpair</B> <I>(int <VAR>namespace</VAR>, int <VAR>style</VAR>, int <VAR>protocol</VAR>, int <VAR>filedes</VAR><TT>[2]</TT>)</I><P>
This function creates a socket pair, returning the file descriptors in
<CODE><VAR>filedes</VAR>[0]</CODE> and <CODE><VAR>filedes</VAR>[1]</CODE>.  The socket pair
is a full-duplex communications channel, so that both reading and writing
may be performed at either end.
<P>
The <VAR>namespace</VAR>, <VAR>style</VAR>, and <VAR>protocol</VAR> arguments are
interpreted as for the <CODE>socket</CODE> function.  <VAR>style</VAR> should be
one of the communication styles listed in section <A HREF="library_15.html#SEC218" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC218">Communication Styles</A>.
The <VAR>namespace</VAR> argument specifies the namespace, which must be
<CODE>AF_FILE</CODE> (see section <A HREF="library_15.html#SEC223" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC223">The File Namespace</A>); <VAR>protocol</VAR> specifies the
communications protocol, but zero is the only meaningful value.
<P>
If <VAR>style</VAR> specifies a connectionless communication style, then
the two sockets you get are not <EM>connected</EM>, strictly speaking,
but each of them knows the other as the default destination address,
so they can send packets to each other.
<P>
The <CODE>socketpair</CODE> function returns <CODE>0</CODE> on success a