PageRenderTime 54ms CodeModel.GetById 32ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 1ms

/Sources/selp_glibc-2.5.90-19.0.46/manual/socket.texi

https://bitbucket.org/Mali_Laurent/ps50c550
Unknown | 3196 lines | 2626 code | 570 blank | 0 comment | 0 complexity | 6717c0fed79090fee0ef8abd53cda7a7 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   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
   5This chapter describes the GNU facilities for interprocess
   6communication using sockets.
   7
   8@cindex socket
   9@cindex interprocess communication, with sockets
  10A @dfn{socket} is a generalized interprocess communication channel.
  11Like a pipe, a socket is represented as a file descriptor.  Unlike pipes
  12sockets support communication between unrelated processes, and even
  13between processes running on different machines that communicate over a
  14network.  Sockets are the primary means of communicating with other
  15machines; @code{telnet}, @code{rlogin}, @code{ftp}, @code{talk} and the
  16other familiar network programs use sockets.
  17
  18Not all operating systems support sockets.  In the GNU library, the
  19header file @file{sys/socket.h} exists regardless of the operating
  20system, and the socket functions always exist, but if the system does
  21not really support sockets these functions always fail.
  22
  23@strong{Incomplete:} We do not currently document the facilities for
  24broadcast messages or for configuring Internet interfaces.  The
  25reentrant functions and some newer functions that are related to IPv6
  26aren'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)
  51When you create a socket, you must specify the style of communication
  52you want to use and the type of protocol that should implement it.
  53The @dfn{communication style} of a socket defines the user-level
  54semantics of sending and receiving data on the socket.  Choosing a
  55communication 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
  63styles regard the data as a sequence of bytes with no larger
  64structure; others group the bytes into records (which are known in
  65this 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
  71styles guarantee that all the data sent arrives in the order it was
  72sent (barring system or network crashes); other styles occasionally
  73lose data as a normal part of operation, and may sometimes deliver
  74packets more than once or in the wrong order.
  75
  76Designing a program to use unreliable communication styles usually
  77involves taking precautions to detect lost or misordered packets and
  78to retransmit data as needed.
  79
  80@item
  81@strong{Is communication entirely with one partner?}  Some
  82communication styles are like a telephone call---you make a
  83@dfn{connection} with one remote socket and then exchange data
  84freely.  Other styles are like mailing letters---you specify a
  85destination 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
  92You must also choose a @dfn{namespace} for naming the socket.  A socket
  93name (``address'') is meaningful only in the context of a particular
  94namespace.  In fact, even the data type to use for a socket name may
  95depend on the namespace.  Namespaces are also called ``domains'', but we
  96avoid that word as it can be confused with other usage of the same
  97term.  Each namespace has a symbolic name that starts with @samp{PF_}.
  98A corresponding symbolic name starting with @samp{AF_} designates the
  99address format for that namespace.
 100
 101@cindex network protocol
 102@cindex protocol (of socket)
 103@cindex socket protocol
 104@cindex protocol family
 105Finally you must choose the @dfn{protocol} to carry out the
 106communication.  The protocol determines what low-level mechanism is used
 107to transmit and receive data.  Each protocol is valid for a particular
 108namespace and communication style; a namespace is sometimes called a
 109@dfn{protocol family} because of this, which is why the namespace names
 110start with @samp{PF_}.
 111
 112The rules of a protocol apply to the data passing between two programs,
 113perhaps on different computers; most of these rules are handled by the
 114operating system and you need not know about them.  What you do need to
 115know about protocols is this:
 116
 117@itemize @bullet
 118@item
 119In order to have communication between two sockets, they must specify
 120the @emph{same} protocol.
 121
 122@item
 123Each protocol is meaningful with particular style/namespace
 124combinations and cannot be used with inappropriate combinations.  For
 125example, the TCP protocol fits only the byte stream style of
 126communication and the Internet namespace.
 127
 128@item
 129For each combination of style and namespace there is a @dfn{default
 130protocol}, which you can request by specifying 0 as the protocol
 131number.  And that's what you should normally do---use the default.
 132@end itemize
 133
 134Throughout the following description at various places
 135variables/parameters to denote sizes are required.  And here the trouble
 136starts.  In the first implementations the type of these variables was
 137simply @code{int}.  On most machines at that time an @code{int} was 32
 138bits wide, which created a @emph{de facto} standard requiring 32-bit
 139variables.  This is important since references to variables of this type
 140are passed to the kernel.
 141
 142Then the POSIX people came and unified the interface with the words "all
 143size 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
 145possible.
 146
 147The Unix98 specification provides a solution by introducing a type
 148@code{socklen_t}.  This type is used in all of the cases that POSIX
 149changed to use @code{size_t}.  The only requirement of this type is that
 150it be an unsigned type of at least 32 bits.  Therefore, implementations
 151which require that references to 32-bit variables be passed can be as
 152happy as implementations which use 64-bit values.
 153
 154
 155@node Communication Styles
 156@section Communication Styles
 157
 158The GNU library includes support for several different kinds of sockets,
 159each with different characteristics.  This section describes the
 160supported socket types.  The symbolic constants listed here are
 161defined 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
 167The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}).
 168It operates over a connection with a particular remote socket and
 169transmits data reliably as a stream of bytes.
 170
 171Use 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
 177The @code{SOCK_DGRAM} style is used for sending
 178individually-addressed packets unreliably.
 179It is the diametrical opposite of @code{SOCK_STREAM}.
 180
 181Each time you write data to a socket of this kind, that data becomes
 182one packet.  Since @code{SOCK_DGRAM} sockets do not have connections,
 183you must specify the recipient address with each packet.
 184
 185The only guarantee that the system makes about your requests to
 186transmit data is that it will try its best to deliver each packet you
 187send.  It may succeed with the sixth packet after failing with the
 188fourth and fifth packets; the seventh packet may arrive before the
 189sixth, and may arrive a second time after the sixth.
 190
 191The typical use for @code{SOCK_DGRAM} is in situations where it is
 192acceptable to simply re-send a packet if no response is seen in a
 193reasonable amount of time.
 194
 195@xref{Datagrams}, for detailed information about how to use datagram
 196sockets.
 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
 205This style is like @code{SOCK_STREAM} except that the data are
 206structured into packets.
 207
 208A program that receives data over a @code{SOCK_SEQPACKET} socket
 209should be prepared to read the entire message packet in a single call
 210to @code{read}; if it only reads part of the message, the remainder of
 211the message is simply discarded instead of being available for
 212subsequent calls to @code{read}.
 213
 214Many 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
 222This style is a reliable version of @code{SOCK_DGRAM}: it sends
 223individually addressed packets, but guarantees that each packet sent
 224arrives exactly once.
 225
 226@strong{Warning:} It is not clear this is actually supported
 227by any operating system.
 228@end deftypevr
 229@end ignore
 230
 231@comment sys/socket.h
 232@comment BSD
 233@deftypevr Macro int SOCK_RAW
 234This style provides access to low-level network protocols and
 235interfaces.  Ordinary user programs usually have no need to use this
 236style.
 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
 246The name of a socket is normally called an @dfn{address}.  The
 247functions and symbols for dealing with socket addresses were named
 248inconsistently, sometimes using the term ``name'' and sometimes using
 249``address''.  You can regard these terms as synonymous where sockets
 250are concerned.
 251
 252A socket newly created with the @code{socket} function has no
 253address.  Other processes can find it for communication only if you
 254give it an address.  We call this @dfn{binding} the address to the
 255socket, and the way to do it is with the @code{bind} function.
 256
 257You need be concerned with the address of a socket if other processes
 258are to find it and start communicating with it.  You can specify an
 259address for other sockets, but this is usually pointless; the first time
 260you send data from a socket, or use it to initiate a connection, the
 261system assigns an address automatically if you have not specified one.
 262
 263Occasionally a client needs to specify an address because the server
 264discriminates based on address; for example, the rsh and rlogin
 265protocols look at the client's socket address and only bypass password
 266checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
 267
 268The details of socket addresses vary depending on what namespace you are
 269using.  @xref{Local Namespace}, or @ref{Internet Namespace}, for specific
 270information.
 271
 272Regardless of the namespace, you use the same functions @code{bind} and
 273@code{getsockname} to set and examine a socket's address.  These
 274functions use a phony data type, @code{struct sockaddr *}, to accept the
 275address.  In practice, the address lives in a structure of some other
 276data type appropriate to the address format you are using, but you cast
 277its 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
 289The functions @code{bind} and @code{getsockname} use the generic data
 290type @code{struct sockaddr *} to represent a pointer to a socket
 291address.  You can't use this data type effectively to interpret an
 292address or construct one; for that, you must use the proper data type
 293for the socket's namespace.
 294
 295Thus, the usual practice is to construct an address of the proper
 296namespace-specific type, then cast a pointer to @code{struct sockaddr *}
 297when you call @code{bind} or @code{getsockname}.
 298
 299The one piece of information that you can get from the @code{struct
 300sockaddr} data type is the @dfn{address format designator}.  This tells
 301you which data type to use to understand the address fully.
 302
 303@pindex sys/socket.h
 304The 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}
 310The @code{struct sockaddr} type itself has the following members:
 311
 312@table @code
 313@item short int sa_family
 314This is the code for the address format of this address.  It
 315identifies the format of the data which follows.
 316
 317@item char sa_data[14]
 318This is the actual socket address data, which is format-dependent.  Its
 319length also depends on the format, and may well be more than 14.  The
 320length 14 of @code{sa_data} is essentially arbitrary.
 321@end table
 322@end deftp
 323
 324Each address format has a symbolic name which starts with @samp{AF_}.
 325Each of them corresponds to a @samp{PF_} symbol which designates the
 326corresponding 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
 333This designates the address format that goes with the local namespace.
 334(@code{PF_LOCAL} is the name of that namespace.)  @xref{Local Namespace
 335Details}, for information about this address format.
 336
 337@comment sys/socket.h
 338@comment BSD, Unix98
 339@item AF_UNIX
 340@vindex AF_UNIX
 341This is a synonym for @code{AF_LOCAL}.  Although @code{AF_LOCAL} is
 342mandated 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
 344POSIX systems support it.  It is also the name of choice in the Unix98
 345specification. (The same is true for @code{PF_UNIX}
 346vs. @code{PF_LOCAL}).
 347
 348@comment sys/socket.h
 349@comment GNU
 350@item AF_FILE
 351@vindex AF_FILE
 352This 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
 359This designates the address format that goes with the Internet
 360namespace.  (@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
 366This 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
 373This designates no particular address format.  It is used only in rare
 374cases, such as to clear out the default destination address of a
 375``connected'' datagram socket.  @xref{Sending Datagrams}.
 376
 377The corresponding namespace designator symbol @code{PF_UNSPEC} exists
 378for 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
 382different kinds of networks, most or all of which are not actually
 383implemented.  We will document those that really work as we receive
 384information about how to use them.
 385
 386@node Setting Address
 387@subsection Setting the Address of a Socket
 388
 389@pindex sys/socket.h
 390Use the @code{bind} function to assign an address to a socket.  The
 391prototype for @code{bind} is in the header file @file{sys/socket.h}.
 392For 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})
 397The @code{bind} function assigns an address to the socket
 398@var{socket}.  The @var{addr} and @var{length} arguments specify the
 399address; the detailed format of the address depends on the namespace.
 400The first part of the address is always the format designator, which
 401specifies a namespace, and says that the address is in the format of
 402that namespace.
 403
 404The return value is @code{0} on success and @code{-1} on failure.  The
 405following @code{errno} error conditions are defined for this function:
 406
 407@table @code
 408@item EBADF
 409The @var{socket} argument is not a valid file descriptor.
 410
 411@item ENOTSOCK
 412The descriptor @var{socket} is not a socket.
 413
 414@item EADDRNOTAVAIL
 415The specified address is not available on this machine.
 416
 417@item EADDRINUSE
 418Some other socket is already using the specified address.
 419
 420@item EINVAL
 421The socket @var{socket} already has an address.
 422
 423@item EACCES
 424You do not have permission to access the requested address.  (In the
 425Internet domain, only the super-user is allowed to specify a port number
 426in the range 0 through @code{IPPORT_RESERVED} minus one; see
 427@ref{Ports}.)
 428@end table
 429
 430Additional conditions may be possible depending on the particular namespace
 431of the socket.
 432@end deftypefun
 433
 434@node Reading Address
 435@subsection Reading the Address of a Socket
 436
 437@pindex sys/socket.h
 438Use the function @code{getsockname} to examine the address of an
 439Internet 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})
 445The @code{getsockname} function returns information about the
 446address 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
 449allocation size of @var{addr}, and on return it contains the actual
 450size of the address data.
 451
 452The format of the address data depends on the socket namespace.  The
 453length of the information is usually fixed for a given namespace, so
 454normally you can know exactly how much space is needed and can provide
 455that much.  The usual practice is to allocate a place for the value
 456using the proper data type for the socket's namespace, then cast its
 457address to @code{struct sockaddr *} to pass it to @code{getsockname}.
 458
 459The return value is @code{0} on success and @code{-1} on error.  The
 460following @code{errno} error conditions are defined for this function:
 461
 462@table @code
 463@item EBADF
 464The @var{socket} argument is not a valid file descriptor.
 465
 466@item ENOTSOCK
 467The descriptor @var{socket} is not a socket.
 468
 469@item ENOBUFS
 470There are not enough internal buffers available for the operation.
 471@end table
 472@end deftypefun
 473
 474You can't read the address of a socket in the file namespace.  This is
 475consistent with the rest of the system; in general, there's no way to
 476find a file's name from a descriptor for that file.
 477
 478@node Interface Naming
 479@section Interface Naming
 480
 481Each network interface has a name.  This usually consists of a few
 482letters that relate to the type of interface, which may be followed by a
 483number if there is more than one interface of that type.  Examples
 484might be @code{lo} (the loopback interface) and @code{eth0} (the first
 485Ethernet interface).
 486
 487Although such names are convenient for humans, it would be clumsy to
 488have to use them whenever a program needs to refer to an interface.  In
 489such situations an interface is referred to by its @dfn{index}, which is
 490an arbitrarily-assigned small positive integer.
 491
 492The following functions, constants and data types are declared in the
 493header file @file{net/if.h}.
 494
 495@comment net/if.h
 496@deftypevr Constant size_t IFNAMSIZ
 497This constant defines the maximum buffer size needed to hold an
 498interface 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)
 504This function yields the interface index corresponding to a particular
 505name.  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)
 511This function maps an interface index to its corresponding name.  The
 512returned name is placed in the buffer pointed to by @code{ifname}, which
 513must be at least @code{IFNAMSIZ} bytes in length.  If the index was
 514invalid, 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}
 521This data type is used to hold the information about a single
 522interface.  It has the following members:
 523
 524@table @code
 525@item unsigned int if_index;
 526This is the interface index.
 527
 528@item char *if_name
 529This 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)
 537This function returns an array of @code{if_nameindex} structures, one
 538for every interface that is present.  The end of the list is indicated
 539by a structure with an interface of 0 and a null name pointer.  If an
 540error occurs, this function returns a null pointer.
 541
 542The returned structure must be freed with @code{if_freenameindex} after
 543use.
 544@end deftypefun
 545
 546@comment net/if.h
 547@comment IPv6 basic API
 548@deftypefun void if_freenameindex (struct if_nameindex *ptr)
 549This 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
 557This section describes the details of the local namespace, whose
 558symbolic name (required when you create a socket) is @code{PF_LOCAL}.
 559The local namespace is also known as ``Unix domain sockets''.  Another
 560name is file namespace since socket addresses are normally implemented
 561as 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
 572In the local namespace socket addresses are file names.  You can specify
 573any file name you want as the address of the socket, but you must have
 574write 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.
 577It's common to put these files in the @file{/tmp} directory.
 578
 579One peculiarity of the local namespace is that the name is only used
 580when opening the connection; once open the address is not meaningful and
 581may not exist.
 582
 583Another peculiarity is that you cannot connect to such a socket from
 584another machine--not even if the other machine shares the file system
 585which contains the name of the socket.  You can see the socket in a
 586directory listing, but connecting to it never succeeds.  Some programs
 587take advantage of this, such as by asking the client to send its own
 588process ID, and using the process IDs to distinguish between clients.
 589However, we recommend you not use this method in protocols you design,
 590as we might someday permit connections from other machines that mount
 591the same file systems.  Instead, send each new client an identifying
 592number if you want it to have one.
 593
 594After you close a socket in the local namespace, you should delete the
 595file name from the file system.  Use @code{unlink} or @code{remove} to
 596do this; see @ref{Deleting Files}.
 597
 598The local namespace supports just one protocol for any communication
 599style; it is protocol number @code{0}.
 600
 601@node Local Namespace Details
 602@subsection Details of Local Namespace
 603
 604@pindex sys/socket.h
 605To 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
 612This designates the local namespace, in which socket addresses are local
 613names, and its associated family of protocols.  @code{PF_Local} is the
 614macro used by Posix.1g.
 615@end deftypevr
 616
 617@comment sys/socket.h
 618@comment BSD
 619@deftypevr Macro int PF_UNIX
 620This 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
 626This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
 627@end deftypevr
 628
 629The structure for specifying socket names in the local namespace is
 630defined 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}
 636This structure is used to specify local namespace socket addresses.  It has
 637the following members:
 638
 639@table @code
 640@item short int sun_family
 641This identifies the address family or format of the socket address.
 642You should store the value @code{AF_LOCAL} to designate the local
 643namespace.  @xref{Socket Addresses}.
 644
 645@item char sun_path[108]
 646This is the file name to use.
 647
 648@strong{Incomplete:}  Why is 108 a magic number?  RMS suggests making
 649this a zero-length array and tweaking the following example to use
 650@code{alloca} to allocate an appropriate amount of storage based on
 651the length of the filename.
 652@end table
 653@end deftp
 654
 655You should compute the @var{length} parameter for a socket address in
 656the local namespace as the sum of the size of the @code{sun_family}
 657component and the string length (@emph{not} the allocation size!) of
 658the 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})
 663The 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
 669Here is an example showing how to create and name a socket in the local
 670namespace.
 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
 680This section describes the details of the protocols and socket naming
 681conventions used in the Internet namespace.
 682
 683Originally the Internet namespace used only IP version 4 (IPv4).  With
 684the growing number of hosts on the Internet, a new protocol with a
 685larger address space was necessary: IP version 6 (IPv6).  IPv6
 686introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
 687features, and will eventually replace IPv4.
 688
 689To 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
 692macro @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
 698This designates the IPv4 Internet namespace and associated family of
 699protocols.
 700@end deftypevr
 701
 702@comment sys/socket.h
 703@comment X/Open
 704@deftypevr Macro int PF_INET6
 705This designates the IPv6 Internet namespace and associated family of
 706protocols.
 707@end deftypevr
 708
 709A socket address for the Internet namespace includes the following components:
 710
 711@itemize @bullet
 712@item
 713The address of the machine you want to connect to.  Internet addresses
 714can be specified in several ways; these are discussed in @ref{Internet
 715Address Formats}, @ref{Host Addresses} and @ref{Host Names}.
 716
 717@item
 718A port number for that machine.  @xref{Ports}.
 719@end itemize
 720
 721You must ensure that the address and port number are represented in a
 722canonical format called @dfn{network byte order}.  @xref{Byte Order},
 723for 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
 741In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6
 742(@code{AF_INET6}), a socket address consists of a host address
 743and a port on that host.  In addition, the protocol you choose serves
 744effectively as a part of the address because local port numbers are
 745meaningful only within a particular protocol.
 746
 747The data types for representing socket addresses in the Internet namespace
 748are 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}
 754This is the data type used to represent socket addresses in the
 755Internet namespace.  It has the following members:
 756
 757@table @code
 758@item sa_family_t sin_family
 759This identifies the address family or format of the socket address.
 760You should store the value @code{AF_INET} in this member.
 761@xref{Socket Addresses}.
 762
 763@item struct in_addr sin_addr
 764This is the Internet address of the host machine.  @xref{Host
 765Addresses}, and @ref{Host Names}, for how to get a value to store
 766here.
 767
 768@item unsigned short int sin_port
 769This is the port number.  @xref{Ports}.
 770@end table
 771@end deftp
 772
 773When you call @code{bind} or @code{getsockname}, you should specify
 774@code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
 775you are using an IPv4 Internet namespace socket address.
 776
 777@deftp {Data Type} {struct sockaddr_in6}
 778This is the data type used to represent socket addresses in the IPv6
 779namespace.  It has the following members:
 780
 781@table @code
 782@item sa_family_t sin6_family
 783This identifies the address family or format of the socket address.
 784You should store the value of @code{AF_INET6} in this member.
 785@xref{Socket Addresses}.
 786
 787@item struct in6_addr sin6_addr
 788This is the IPv6 address of the host machine.  @xref{Host
 789Addresses}, and @ref{Host Names}, for how to get a value to store
 790here.
 791
 792@item uint32_t sin6_flowinfo
 793This is a currently unimplemented field.
 794
 795@item uint16_t sin6_port
 796This is the port number.  @xref{Ports}.
 797
 798@end table
 799@end deftp
 800
 801@node Host Addresses
 802@subsection Host Addresses
 803
 804Each computer on the Internet has one or more @dfn{Internet addresses},
 805numbers which identify that computer among all those on the Internet.
 806Users typically write IPv4 numeric host addresses as sequences of four
 807numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6
 808numeric host addresses as sequences of up to eight numbers separated by
 809colons, as in @samp{5f03:1200:836f:c100::1}.
 810
 811Each computer also has one or more @dfn{host names}, which are strings
 812of words separated by periods, as in @samp{mescaline.gnu.org}.
 813
 814Programs that let the user specify a host typically accept both numeric
 815addresses and host names.  To open a connection a program needs a
 816numeric address, and so must convert a host name to the numeric address
 817it stands for.
 818
 819@menu
 820* Abstract Host Addresses::	What a host number consists of.
 821* Data type: Host Address Data Type.	Data type for a host number.
 822* Functions: Host Address Functions.	Functions to operate on them.
 823* Names: Host Names.		Translating host names to host numbers.
 824@end menu
 825
 826@node Abstract Host Addresses
 827@subsubsection Internet Host Addresses
 828@cindex host address, Internet
 829@cindex Internet host address
 830
 831@ifinfo
 832Each computer on the Internet has one or more Internet addresses,
 833numbers which identify that computer among all those on the Internet.
 834@end ifinfo
 835
 836@cindex network number
 837@cindex local network address number
 838An IPv4 Internet host address is a number containing four bytes of data.
 839Historically these are divided into two parts, a @dfn{network number} and a
 840@dfn{local network address number} within that network.  In the
 841mid-1990s classless addresses were introduced which changed this
 842behavior.  Since some functions implicitly expect the old definitions,
 843we first describe the class-based network and will then describe
 844classless addresses.  IPv6 uses only classless addresses and therefore
 845the following paragraphs don't apply.
 846
 847The class-based IPv4 network number consists of the first one, two or
 848three bytes; the rest of the bytes are the local address.
 849
 850IPv4 network numbers are registered with the Network Information Center
 851(NIC), and are divided into three classes---A, B and C.  The local
 852network address numbers of individual machines are registered with the
 853administrator of the particular network.
 854
 855Class A networks have single-byte numbers in the range 0 to 127.  There
 856are only a small number of Class A networks, but they can each support a
 857very large number of hosts.  Medium-sized Class B networks have two-byte
 858network numbers, with the first byte in the range 128 to 191.  Class C
 859networks are the smallest; they have three-byte network numbers, with
 860the first byte in the range 192-255.  Thus, the first 1, 2, or 3 bytes
 861of an Internet address specify a network.  The remaining bytes of the
 862Internet address specify the address within that network.
 863
 864The Class A network 0 is reserved for broadcast to all networks.  In
 865addition, the host number 0 within each network is reserved for broadcast
 866to all hosts in that network.  These uses are obsolete now but for
 867compatibility reasons you shouldn't use network 0 and host number 0.
 868
 869The Class A network 127 is reserved for loopback; you can always use
 870the Internet address @samp{127.0.0.1} to refer to the host machine.
 871
 872Since a single machine can be a member of multiple networks, it can
 873have multiple Internet host addresses.  However, there is never
 874supposed to be more than one machine with the same host address.
 875
 876@c !!! this section could document the IN_CLASS* macros in <netinet/in.h>.
 877@c No, it shouldn't since they're obsolete.
 878
 879@cindex standard dot notation, for Internet addresses
 880@cindex dot notation, for Internet addresses
 881There are four forms of the @dfn{standard numbers-and-dots notation}
 882for Internet addresses:
 883
 884@table @code
 885@item @var{a}.@var{b}.@var{c}.@var{d}
 886This specifies all four bytes of the address individually and is the
 887commonly used representation.
 888
 889@item @var{a}.@var{b}.@var{c}
 890The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
 891This is useful for specifying host addresses in a Class B network with
 892network address number @code{@var{a}.@var{b}}.
 893
 894@item @var{a}.@var{b}
 895The last part of the address, @var{b}, is interpreted as a 3-byte quantity.
 896This is useful for specifying host addresses in a Class A network with
 897network address number @var{a}.
 898
 899@item @var{a}
 900If only one part is given, this corresponds directly to the host address
 901number.
 902@end table
 903
 904Within each part of the address, the usual C conventions for specifying
 905the radix apply.  In other words, a leading @samp{0x} or @samp{0X} implies
 906hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
 907radix is assumed.
 908
 909@subsubheading Classless Addresses
 910
 911IPv4 addresses (and IPv6 addresses also) are now considered classless;
 912the distinction between classes A, B and C can be ignored.  Instead an
 913IPv4 host address consists of a 32-bit address and a 32-bit mask.  The
 914mask contains set bits for the network part and cleared bits for the
 915host part.  The network part is contiguous from the left, with the
 916remaining bits representing the host.  As a consequence, the netmask can
 917simply be specified as the number of set bits.  Classes A, B and C are
 918just special cases of this general rule.  For example, class A addresses
 919have a netmask of @samp{255.0.0.0} or a prefix length of 8.
 920
 921Classless IPv4 network addresses are written in numbers-and-dots
 922notation with the prefix length appended and a slash as separator.  For
 923example the class A network 10 is written as @samp{10.0.0.0/8}.
 924
 925@subsubheading IPv6 Addresses
 926
 927IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data.  A host
 928address is usually written as eight 16-bit hexadecimal numbers that are
 929separated by colons.  Two colons are used to abbreviate strings of
 930consecutive zeros.  For example, the IPv6 loopback address
 931@samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}.
 932
 933@node Host Address Data Type
 934@subsubsection Host Address Data Type
 935
 936IPv4 Internet host addresses are represented in some contexts as integers
 937(type @code{uint32_t}).  In other contexts, the integer is
 938packaged inside a structure of type @code{struct in_addr}.  It would
 939be better if the usage were made consistent, but it is not hard to extract
 940the integer from the structure or put the integer into a structure.
 941
 942You will find older code that uses @code{unsigned long int} for
 943IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct
 944in_addr}.  Historically @code{unsigned long int} was a 32-bit number but
 945with 64-bit machines this has changed.  Using @code{unsigned long int}
 946might break the code if it is used on machines where this type doesn't
 947have 32 bits.  @code{uint32_t} is specified by Unix98 and guaranteed to have
 94832 bits.
 949
 950IPv6 Internet host addresses have 128 bits and are packaged inside a
 951structure of type @code{struct in6_addr}.
 952
 953The following basic definitions for Internet addresses are declared in
 954the header file @file{netinet/in.h}:
 955@pindex netinet/in.h
 956
 957@comment netinet/in.h
 958@comment BSD
 959@deftp {Data Type} {struct in_addr}
 960This data type is used in certain contexts to contain an IPv4 Internet
 961host address.  It has just one field, named @code{s_addr}, which records
 962the host address number as an @code{uint32_t}.
 963@end deftp
 964
 965@comment netinet/in.h
 966@comment BSD
 967@deftypevr Macro {uint32_t} INADDR_LOOPBACK
 968You can use this constant to stand for ``the address of this machine,''
 969instead of finding its actual address.  It is the IPv4 Internet address
 970@samp{127.0.0.1}, which is usually called @samp{localhost}.  This
 971special constant saves you the trouble of looking up the address of your
 972own machine.  Also, the system usually implements @code{INADDR_LOOPBACK}
 973specially, avoiding any network traffic for the case of one machine
 974talking to itself.
 975@end deftypevr
 976
 977@comment netinet/in.h
 978@comment BSD
 979@deftypevr Macro {uint32_t} INADDR_ANY
 980You can use this constant to stand for ``any incoming address'' when
 981binding to an address.  @xref{Setting Address}.  This is the usual
 982address to give in the @code{sin_addr} member of @w{@code{struct
 983sockaddr_in}} when you want to accept Internet connections.
 984@end deftypevr
 985
 986@comment netinet/in.h
 987@comment BSD
 988@deftypevr Macro {uint32_t} INADDR_BROADCAST
 989This constant is the address you use to send a broadcast message.
 990@c !!! broadcast needs further documented
 991@end deftypevr
 992
 993@comment netinet/in.h
 994@comment BSD
 995@deftypevr Macro {uint32_t} INADDR_NONE
 996This constant is returned by some functions to indicate an error.
 997@end deftypevr
 998
 999@comment netinet/in.h
