<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 3 March 1994 -->

<TITLE>The GNU C Library - Sockets</TITLE>
<P>Go to the <A HREF="library_14.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_14.html">previous</A>, <A HREF="library_16.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html">next</A> section.<P>
<H1><A NAME="SEC216" HREF="library_toc.html#SEC216" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC216">Sockets</A></H1>
<P>
This chapter describes the GNU facilities for interprocess
communication using sockets.
<A NAME="IDX889"></A>
<A NAME="IDX890"></A>
<P>
A <DFN>socket</DFN> is a generalized interprocess communication channel.
Like a pipe, a socket is represented as a file descriptor.  But,
unlike pipes, sockets support communication between unrelated
processes, and even between processes running on different machines
that communicate over a network.  Sockets are the primary means of
communicating with other machines; <CODE>telnet</CODE>, <CODE>rlogin</CODE>,
<CODE>ftp</CODE>, <CODE>talk</CODE>, and the other familiar network programs use
sockets.
<P>
Not all operating systems support sockets.  In the GNU library, the
header file <TT>`sys/socket.h'</TT> exists regardless of the operating
system, and the socket functions always exist, but if the system does
not really support sockets, these functions always fail.
<P>
<STRONG>Incomplete:</STRONG> We do not currently document the facilities for
broadcast messages or for configuring Internet interfaces.
<P>
<H2><A NAME="SEC217" HREF="library_toc.html#SEC217" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC217">Socket Concepts</A></H2>
<A NAME="IDX891"></A>
<A NAME="IDX892"></A>
<P>
When you create a socket, you must specify the style of communication
you want to use and the type of protocol that should implement it.
The <DFN>communication style</DFN> of a socket defines the user-level
semantics of sending and receiving data on the socket.  Choosing a
communication style specifies the answers to questions such as these:
<P>
<UL>
<A NAME="IDX893"></A>
<A NAME="IDX894"></A>
<A NAME="IDX895"></A>
<LI>
<STRONG>What are the units of data transmission?</STRONG>  Some communication
styles regard the data as a sequence of bytes, with no larger
structure; others group the bytes into records (which are known in
this context as <DFN>packets</DFN>).
<P>
<A NAME="IDX896"></A>
<A NAME="IDX897"></A>
<LI>
<STRONG>Can data be lost during normal operation?</STRONG>  Some communication
styles guarantee that all the data sent arrives in the order it was
sent (barring system or network crashes); others styles occasionally
lose data as a normal part of operation, and may sometimes deliver
packets more than once or in the wrong order.
<P>
Designing a program to use unreliable communication styles usually
involves taking precautions to detect lost or misordered packets and
to retransmit data as needed.
<P>
<LI>
<STRONG>Is communication entirely with one partner?</STRONG>  Some
communication styles are like a telephone call--you make a
<DFN>connection</DFN> with one remote socket, and then exchange data
freely.  Other styles are like mailing letters--you specify a
destination address for each message you send.
</UL>
<A NAME="IDX898"></A>
<A NAME="IDX899"></A>
<A NAME="IDX900"></A>
<A NAME="IDX901"></A>
<P>
You must also choose a <DFN>namespace</DFN> for naming the socket.  A socket
name ("address") is meaningful only in the context of a particular
namespace.  In fact, even the data type to use for a socket name may
depend on the namespace.  Namespaces are also called "domains", but we
avoid that word as it can be confused with other usage of the same
term.  Each namespace has a symbolic name that starts with <SAMP>`PF_'</SAMP>.
A corresponding symbolic name starting with <SAMP>`AF_'</SAMP> designates the
address format for that namespace.
<A NAME="IDX902"></A>
<A NAME="IDX903"></A>
<A NAME="IDX904"></A>
<A NAME="IDX905"></A>
<P>
Finally you must next choose the <DFN>protocol</DFN> to carry out the
communication.  The protocol determines what low-level mechanism is used
to transmit and receive data.  Each protocol is valid for a particular
namespace and communication style; a namespace is sometimes called a
<DFN>protocol family</DFN> because of this, which is why the namespace names
start with <SAMP>`PF_'</SAMP>.
<P>
The rules of a protocol apply to the data passing between two programs,
perhaps on different computers; most of these rules are handled by the
operating system, and you need not know about them.  What you do need to
know about protocols is this:
<P>
<UL>
<LI>
In order to have communication between two sockets, they must specify
the <EM>same</EM> protocol.
<P>
<LI>
Each protocol is meaningful with particular style/namespace
combinations and cannot be used with inappropriate combinations.  For
example, the TCP protocol fits only the byte stream style of
communication and the Internet namespace.
<P>
<LI>
For each combination of style and namespace, there is a <DFN>default
protocol</DFN> which you can request by specifying 0 as the protocol
number.  And that's what you should normally do--use the default.
</UL>
<P>
<H2><A NAME="SEC218" HREF="library_toc.html#SEC218" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC218">Communication Styles</A></H2>
<P>
The GNU library includes support for several different kinds of sockets,
each with different characteristics.  This section describes the
supported socket types.  The symbolic constants listed here are
defined in <TT>`sys/socket.h'</TT>.
<A NAME="IDX906"></A>
<P>
<A NAME="IDX907"></A>
<U>Macro:</U> int <B>SOCK_STREAM</B><P>
The <CODE>SOCK_STREAM</CODE> style is like a pipe (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>);
it operates over a connection with a particular remote socket, and
transmits data reliably as a stream of bytes.
<P>
Use of this style is covered in detail in section <A HREF="library_15.html#SEC244" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC244">Using Sockets with Connections</A>.
<P>
<A NAME="IDX908"></A>
<U>Macro:</U> int <B>SOCK_DGRAM</B><P>
The <CODE>SOCK_DGRAM</CODE> style is used for sending
individually-addressed packets, unreliably.  
It is the diametrical opposite of <CODE>SOCK_STREAM</CODE>.
<P>
Each time you write data to a socket of this kind, that data becomes
one packet.  Since <CODE>SOCK_DGRAM</CODE> sockets do not have connections,
you must specify the recipient address with each packet.
<P>
The only guarantee that the system makes about your requests to
transmit data is that it will try its best to deliver each packet you
send.  It may succeed with the sixth packet after failing with the
fourth and fifth packets; the seventh packet may arrive before the
sixth, and may arrive a second time after the sixth.
<P>
The typical use for <CODE>SOCK_DGRAM</CODE> is in situations where it is
acceptible to simply resend a packet if no response is seen in a
reasonable amount of time.
<P>
See section <A HREF="library_15.html#SEC256" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC256">Datagram Socket Operations</A>, for detailed information about how to use datagram
sockets.
<P>
<A NAME="IDX909"></A>
<U>Macro:</U> int <B>SOCK_RAW</B><P>
This style provides access to low-level network protocols and
interfaces.  Ordinary user programs usually have no need to use this
style.
<P>
<H2><A NAME="SEC219" HREF="library_toc.html#SEC219" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC219">Socket Addresses</A></H2>
<A NAME="IDX910"></A>
<A NAME="IDX911"></A>
<A NAME="IDX912"></A>
<A NAME="IDX913"></A>
<P>
The name of a socket is normally called an <DFN>address</DFN>.  The
functions and symbols for dealing with socket addresses were named
inconsistently, sometimes using the term "name" and sometimes using
"address".  You can regard these terms as synonymous where sockets
are concerned.
<P>
A socket newly created with the <CODE>socket</CODE> function has no
address.  Other processes can find it for communication only if you
give it an address.  We call this <DFN>binding</DFN> the address to the
socket, and the way to do it is with the <CODE>bind</CODE> function.
<P>
You need be concerned with the address of a socket if other processes
are to find it and start communicating with it.  You can specify an
address for other sockets, but this is usually pointless; the first time
you send data from a socket, or use it to initiate a connection, the
system assigns an address automatically if you have not specified one.
<P>
Occasionally a client needs to specify an address because the server
discriminates based on addresses; for example, the rsh and rlogin
protocols look at the client's socket address and don't bypass password
checking unless it is less than <CODE>IPPORT_RESERVED</CODE> (see section <A HREF="library_15.html#SEC234" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC234">Internet Ports</A>).
<P>
The details of socket addresses vary depending on what namespace you are
using.  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#SEC227" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC227">The Internet Namespace</A>, for specific
information.
<P>
Regardless of the namespace, you use the same functions <CODE>bind</CODE> and
<CODE>getsockname</CODE> to set and examine a socket's address.  These
functions use a phony data type, <CODE>struct sockaddr *</CODE>, to accept the
address.  In practice, the address lives in a structure of some other
data type appropriate to the address format you are using, but you cast
its address to <CODE>struct sockaddr *</CODE> when you pass it to
<CODE>bind</CODE>.
<P>
<H3><A NAME="SEC220" HREF="library_toc.html#SEC220" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC220">Address Formats</A></H3>
<P>
The functions <CODE>bind</CODE> and <CODE>getsockname</CODE> use the generic data
type <CODE>struct sockaddr *</CODE> to represent a pointer to a socket
address.  You can't use this data type effectively to interpret an
address or construct one; for that, you must use the proper data type
for the socket's namespace.
<P>
Thus, the usual practice is to construct an address in the proper
namespace-specific type, then cast a pointer to <CODE>struct sockaddr *</CODE>
when you call <CODE>bind</CODE> or <CODE>getsockname</CODE>.
<P>
The one piece of information that you can get from the <CODE>struct
sockaddr</CODE> data type is the <DFN>address format</DFN> designator which tells
you which data type to use to understand the address fully.
<A NAME="IDX914"></A>
<P>
The symbols in this section are defined in the header file
<TT>`sys/socket.h'</TT>.
<P>
<A NAME="IDX915"></A>
<U>Date Type:</U> <B>struct sockaddr</B><P>
The <CODE>struct sockaddr</CODE> type itself has the following members:
<P>
<DL COMPACT>
<DT><CODE>short int sa_family</CODE>
<DD>This is the code for the address format of this address.  It
identifies the format of the data which follows.
<P>
<DT><CODE>char sa_data[14]</CODE>
<DD>This is the actual socket address data, which is format-dependent.  Its
length is also format-dependent, and may well be more than 14.  The
length 14 of <CODE>sa_data</CODE> is essentially arbitrary.
</DL>
<P>
Each address format has a symbolic name which starts with <SAMP>`AF_'</SAMP>.
Each of them corresponds to a <SAMP>`PF_'</SAMP> symbol which designates the
corresponding namespace.  Here is a list of address format names:
<P>
<DL COMPACT>
<A NAME="IDX916"></A>
<DT><CODE>AF_FILE</CODE>
<DD>This designates the address format that goes with the file namespace.
(<CODE>PF_FILE</CODE> is the name of that namespace.)  See section <A HREF="library_15.html#SEC225" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC225">Details of File Namespace</A>, for information about this address format.
<P>
<A NAME="IDX917"></A>
<DT><CODE>AF_UNIX</CODE>
<DD>This is a synonym for <CODE>AF_FILE</CODE>, for compatibility.
(<CODE>PF_UNIX</CODE> is likewise a synonym for <CODE>PF_FILE</CODE>.)
<P>
<A NAME="IDX918"></A>
<DT><CODE>AF_INET</CODE>
<DD>This designates the address format that goes with the Internet
namespace.  (<CODE>PF_INET</CODE> is the name of that namespace.)
See section <A HREF="library_15.html#SEC228" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC228">Internet Socket Address Format</A>.
<P>
<A NAME="IDX919"></A>
<DT><CODE>AF_UNSPEC</CODE>
<DD>This designates no particular address format.  It is used only in rare
cases, such as to clear out the default destination address of a
"connected" datagram socket.  See section <A HREF="library_15.html#SEC257" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC257">Sending Datagrams</A>.
<P>
The corresponding namespace designator symbol <CODE>PF_UNSPEC</CODE> exists
for completeness, but there is no reason to use it in a program.
</DL>