1: @node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top
    2: @c %MENU% A more complicated IPC mechanism, with networking support
    3: @chapter Sockets
    4: 
    5: This chapter describes the GNU facilities for interprocess
    6: communication using sockets.
    7: 
    8: @cindex socket
    9: @cindex interprocess communication, with sockets
   10: A @dfn{socket} is a generalized interprocess communication channel.
   11: Like a pipe, a socket is represented as a file descriptor.  Unlike pipes
   12: sockets support communication between unrelated processes, and even
   13: between processes running on different machines that communicate over a
   14: network.  Sockets are the primary means of communicating with other
   15: machines; @code{telnet}, @code{rlogin}, @code{ftp}, @code{talk} and the
   16: other familiar network programs use sockets.
   17: 
   18: Not all operating systems support sockets.  In the GNU library, the
   19: header file @file{sys/socket.h} exists regardless of the operating
   20: system, and the socket functions always exist, but if the system does
   21: not really support sockets these functions always fail.
   22: 
   23: @strong{Incomplete:} We do not currently document the facilities for
   24: broadcast messages or for configuring Internet interfaces.  The
   25: reentrant functions and some newer functions that are related to IPv6
   26: aren't documented either so far.
   27: 
   28: @menu
   29: * Socket Concepts::     Basic concepts you need to know about.
   30: * Communication Styles::Stream communication, datagrams and other styles.
   31: * Socket Addresses::    How socket names (``addresses'') work.
   32: * Interface Naming::    Identifying specific network interfaces.
   33: * Local Namespace::     Details about the local namespace.
   34: * Internet Namespace::  Details about the Internet namespace.
   35: * Misc Namespaces::     Other namespaces not documented fully here.
   36: * Open/Close Sockets::  Creating sockets and destroying them.
   37: * Connections::         Operations on sockets with connection state.
   38: * Datagrams::           Operations on datagram sockets.
   39: * Inetd::               Inetd is a daemon that starts servers on request.
   40:                            The most convenient way to write a server
   41:                            is to make it work with Inetd.
   42: * Socket Options::      Miscellaneous low-level socket options.
   43: * Networks Database::   Accessing the database of network names.
   44: @end menu
   45: 
   46: @node Socket Concepts
   47: @section Socket Concepts
   48: 
   49: @cindex communication style (of a socket)
   50: @cindex style of communication (of a socket)
   51: When you create a socket, you must specify the style of communication
   52: you want to use and the type of protocol that should implement it.
   53: The @dfn{communication style} of a socket defines the user-level
   54: semantics of sending and receiving data on the socket.  Choosing a
   55: communication style specifies the answers to questions such as these:
   56: 
   57: @itemize @bullet
   58: @item
   59: @cindex packet
   60: @cindex byte stream
   61: @cindex stream (sockets)
   62: @strong{What are the units of data transmission?}  Some communication
   63: styles regard the data as a sequence of bytes with no larger
   64: structure; others group the bytes into records (which are known in
   65: this context as @dfn{packets}).
   66: 
   67: @item
   68: @cindex loss of data on sockets
   69: @cindex data loss on sockets
   70: @strong{Can data be lost during normal operation?}  Some communication
   71: styles guarantee that all the data sent arrives in the order it was
   72: sent (barring system or network crashes); other styles occasionally
   73: lose data as a normal part of operation, and may sometimes deliver
   74: packets more than once or in the wrong order.
   75: 
   76: Designing a program to use unreliable communication styles usually
   77: involves taking precautions to detect lost or misordered packets and
   78: to retransmit data as needed.
   79: 
   80: @item
   81: @strong{Is communication entirely with one partner?}  Some
   82: communication styles are like a telephone call---you make a
   83: @dfn{connection} with one remote socket and then exchange data
   84: freely.  Other styles are like mailing letters---you specify a
   85: destination address for each message you send.
   86: @end itemize
   87: 
   88: @cindex namespace (of socket)
   89: @cindex domain (of socket)
   90: @cindex socket namespace
   91: @cindex socket domain
   92: You must also choose a @dfn{namespace} for naming the socket.  A socket
   93: name (``address'') is meaningful only in the context of a particular
   94: namespace.  In fact, even the data type to use for a socket name may
   95: depend on the namespace.  Namespaces are also called ``domains'', but we
   96: avoid that word as it can be confused with other usage of the same
   97: term.  Each namespace has a symbolic name that starts with @samp{PF_}.
   98: A corresponding symbolic name starting with @samp{AF_} designates the
   99: address format for that namespace.
  100: 
  101: @cindex network protocol
  102: @cindex protocol (of socket)
  103: @cindex socket protocol
  104: @cindex protocol family
  105: Finally you must choose the @dfn{protocol} to carry out the
  106: communication.  The protocol determines what low-level mechanism is used
  107: to transmit and receive data.  Each protocol is valid for a particular
  108: namespace and communication style; a namespace is sometimes called a
  109: @dfn{protocol family} because of this, which is why the namespace names
  110: start with @samp{PF_}.
  111: 
  112: The rules of a protocol apply to the data passing between two programs,
  113: perhaps on different computers; most of these rules are handled by the
  114: operating system and you need not know about them.  What you do need to
  115: know about protocols is this:
  116: 
  117: @itemize @bullet
  118: @item
  119: In order to have communication between two sockets, they must specify
  120: the @emph{same} protocol.
  121: 
  122: @item
  123: Each protocol is meaningful with particular style/namespace
  124: combinations and cannot be used with inappropriate combinations.  For
  125: example, the TCP protocol fits only the byte stream style of
  126: communication and the Internet namespace.
  127: 
  128: @item
  129: For each combination of style and namespace there is a @dfn{default
  130: protocol}, which you can request by specifying 0 as the protocol
  131: number.  And that's what you should normally do---use the default.
  132: @end itemize
  133: 
  134: Throughout the following description at various places
  135: variables/parameters to denote sizes are required.  And here the trouble
  136: starts.  In the first implementations the type of these variables was
  137: simply @code{int}.  On most machines at that time an @code{int} was 32
  138: bits wide, which created a @emph{de facto} standard requiring 32-bit
  139: variables.  This is important since references to variables of this type
  140: are passed to the kernel.
  141: 
  142: Then the POSIX people came and unified the interface with the words "all
  143: size values are of type @code{size_t}".  On 64-bit machines
  144: @code{size_t} is 64 bits wide, so pointers to variables were no longer
  145: possible.
  146: 
  147: The Unix98 specification provides a solution by introducing a type
  148: @code{socklen_t}.  This type is used in all of the cases that POSIX
  149: changed to use @code{size_t}.  The only requirement of this type is that
  150: it be an unsigned type of at least 32 bits.  Therefore, implementations
  151: which require that references to 32-bit variables be passed can be as
  152: happy as implementations which use 64-bit values.
  153: 
  154: 
  155: @node Communication Styles
  156: @section Communication Styles
  157: 
  158: The GNU library includes support for several different kinds of sockets,
  159: each with different characteristics.  This section describes the
  160: supported socket types.  The symbolic constants listed here are
  161: defined in @file{sys/socket.h}.
  162: @pindex sys/socket.h
  163: 
  164: @comment sys/socket.h
  165: @comment BSD
  166: @deftypevr Macro int SOCK_STREAM
  167: The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}).
  168: It operates over a connection with a particular remote socket and
  169: transmits data reliably as a stream of bytes.
  170: 
  171: Use of this style is covered in detail in @ref{Connections}.
  172: @end deftypevr
  173: 
  174: @comment sys/socket.h
  175: @comment BSD
  176: @deftypevr Macro int SOCK_DGRAM
  177: The @code{SOCK_DGRAM} style is used for sending
  178: individually-addressed packets unreliably.
  179: It is the diametrical opposite of @code{SOCK_STREAM}.
  180: 
  181: Each time you write data to a socket of this kind, that data becomes
  182: one packet.  Since @code{SOCK_DGRAM} sockets do not have connections,
  183: you must specify the recipient address with each packet.
  184: 
  185: The only guarantee that the system makes about your requests to
  186: transmit data is that it will try its best to deliver each packet you
  187: send.  It may succeed with the sixth packet after failing with the
  188: fourth and fifth packets; the seventh packet may arrive before the
  189: sixth, and may arrive a second time after the sixth.
  190: 
  191: The typical use for @code{SOCK_DGRAM} is in situations where it is
  192: acceptable to simply re-send a packet if no response is seen in a
  193: reasonable amount of time.
  194: 
  195: @xref{Datagrams}, for detailed information about how to use datagram
  196: sockets.
  197: @end deftypevr
  198: 
  199: @ignore
  200: @c This appears to be only for the NS domain, which we aren't
  201: @c discussing and probably won't support either.
  202: @comment sys/socket.h
  203: @comment BSD
  204: @deftypevr Macro int SOCK_SEQPACKET
  205: This style is like @code{SOCK_STREAM} except that the data are
  206: structured into packets.
  207: 
  208: A program that receives data over a @code{SOCK_SEQPACKET} socket
  209: should be prepared to read the entire message packet in a single call
  210: to @code{read}; if it only reads part of the message, the remainder of
  211: the message is simply discarded instead of being available for
  212: subsequent calls to @code{read}.
  213: 
  214: Many protocols do not support this communication style.
  215: @end deftypevr
  216: @end ignore
  217: 
  218: @ignore
  219: @comment sys/socket.h
  220: @comment BSD
  221: @deftypevr Macro int SOCK_RDM
  222: This style is a reliable version of @code{SOCK_DGRAM}: it sends
  223: individually addressed packets, but guarantees that each packet sent
  224: arrives exactly once.
  225: 
  226: @strong{Warning:} It is not clear this is actually supported
  227: by any operating system.
  228: @end deftypevr
  229: @end ignore
  230: 
  231: @comment sys/socket.h
  232: @comment BSD
  233: @deftypevr Macro int SOCK_RAW
  234: This style provides access to low-level network protocols and
  235: interfaces.  Ordinary user programs usually have no need to use this
  236: style.
  237: @end deftypevr
  238: 
  239: @node Socket Addresses
  240: @section Socket Addresses
  241: 
  242: @cindex address of socket
  243: @cindex name of socket
  244: @cindex binding a socket address
  245: @cindex socket address (name) binding
  246: The name of a socket is normally called an @dfn{address}.  The
  247: functions and symbols for dealing with socket addresses were named
  248: inconsistently, sometimes using the term ``name'' and sometimes using
  249: ``address''.  You can regard these terms as synonymous where sockets
  250: are concerned.
  251: 
  252: A socket newly created with the @code{socket} function has no
  253: address.  Other processes can find it for communication only if you
  254: give it an address.  We call this @dfn{binding} the address to the
  255: socket, and the way to do it is with the @code{bind} function.
  256: 
  257: You need be concerned with the address of a socket if other processes
  258: are to find it and start communicating with it.  You can specify an
  259: address for other sockets, but this is usually pointless; the first time
  260: you send data from a socket, or use it to initiate a connection, the
  261: system assigns an address automatically if you have not specified one.
  262: 
  263: Occasionally a client needs to specify an address because the server
  264: discriminates based on address; for example, the rsh and rlogin
  265: protocols look at the client's socket address and only bypass password
  266: checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
  267: 
  268: The details of socket addresses vary depending on what namespace you are
  269: using.  @xref{Local Namespace}, or @ref{Internet Namespace}, for specific
  270: information.
  271: 
  272: Regardless of the namespace, you use the same functions @code{bind} and
  273: @code{getsockname} to set and examine a socket's address.  These
  274: functions use a phony data type, @code{struct sockaddr *}, to accept the
  275: address.  In practice, the address lives in a structure of some other
  276: data type appropriate to the address format you are using, but you cast
  277: its address to @code{struct sockaddr *} when you pass it to
  278: @code{bind}.
  279: 
  280: @menu
  281: * Address Formats::             About @code{struct sockaddr}.
  282: * Setting Address::             Binding an address to a socket.
  283: * Reading Address::             Reading the address of a socket.
  284: @end menu
  285: 
  286: @node Address Formats
  287: @subsection Address Formats
  288: 
  289: The functions @code{bind} and @code{getsockname} use the generic data
  290: type @code{struct sockaddr *} to represent a pointer to a socket
  291: address.  You can't use this data type effectively to interpret an
  292: address or construct one; for that, you must use the proper data type
  293: for the socket's namespace.
  294: 
  295: Thus, the usual practice is to construct an address of the proper
  296: namespace-specific type, then cast a pointer to @code{struct sockaddr *}
  297: when you call @code{bind} or @code{getsockname}.
  298: 
  299: The one piece of information that you can get from the @code{struct
  300: sockaddr} data type is the @dfn{address format designator}.  This tells
  301: you which data type to use to understand the address fully.
  302: 
  303: @pindex sys/socket.h
  304: The symbols in this section are defined in the header file
  305: @file{sys/socket.h}.
  306: 
  307: @comment sys/socket.h
  308: @comment BSD
  309: @deftp {Data Type} {struct sockaddr}
  310: The @code{struct sockaddr} type itself has the following members:
  311: 
  312: @table @code
  313: @item short int sa_family
  314: This is the code for the address format of this address.  It
  315: identifies the format of the data which follows.
  316: 
  317: @item char sa_data[14]
  318: This is the actual socket address data, which is format-dependent.  Its
  319: length also depends on the format, and may well be more than 14.  The
  320: length 14 of @code{sa_data} is essentially arbitrary.
  321: @end table
  322: @end deftp
  323: 
  324: Each address format has a symbolic name which starts with @samp{AF_}.
  325: Each of them corresponds to a @samp{PF_} symbol which designates the
  326: corresponding namespace.  Here is a list of address format names:
  327: 
  328: @table @code
  329: @comment sys/socket.h
  330: @comment POSIX
  331: @item AF_LOCAL
  332: @vindex AF_LOCAL
  333: This designates the address format that goes with the local namespace.
  334: (@code{PF_LOCAL} is the name of that namespace.)  @xref{Local Namespace
  335: Details}, for information about this address format.
  336: 
  337: @comment sys/socket.h
  338: @comment BSD, Unix98
  339: @item AF_UNIX
  340: @vindex AF_UNIX
  341: This is a synonym for @code{AF_LOCAL}.  Although @code{AF_LOCAL} is
  342: mandated by POSIX.1g, @code{AF_UNIX} is portable to more systems.
  343: @code{AF_UNIX} was the traditional name stemming from BSD, so even most
  344: POSIX systems support it.  It is also the name of choice in the Unix98
  345: specification. (The same is true for @code{PF_UNIX}
  346: vs. @code{PF_LOCAL}).
  347: 
  348: @comment sys/socket.h
  349: @comment GNU
  350: @item AF_FILE
  351: @vindex AF_FILE
  352: This is another synonym for @code{AF_LOCAL}, for compatibility.
  353: (@code{PF_FILE} is likewise a synonym for @code{PF_LOCAL}.)
  354: 
  355: @comment sys/socket.h
  356: @comment BSD
  357: @item AF_INET
  358: @vindex AF_INET
  359: This designates the address format that goes with the Internet
  360: namespace.  (@code{PF_INET} is the name of that namespace.)
  361: @xref{Internet Address Formats}.
  362: 
  363: @comment sys/socket.h
  364: @comment IPv6 Basic API
  365: @item AF_INET6
  366: This is similar to @code{AF_INET}, but refers to the IPv6 protocol.
  367: (@code{PF_INET6} is the name of the corresponding namespace.)
  368: 
  369: @comment sys/socket.h
  370: @comment BSD
  371: @item AF_UNSPEC
  372: @vindex AF_UNSPEC
  373: This designates no particular address format.  It is used only in rare
  374: cases, such as to clear out the default destination address of a
  375: ``connected'' datagram socket.  @xref{Sending Datagrams}.
  376: 
  377: The corresponding namespace designator symbol @code{PF_UNSPEC} exists
  378: for completeness, but there is no reason to use it in a program.
  379: @end table
  380: 
  381: @file{sys/socket.h} defines symbols starting with @samp{AF_} for many
  382: different kinds of networks, most or all of which are not actually
  383: implemented.  We will document those that really work as we receive
  384: information about how to use them.
  385: 
  386: @node Setting Address
  387: @subsection Setting the Address of a Socket
  388: 
  389: @pindex sys/socket.h
  390: Use the @code{bind} function to assign an address to a socket.  The
  391: prototype for @code{bind} is in the header file @file{sys/socket.h}.
  392: For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}.
  393: 
  394: @comment sys/socket.h
  395: @comment BSD
  396: @deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
  397: The @code{bind} function assigns an address to the socket
  398: @var{socket}.  The @var{addr} and @var{length} arguments specify the
  399: address; the detailed format of the address depends on the namespace.
  400: The first part of the address is always the format designator, which
  401: specifies a namespace, and says that the address is in the format of
  402: that namespace.
  403: 
  404: The return value is @code{0} on success and @code{-1} on failure.  The
  405: following @code{errno} error conditions are defined for this function:
  406: 
  407: @table @code
  408: @item EBADF
  409: The @var{socket} argument is not a valid file descriptor.
  410: 
  411: @item ENOTSOCK
  412: The descriptor @var{socket} is not a socket.
  413: 
  414: @item EADDRNOTAVAIL
  415: The specified address is not available on this machine.
  416: 
  417: @item EADDRINUSE
  418: Some other socket is already using the specified address.
  419: 
  420: @item EINVAL
  421: The socket @var{socket} already has an address.
  422: 
  423: @item EACCES
  424: You do not have permission to access the requested address.  (In the
  425: Internet domain, only the super-user is allowed to specify a port number
  426: in the range 0 through @code{IPPORT_RESERVED} minus one; see
  427: @ref{Ports}.)
  428: @end table
  429: 
  430: Additional conditions may be possible depending on the particular namespace
  431: of the socket.
  432: @end deftypefun
  433: 
  434: @node Reading Address
  435: @subsection Reading the Address of a Socket
  436: 
  437: @pindex sys/socket.h
  438: Use the function @code{getsockname} to examine the address of an
  439: Internet socket.  The prototype for this function is in the header file
  440: @file{sys/socket.h}.
  441: 
  442: @comment sys/socket.h
  443: @comment BSD
  444: @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
  445: The @code{getsockname} function returns information about the
  446: address of the socket @var{socket} in the locations specified by the
  447: @var{addr} and @var{length-ptr} arguments.  Note that the
  448: @var{length-ptr} is a pointer; you should initialize it to be the
  449: allocation size of @var{addr}, and on return it contains the actual
  450: size of the address data.
  451: 
  452: The format of the address data depends on the socket namespace.  The
  453: length of the information is usually fixed for a given namespace, so
  454: normally you can know exactly how much space is needed and can provide
  455: that much.  The usual practice is to allocate a place for the value
  456: using the proper data type for the socket's namespace, then cast its
  457: address to @code{struct sockaddr *} to pass it to @code{getsockname}.
  458: 
  459: The return value is @code{0} on success and @code{-1} on error.  The
  460: following @code{errno} error conditions are defined for this function:
  461: 
  462: @table @code
  463: @item EBADF
  464: The @var{socket} argument is not a valid file descriptor.
  465: 
  466: @item ENOTSOCK
  467: The descriptor @var{socket} is not a socket.
  468: 
  469: @item ENOBUFS
  470: There are not enough internal buffers available for the operation.
  471: @end table
  472: @end deftypefun
  473: 
  474: You can't read the address of a socket in the file namespace.  This is
  475: consistent with the rest of the system; in general, there's no way to
  476: find a file's name from a descriptor for that file.
  477: 
  478: @node Interface Naming
  479: @section Interface Naming
  480: 
  481: Each network interface has a name.  This usually consists of a few
  482: letters that relate to the type of interface, which may be followed by a
  483: number if there is more than one interface of that type.  Examples
  484: might be @code{lo} (the loopback interface) and @code{eth0} (the first
  485: Ethernet interface).
  486: 
  487: Although such names are convenient for humans, it would be clumsy to
  488: have to use them whenever a program needs to refer to an interface.  In
  489: such situations an interface is referred to by its @dfn{index}, which is
  490: an arbitrarily-assigned small positive integer.
  491: 
  492: The following functions, constants and data types are declared in the
  493: header file @file{net/if.h}.
  494: 
  495: @comment net/if.h
  496: @deftypevr Constant size_t IFNAMSIZ
  497: This constant defines the maximum buffer size needed to hold an
  498: interface name, including its terminating zero byte.
  499: @end deftypevr
  500: 
  501: @comment net/if.h
  502: @comment IPv6 basic API
  503: @deftypefun {unsigned int} if_nametoindex (const char *ifname)
  504: This function yields the interface index corresponding to a particular
  505: name.  If no interface exists with the name given, it returns 0.
  506: @end deftypefun
  507: 
  508: @comment net/if.h
  509: @comment IPv6 basic API
  510: @deftypefun {char *} if_indextoname (unsigned int ifindex, char *ifname)
  511: This function maps an interface index to its corresponding name.  The
  512: returned name is placed in the buffer pointed to by @code{ifname}, which
  513: must be at least @code{IFNAMSIZ} bytes in length.  If the index was
  514: invalid, the function's return value is a null pointer, otherwise it is
  515: @code{ifname}.
  516: @end deftypefun
  517: 
  518: @comment net/if.h
  519: @comment IPv6 basic API
  520: @deftp {Data Type} {struct if_nameindex}
  521: This data type is used to hold the information about a single
  522: interface.  It has the following members:
  523: 
  524: @table @code
  525: @item unsigned int if_index;
  526: This is the interface index.
  527: 
  528: @item char *if_name
  529: This is the null-terminated index name.
  530: 
  531: @end table
  532: @end deftp
  533: 
  534: @comment net/if.h
  535: @comment IPv6 basic API
  536: @deftypefun {struct if_nameindex *} if_nameindex (void)
  537: This function returns an array of @code{if_nameindex} structures, one
  538: for every interface that is present.  The end of the list is indicated
  539: by a structure with an interface of 0 and a null name pointer.  If an
  540: error occurs, this function returns a null pointer.
  541: 
  542: The returned structure must be freed with @code{if_freenameindex} after
  543: use.
  544: @end deftypefun
  545: 
  546: @comment net/if.h
  547: @comment IPv6 basic API
  548: @deftypefun void if_freenameindex (struct if_nameindex *ptr)
  549: This function frees the structure returned by an earlier call to
  550: @code{if_nameindex}.
  551: @end deftypefun
  552: 
  553: @node Local Namespace
  554: @section The Local Namespace
  555: @cindex local namespace, for sockets
  556: 
  557: This section describes the details of the local namespace, whose
  558: symbolic name (required when you create a socket) is @code{PF_LOCAL}.
  559: The local namespace is also known as ``Unix domain sockets''.  Another
  560: name is file namespace since socket addresses are normally implemented
  561: as file names.
  562: 
  563: @menu
  564: * Concepts: Local Namespace Concepts. What you need to understand.
  565: * Details: Local Namespace Details.   Address format, symbolic names, etc.
  566: * Example: Local Socket Example.      Example of creating a socket.
  567: @end menu
  568: 
  569: @node Local Namespace Concepts
  570: @subsection Local Namespace Concepts
  571: 
  572: In the local namespace socket addresses are file names.  You can specify
  573: any file name you want as the address of the socket, but you must have
  574: write permission on the directory containing it.
  575: @c XXX The following was said to be wrong.
  576: @c In order to connect to a socket you must have read permission for it.
  577: It's common to put these files in the @file{/tmp} directory.
  578: 
  579: One peculiarity of the local namespace is that the name is only used
  580: when opening the connection; once open the address is not meaningful and
  581: may not exist.
  582: 
  583: Another peculiarity is that you cannot connect to such a socket from
  584: another machine--not even if the other machine shares the file system
  585: which contains the name of the socket.  You can see the socket in a
  586: directory listing, but connecting to it never succeeds.  Some programs
  587: take advantage of this, such as by asking the client to send its own
  588: process ID, and using the process IDs to distinguish between clients.
  589: However, we recommend you not use this method in protocols you design,
  590: as we might someday permit connections from other machines that mount
  591: the same file systems.  Instead, send each new client an identifying
  592: number if you want it to have one.
  593: 
  594: After you close a socket in the local namespace, you should delete the
  595: file name from the file system.  Use @code{unlink} or @code{remove} to
  596: do this; see @ref{Deleting Files}.
  597: 
  598: The local namespace supports just one protocol for any communication
  599: style; it is protocol number @code{0}.
  600: 
  601: @node Local Namespace Details
  602: @subsection Details of Local Namespace
  603: 
  604: @pindex sys/socket.h
  605: To create a socket in the local namespace, use the constant
  606: @code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or
  607: @code{socketpair}.  This constant is defined in @file{sys/socket.h}.
  608: 
  609: @comment sys/socket.h
  610: @comment POSIX
  611: @deftypevr Macro int PF_LOCAL
  612: This designates the local namespace, in which socket addresses are local
  613: names, and its associated family of protocols.  @code{PF_Local} is the
  614: macro used by Posix.1g.
  615: @end deftypevr
  616: 
  617: @comment sys/socket.h
  618: @comment BSD
  619: @deftypevr Macro int PF_UNIX
  620: This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
  621: @end deftypevr
  622: 
  623: @comment sys/socket.h
  624: @comment GNU
  625: @deftypevr Macro int PF_FILE
  626: This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
  627: @end deftypevr
  628: 
  629: The structure for specifying socket names in the local namespace is
  630: defined in the header file @file{sys/un.h}:
  631: @pindex sys/un.h
  632: 
  633: @comment sys/un.h
  634: @comment BSD
  635: @deftp {Data Type} {struct sockaddr_un}
  636: This structure is used to specify local namespace socket addresses.  It has
  637: the following members:
  638: 
  639: @table @code
  640: @item short int sun_family
  641: This identifies the address family or format of the socket address.
  642: You should store the value @code{AF_LOCAL} to designate the local
  643: namespace.  @xref{Socket Addresses}.
  644: 
  645: @item char sun_path[108]
  646: This is the file name to use.
  647: 
  648: @strong{Incomplete:}  Why is 108 a magic number?  RMS suggests making
  649: this a zero-length array and tweaking the following example to use
  650: @code{alloca} to allocate an appropriate amount of storage based on
  651: the length of the filename.
  652: @end table
  653: @end deftp
  654: 
  655: You should compute the @var{length} parameter for a socket address in
  656: the local namespace as the sum of the size of the @code{sun_family}
  657: component and the string length (@emph{not} the allocation size!) of
  658: the file name string.  This can be done using the macro @code{SUN_LEN}:
  659: 
  660: @comment sys/un.h
  661: @comment BSD
  662: @deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr})
  663: The macro computes the length of socket address in the local namespace.
  664: @end deftypefn
  665: 
  666: @node Local Socket Example
  667: @subsection Example of Local-Namespace Sockets
  668: 
  669: Here is an example showing how to create and name a socket in the local
  670: namespace.
  671: 
  672: @smallexample
  673: @include mkfsock.c.texi
  674: @end smallexample
  675: 
  676: @node Internet Namespace
  677: @section The Internet Namespace
  678: @cindex Internet namespace, for sockets
  679: 
  680: This section describes the details of the protocols and socket naming
  681: conventions used in the Internet namespace.
  682: 
  683: Originally the Internet namespace used only IP version 4 (IPv4).  With
  684: the growing number of hosts on the Internet, a new protocol with a
  685: larger address space was necessary: IP version 6 (IPv6).  IPv6
  686: introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
  687: features, and will eventually replace IPv4.
  688: 
  689: To create a socket in the IPv4 Internet namespace, use the symbolic name
  690: @code{PF_INET} of this namespace as the @var{namespace} argument to
  691: @code{socket} or @code{socketpair}.  For IPv6 addresses you need the
  692: macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}.
  693: @pindex sys/socket.h
  694: 
  695: @comment sys/socket.h
  696: @comment BSD
  697: @deftypevr Macro int PF_INET
  698: This designates the IPv4 Internet namespace and associated family of
  699: protocols.
  700: @end deftypevr
  701: 
  702: @comment sys/socket.h
  703: @comment X/Open
  704: @deftypevr Macro int PF_INET6
  705: This designates the IPv6 Internet namespace and associated family of
  706: protocols.
  707: @end deftypevr
  708: 
  709: A socket address for the Internet namespace includes the following components:
  710: 
  711: @itemize @bullet
  712: @item
  713: The address of the machine you want to connect to.  Internet addresses
  714: can be specified in several ways; these are discussed in @ref{Internet
  715: Address Formats}, @ref{Host Addresses} and @ref{Host Names}.
  716: 
  717: @item
  718: A port number for that machine.  @xref{Ports}.
  719: @end itemize
  720: 
  721: You must ensure that the address and port number are represented in a
  722: canonical format called @dfn{network byte order}.  @xref{Byte Order},
  723: for information about this.
  724: 
  725: @menu
  726: * Internet Address Formats::    How socket addresses are specified in the
  727:                                  Internet namespace.
  728: * Host Addresses::              All about host addresses of Internet host.
  729: * Protocols Database::          Referring to protocols by name.
  730: * Ports::                       Internet port numbers.
  731: * Services Database::           Ports may have symbolic names.
  732: * Byte Order::                  Different hosts may use different byte
  733:                                  ordering conventions; you need to
  734:                                  canonicalize host address and port number.
  735: * Inet Example::                Putting it all together.
  736: @end menu
  737: 
  738: @node Internet Address Formats
  739: @subsection Internet Socket Address Formats
  740: 
  741: In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6
  742: (@code{AF_INET6}), a socket address consists of a host address
  743: and a port on that host.  In addition, the protocol you choose serves
  744: effectively as a part of the address because local port numbers are
  745: meaningful only within a particular protocol.
  746: 
  747: The data types for representing socket addresses in the Internet namespace
  748: are defined in the header file @file{netinet/in.h}.
  749: @pindex netinet/in.h
  750: 
  751: @comment netinet/in.h
  752: @comment BSD
  753: @deftp {Data Type} {struct sockaddr_in}
  754: This is the data type used to represent socket addresses in the
  755: Internet namespace.  It has the following members:
  756: 
  757: @table @code
  758: @item sa_family_t sin_family