1000@comment IPv6 basic API
1001@deftp {Data Type} {struct in6_addr}
1002This data type is used to store an IPv6 address.  It stores 128 bits of
1003data, which can be accessed (via a union) in a variety of ways.
1004@end deftp
1005
1006@comment netinet/in.h
1007@comment IPv6 basic API
1008@deftypevr Constant {struct in6_addr} in6addr_loopback
1009This constant is the IPv6 address @samp{::1}, the loopback address.  See
1010above for a description of what this means.  The macro
1011@code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your
1012own variables to this value.
1013@end deftypevr
1014
1015@comment netinet/in.h
1016@comment IPv6 basic API
1017@deftypevr Constant {struct in6_addr} in6addr_any
1018This constant is the IPv6 address @samp{::}, the unspecified address.  See
1019above for a description of what this means.  The macro
1020@code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your
1021own variables to this value.
1022@end deftypevr
1023
1024@node Host Address Functions
1025@subsubsection Host Address Functions
1026
1027@pindex arpa/inet.h
1028@noindent
1029These additional functions for manipulating Internet addresses are
1030declared in the header file @file{arpa/inet.h}.  They represent Internet
1031addresses in network byte order, and network numbers and
1032local-address-within-network numbers in host byte order.  @xref{Byte
1033Order}, for an explanation of network and host byte order.
1034
1035@comment arpa/inet.h
1036@comment BSD
1037@deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr})
1038This function converts the IPv4 Internet host address @var{name}
1039from the standard numbers-and-dots notation into binary data and stores
1040it in the @code{struct in_addr} that @var{addr} points to.
1041@code{inet_aton} returns nonzero if the address is valid, zero if not.
1042@end deftypefun
1043
1044@comment arpa/inet.h
1045@comment BSD
1046@deftypefun {uint32_t} inet_addr (const char *@var{name})
1047This function converts the IPv4 Internet host address @var{name} from the
1048standard numbers-and-dots notation into binary data.  If the input is
1049not valid, @code{inet_addr} returns @code{INADDR_NONE}.  This is an
1050obsolete interface to @code{inet_aton}, described immediately above. It
1051is obsolete because @code{INADDR_NONE} is a valid address
1052(255.255.255.255), and @code{inet_aton} provides a cleaner way to
1053indicate error return.
1054@end deftypefun
1055
1056@comment arpa/inet.h
1057@comment BSD
1058@deftypefun {uint32_t} inet_network (const char *@var{name})
1059This function extracts the network number from the address @var{name},
1060given in the standard numbers-and-dots notation. The returned address is
1061in host order. If the input is not valid, @code{inet_network} returns
1062@code{-1}.
1063
1064The function works only with traditional IPv4 class A, B and C network
1065types.  It doesn't work with classless addresses and shouldn't be used
1066anymore.
1067@end deftypefun
1068
1069@comment arpa/inet.h
1070@comment BSD
1071@deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
1072This function converts the IPv4 Internet host address @var{addr} to a
1073string in the standard numbers-and-dots notation.  The return value is
1074a pointer into a statically-allocated buffer.  Subsequent calls will
1075overwrite the same buffer, so you should copy the string if you need
1076to save it.
1077
1078In multi-threaded programs each thread has an own statically-allocated
1079buffer.  But still subsequent calls of @code{inet_ntoa} in the same
1080thread will overwrite the result of the last call.
1081
1082Instead of @code{inet_ntoa} the newer function @code{inet_ntop} which is
1083described below should be used since it handles both IPv4 and IPv6
1084addresses.
1085@end deftypefun
1086
1087@comment arpa/inet.h
1088@comment BSD
1089@deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local})
1090This function makes an IPv4 Internet host address by combining the network
1091number @var{net} with the local-address-within-network number
1092@var{local}.
1093@end deftypefun
1094
1095@comment arpa/inet.h
1096@comment BSD
1097@deftypefun uint32_t inet_lnaof (struct in_addr @var{addr})
1098This function returns the local-address-within-network part of the
1099Internet host address @var{addr}.
1100
1101The function works only with traditional IPv4 class A, B and C network
1102types.  It doesn't work with classless addresses and shouldn't be used
1103anymore.
1104@end deftypefun
1105
1106@comment arpa/inet.h
1107@comment BSD
1108@deftypefun uint32_t inet_netof (struct in_addr @var{addr})
1109This function returns the network number part of the Internet host
1110address @var{addr}.
1111
1112The function works only with traditional IPv4 class A, B and C network
1113types.  It doesn't work with classless addresses and shouldn't be used
1114anymore.
1115@end deftypefun
1116
1117@comment arpa/inet.h
1118@comment IPv6 basic API
1119@deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf})
1120This function converts an Internet address (either IPv4 or IPv6) from
1121presentation (textual) to network (binary) format.  @var{af} should be
1122either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of
1123address being converted.  @var{cp} is a pointer to the input string, and
1124@var{buf} is a pointer to a buffer for the result.  It is the caller's
1125responsibility to make sure the buffer is large enough.
1126@end deftypefun
1127
1128@comment arpa/inet.h
1129@comment IPv6 basic API
1130@deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, size_t @var{len})
1131This function converts an Internet address (either IPv4 or IPv6) from
1132network (binary) to presentation (textual) form.  @var{af} should be
1133either @code{AF_INET} or @code{AF_INET6}, as appropriate.  @var{cp} is a
1134pointer to the address to be converted.  @var{buf} should be a pointer
1135to a buffer to hold the result, and @var{len} is the length of this
1136buffer.  The return value from the function will be this buffer address.
1137@end deftypefun
1138
1139@node Host Names
1140@subsubsection Host Names
1141@cindex hosts database
1142@cindex converting host name to address
1143@cindex converting host address to name
1144
1145Besides the standard numbers-and-dots notation for Internet addresses,
1146you can also refer to a host by a symbolic name.  The advantage of a
1147symbolic name is that it is usually easier to remember.  For example,
1148the machine with Internet address @samp{158.121.106.19} is also known as
1149@samp{alpha.gnu.org}; and other machines in the @samp{gnu.org}
1150domain can refer to it simply as @samp{alpha}.
1151
1152@pindex /etc/hosts
1153@pindex netdb.h
1154Internally, the system uses a database to keep track of the mapping
1155between host names and host numbers.  This database is usually either
1156the file @file{/etc/hosts} or an equivalent provided by a name server.
1157The functions and other symbols for accessing this database are declared
1158in @file{netdb.h}.  They are BSD features, defined unconditionally if
1159you include @file{netdb.h}.
1160
1161@comment netdb.h
1162@comment BSD
1163@deftp {Data Type} {struct hostent}
1164This data type is used to represent an entry in the hosts database.  It
1165has the following members:
1166
1167@table @code
1168@item char *h_name
1169This is the ``official'' name of the host.
1170
1171@item char **h_aliases
1172These are alternative names for the host, represented as a null-terminated
1173vector of strings.
1174
1175@item int h_addrtype
1176This is the host address type; in practice, its value is always either
1177@code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6
1178hosts.  In principle other kinds of addresses could be represented in
1179the database as well as Internet addresses; if this were done, you
1180might find a value in this field other than @code{AF_INET} or
1181@code{AF_INET6}.  @xref{Socket Addresses}.
1182
1183@item int h_length
1184This is the length, in bytes, of each address.
1185
1186@item char **h_addr_list
1187This is the vector of addresses for the host.  (Recall that the host
1188might be connected to multiple networks and have different addresses on
1189each one.)  The vector is terminated by a null pointer.
1190
1191@item char *h_addr
1192This is a synonym for @code{h_addr_list[0]}; in other words, it is the
1193first host address.
1194@end table
1195@end deftp
1196
1197As far as the host database is concerned, each address is just a block
1198of memory @code{h_length} bytes long.  But in other contexts there is an
1199implicit assumption that you can convert IPv4 addresses to a
1200@code{struct in_addr} or an @code{uint32_t}.  Host addresses in
1201a @code{struct hostent} structure are always given in network byte
1202order; see @ref{Byte Order}.
1203
1204You can use @code{gethostbyname}, @code{gethostbyname2} or
1205@code{gethostbyaddr} to search the hosts database for information about
1206a particular host.  The information is returned in a
1207statically-allocated structure; you must copy the information if you
1208need to save it across calls.  You can also use @code{getaddrinfo} and
1209@code{getnameinfo} to obtain this information.
1210
1211@comment netdb.h
1212@comment BSD
1213@deftypefun {struct hostent *} gethostbyname (const char *@var{name})
1214The @code{gethostbyname} function returns information about the host
1215named @var{name}.  If the lookup fails, it returns a null pointer.
1216@end deftypefun
1217
1218@comment netdb.h
1219@comment IPv6 Basic API
1220@deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
1221The @code{gethostbyname2} function is like @code{gethostbyname}, but
1222allows the caller to specify the desired address family (e.g.@:
1223@code{AF_INET} or @code{AF_INET6}) of the result.
1224@end deftypefun
1225
1226@comment netdb.h
1227@comment BSD
1228@deftypefun {struct hostent *} gethostbyaddr (const char *@var{addr}, size_t @var{length}, int @var{format})
1229The @code{gethostbyaddr} function returns information about the host
1230with Internet address @var{addr}.  The parameter @var{addr} is not
1231really a pointer to char - it can be a pointer to an IPv4 or an IPv6
1232address. The @var{length} argument is the size (in bytes) of the address
1233at @var{addr}.  @var{format} specifies the address format; for an IPv4
1234Internet address, specify a value of @code{AF_INET}; for an IPv6
1235Internet address, use @code{AF_INET6}.
1236
1237If the lookup fails, @code{gethostbyaddr} returns a null pointer.
1238@end deftypefun
1239
1240@vindex h_errno
1241If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
1242fails, you can find out the reason by looking at the value of the
1243variable @code{h_errno}.  (It would be cleaner design for these
1244functions to set @code{errno}, but use of @code{h_errno} is compatible
1245with other systems.)
1246
1247Here are the error codes that you may find in @code{h_errno}:
1248
1249@table @code
1250@comment netdb.h
1251@comment BSD
1252@item HOST_NOT_FOUND
1253@vindex HOST_NOT_FOUND
1254No such host is known in the database.
1255
1256@comment netdb.h
1257@comment BSD
1258@item TRY_AGAIN
1259@vindex TRY_AGAIN
1260This condition happens when the name server could not be contacted.  If
1261you try again later, you may succeed then.
1262
1263@comment netdb.h
1264@comment BSD
1265@item NO_RECOVERY
1266@vindex NO_RECOVERY
1267A non-recoverable error occurred.
1268
1269@comment netdb.h
1270@comment BSD
1271@item NO_ADDRESS
1272@vindex NO_ADDRESS
1273The host database contains an entry for the name, but it doesn't have an
1274associated Internet address.
1275@end table
1276
1277The lookup functions above all have one in common: they are not
1278reentrant and therefore unusable in multi-threaded applications.
1279Therefore provides the GNU C library a new set of functions which can be
1280used in this context.
1281
1282@comment netdb.h
1283@comment GNU
1284@deftypefun int gethostbyname_r (const char *restrict @var{name}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop})
1285The @code{gethos…

Large files files are truncated, but you can click here to view the full file