diff options
Diffstat (limited to 'manual/socket.texi')
| -rw-r--r-- | manual/socket.texi | 3761 |
1 files changed, 0 insertions, 3761 deletions
diff --git a/manual/socket.texi b/manual/socket.texi deleted file mode 100644 index 21b672badc..0000000000 --- a/manual/socket.texi +++ /dev/null @@ -1,3761 +0,0 @@ -@node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top -@c %MENU% A more complicated IPC mechanism, with networking support -@chapter Sockets - -This chapter describes the GNU facilities for interprocess -communication using sockets. - -@cindex socket -@cindex interprocess communication, with sockets -A @dfn{socket} is a generalized interprocess communication channel. -Like a pipe, a socket is represented as a file descriptor. 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{rlogin}, @code{ftp}, @code{talk} and the -other familiar network programs use sockets. - -Not all operating systems support sockets. In @theglibc{}, the -header file @file{sys/socket.h} 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. - -@strong{Incomplete:} We do not currently document the facilities for -broadcast messages or for configuring Internet interfaces. The -reentrant functions and some newer functions that are related to IPv6 -aren't documented either so far. - -@menu -* Socket Concepts:: Basic concepts you need to know about. -* Communication Styles::Stream communication, datagrams and other styles. -* Socket Addresses:: How socket names (``addresses'') work. -* Interface Naming:: Identifying specific network interfaces. -* Local Namespace:: Details about the local namespace. -* Internet Namespace:: Details about the Internet namespace. -* Misc Namespaces:: Other namespaces not documented fully here. -* Open/Close Sockets:: Creating sockets and destroying them. -* Connections:: Operations on sockets with connection state. -* Datagrams:: Operations on datagram sockets. -* Inetd:: Inetd is a daemon that starts servers on request. - The most convenient way to write a server - is to make it work with Inetd. -* Socket Options:: Miscellaneous low-level socket options. -* Networks Database:: Accessing the database of network names. -@end menu - -@node Socket Concepts -@section Socket Concepts - -@cindex communication style (of a socket) -@cindex style of communication (of a socket) -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} 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: - -@itemize @bullet -@item -@cindex packet -@cindex byte stream -@cindex stream (sockets) -@strong{What are the units of data transmission?} 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}). - -@item -@cindex loss of data on sockets -@cindex data loss on sockets -@strong{Can data be lost during normal operation?} Some communication -styles guarantee that all the data sent arrives in the order it was -sent (barring system or network crashes); other styles occasionally -lose data as a normal part of operation, and may sometimes deliver -packets more than once or in the wrong order. - -Designing a program to use unreliable communication styles usually -involves taking precautions to detect lost or misordered packets and -to retransmit data as needed. - -@item -@strong{Is communication entirely with one partner?} Some -communication styles are like a telephone call---you make a -@dfn{connection} 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. -@end itemize - -@cindex namespace (of socket) -@cindex domain (of socket) -@cindex socket namespace -@cindex socket domain -You must also choose a @dfn{namespace} 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_}. -A corresponding symbolic name starting with @samp{AF_} designates the -address format for that namespace. - -@cindex network protocol -@cindex protocol (of socket) -@cindex socket protocol -@cindex protocol family -Finally you must choose the @dfn{protocol} 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} because of this, which is why the namespace names -start with @samp{PF_}. - -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: - -@itemize @bullet -@item -In order to have communication between two sockets, they must specify -the @emph{same} protocol. - -@item -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. - -@item -For each combination of style and namespace there is a @dfn{default -protocol}, which you can request by specifying 0 as the protocol -number. And that's what you should normally do---use the default. -@end itemize - -Throughout the following description at various places -variables/parameters to denote sizes are required. And here the trouble -starts. In the first implementations the type of these variables was -simply @code{int}. On most machines at that time an @code{int} was 32 -bits wide, which created a @emph{de facto} standard requiring 32-bit -variables. This is important since references to variables of this type -are passed to the kernel. - -Then the POSIX people came and unified the interface with the words "all -size values are of type @code{size_t}". On 64-bit machines -@code{size_t} is 64 bits wide, so pointers to variables were no longer -possible. - -The Unix98 specification provides a solution by introducing a type -@code{socklen_t}. This type is used in all of the cases that POSIX -changed to use @code{size_t}. The only requirement of this type is that -it be an unsigned type of at least 32 bits. Therefore, implementations -which require that references to 32-bit variables be passed can be as -happy as implementations which use 64-bit values. - - -@node Communication Styles -@section Communication Styles - -@Theglibc{} 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 @file{sys/socket.h}. -@pindex sys/socket.h - -@comment sys/socket.h -@comment BSD -@deftypevr Macro int SOCK_STREAM -The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}). -It operates over a connection with a particular remote socket and -transmits data reliably as a stream of bytes. - -Use of this style is covered in detail in @ref{Connections}. -@end deftypevr - -@comment sys/socket.h -@comment BSD -@deftypevr Macro int SOCK_DGRAM -The @code{SOCK_DGRAM} style is used for sending -individually-addressed packets unreliably. -It is the diametrical opposite of @code{SOCK_STREAM}. - -Each time you write data to a socket of this kind, that data becomes -one packet. Since @code{SOCK_DGRAM} sockets do not have connections, -you must specify the recipient address with each packet. - -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. - -The typical use for @code{SOCK_DGRAM} is in situations where it is -acceptable to simply re-send a packet if no response is seen in a -reasonable amount of time. - -@xref{Datagrams}, for detailed information about how to use datagram -sockets. -@end deftypevr - -@ignore -@c This appears to be only for the NS domain, which we aren't -@c discussing and probably won't support either. -@comment sys/socket.h -@comment BSD -@deftypevr Macro int SOCK_SEQPACKET -This style is like @code{SOCK_STREAM} except that the data are -structured into packets. - -A program that receives data over a @code{SOCK_SEQPACKET} socket -should be prepared to read the entire message packet in a single call -to @code{read}; if it only reads part of the message, the remainder of -the message is simply discarded instead of being available for -subsequent calls to @code{read}. - -Many protocols do not support this communication style. -@end deftypevr -@end ignore - -@ignore -@comment sys/socket.h -@comment BSD -@deftypevr Macro int SOCK_RDM -This style is a reliable version of @code{SOCK_DGRAM}: it sends -individually addressed packets, but guarantees that each packet sent -arrives exactly once. - -@strong{Warning:} It is not clear this is actually supported -by any operating system. -@end deftypevr -@end ignore - -@comment sys/socket.h -@comment BSD -@deftypevr Macro int SOCK_RAW -This style provides access to low-level network protocols and -interfaces. Ordinary user programs usually have no need to use this -style. -@end deftypevr - -@node Socket Addresses -@section Socket Addresses - -@cindex address of socket -@cindex name of socket -@cindex binding a socket address -@cindex socket address (name) binding -The name of a socket is normally called an @dfn{address}. 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. - -A socket newly created with the @code{socket} function has no -address. Other processes can find it for communication only if you -give it an address. We call this @dfn{binding} the address to the -socket, and the way to do it is with the @code{bind} function. - -You need only 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. - -Occasionally a client needs to specify an address because the server -discriminates based on address; for example, the rsh and rlogin -protocols look at the client's socket address and only bypass password -checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}). - -The details of socket addresses vary depending on what namespace you are -using. @xref{Local Namespace}, or @ref{Internet Namespace}, for specific -information. - -Regardless of the namespace, you use the same functions @code{bind} and -@code{getsockname} to set and examine a socket's address. These -functions use a phony data type, @code{struct sockaddr *}, 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 *} when you pass it to -@code{bind}. - -@menu -* Address Formats:: About @code{struct sockaddr}. -* Setting Address:: Binding an address to a socket. -* Reading Address:: Reading the address of a socket. -@end menu - -@node Address Formats -@subsection Address Formats - -The functions @code{bind} and @code{getsockname} use the generic data -type @code{struct sockaddr *} 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. - -Thus, the usual practice is to construct an address of the proper -namespace-specific type, then cast a pointer to @code{struct sockaddr *} -when you call @code{bind} or @code{getsockname}. - -The one piece of information that you can get from the @code{struct -sockaddr} data type is the @dfn{address format designator}. This tells -you which data type to use to understand the address fully. - -@pindex sys/socket.h -The symbols in this section are defined in the header file -@file{sys/socket.h}. - -@comment sys/socket.h -@comment BSD -@deftp {Data Type} {struct sockaddr} -The @code{struct sockaddr} type itself has the following members: - -@table @code -@item short int sa_family -This is the code for the address format of this address. It -identifies the format of the data which follows. - -@item char sa_data[14] -This is the actual socket address data, which is format-dependent. Its -length also depends on the format, and may well be more than 14. The -length 14 of @code{sa_data} is essentially arbitrary. -@end table -@end deftp - -Each address format has a symbolic name which starts with @samp{AF_}. -Each of them corresponds to a @samp{PF_} symbol which designates the -corresponding namespace. Here is a list of address format names: - -@vtable @code -@comment sys/socket.h -@comment POSIX -@item AF_LOCAL -This designates the address format that goes with the local namespace. -(@code{PF_LOCAL} is the name of that namespace.) @xref{Local Namespace -Details}, for information about this address format. - -@comment sys/socket.h -@comment BSD, Unix98 -@item AF_UNIX -This is a synonym for @code{AF_LOCAL}. Although @code{AF_LOCAL} is -mandated by POSIX.1g, @code{AF_UNIX} is portable to more systems. -@code{AF_UNIX} was the traditional name stemming from BSD, so even most -POSIX systems support it. It is also the name of choice in the Unix98 -specification. (The same is true for @code{PF_UNIX} -vs. @code{PF_LOCAL}). - -@comment sys/socket.h -@comment GNU -@item AF_FILE -This is another synonym for @code{AF_LOCAL}, for compatibility. -(@code{PF_FILE} is likewise a synonym for @code{PF_LOCAL}.) - -@comment sys/socket.h -@comment BSD -@item AF_INET -This designates the address format that goes with the Internet -namespace. (@code{PF_INET} is the name of that namespace.) -@xref{Internet Address Formats}. - -@comment sys/socket.h -@comment IPv6 Basic API -@item AF_INET6 -This is similar to @code{AF_INET}, but refers to the IPv6 protocol. -(@code{PF_INET6} is the name of the corresponding namespace.) - -@comment sys/socket.h -@comment BSD -@item AF_UNSPEC -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. @xref{Sending Datagrams}. - -The corresponding namespace designator symbol @code{PF_UNSPEC} exists -for completeness, but there is no reason to use it in a program. -@end vtable - -@file{sys/socket.h} defines symbols starting with @samp{AF_} for many -different kinds of networks, most or all of which are not actually -implemented. We will document those that really work as we receive -information about how to use them. - -@node Setting Address -@subsection Setting the Address of a Socket - -@pindex sys/socket.h -Use the @code{bind} function to assign an address to a socket. The -prototype for @code{bind} is in the header file @file{sys/socket.h}. -For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}. - -@comment sys/socket.h -@comment BSD -@deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Direct syscall, except on Hurd. -The @code{bind} function assigns an address to the socket -@var{socket}. The @var{addr} and @var{length} arguments specify the -address; the detailed format of the address depends on the namespace. -The first part of the address is always the format designator, which -specifies a namespace, and says that the address is in the format of -that namespace. - -The return value is @code{0} on success and @code{-1} on failure. The -following @code{errno} error conditions are defined for this function: - -@table @code -@item EBADF -The @var{socket} argument is not a valid file descriptor. - -@item ENOTSOCK -The descriptor @var{socket} is not a socket. - -@item EADDRNOTAVAIL -The specified address is not available on this machine. - -@item EADDRINUSE -Some other socket is already using the specified address. - -@item EINVAL -The socket @var{socket} already has an address. - -@item EACCES -You do not have permission to access the requested address. (In the -Internet domain, only the super-user is allowed to specify a port number -in the range 0 through @code{IPPORT_RESERVED} minus one; see -@ref{Ports}.) -@end table - -Additional conditions may be possible depending on the particular namespace -of the socket. -@end deftypefun - -@node Reading Address -@subsection Reading the Address of a Socket - -@pindex sys/socket.h -Use the function @code{getsockname} to examine the address of an -Internet socket. The prototype for this function is in the header file -@file{sys/socket.h}. - -@comment sys/socket.h -@comment BSD -@deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsmem{/hurd}}} -@c Direct syscall, except on Hurd, where it seems like it might leak -@c VM if cancelled. -The @code{getsockname} function returns information about the -address of the socket @var{socket} in the locations specified by the -@var{addr} and @var{length-ptr} arguments. Note that the -@var{length-ptr} is a pointer; you should initialize it to be the -allocation size of @var{addr}, and on return it contains the actual -size of the address data. - -The format of the address data depends on the socket namespace. The -length of the information is usually fixed for a given namespace, so -normally you can know exactly how much space is needed and can provide -that much. The usual practice is to allocate a place for the value -using the proper data type for the socket's namespace, then cast its -address to @code{struct sockaddr *} to pass it to @code{getsockname}. - -The return value is @code{0} on success and @code{-1} on error. The -following @code{errno} error conditions are defined for this function: - -@table @code -@item EBADF -The @var{socket} argument is not a valid file descriptor. - -@item ENOTSOCK -The descriptor @var{socket} is not a socket. - -@item ENOBUFS -There are not enough internal buffers available for the operation. -@end table -@end deftypefun - -You can't read the address of a socket in the file namespace. This is -consistent with the rest of the system; in general, there's no way to -find a file's name from a descriptor for that file. - -@node Interface Naming -@section Interface Naming - -Each network interface has a name. This usually consists of a few -letters that relate to the type of interface, which may be followed by a -number if there is more than one interface of that type. Examples -might be @code{lo} (the loopback interface) and @code{eth0} (the first -Ethernet interface). - -Although such names are convenient for humans, it would be clumsy to -have to use them whenever a program needs to refer to an interface. In -such situations an interface is referred to by its @dfn{index}, which is -an arbitrarily-assigned small positive integer. - -The following functions, constants and data types are declared in the -header file @file{net/if.h}. - -@comment net/if.h -@deftypevr Constant size_t IFNAMSIZ -This constant defines the maximum buffer size needed to hold an -interface name, including its terminating zero byte. -@end deftypevr - -@comment net/if.h -@comment IPv6 basic API -@deftypefun {unsigned int} if_nametoindex (const char *@var{ifname}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} -@c It opens a socket to use ioctl on the fd to get the index. -@c opensock may call socket and access multiple times until it finds a -@c socket family that works. The Linux implementation has a potential -@c concurrency issue WRT last_type and last_family not being updated -@c atomically, but it is harmless; the generic implementation, OTOH, -@c takes a lock, which makes all callers AS- and AC-Unsafe. -@c opensock @asulock @aculock @acsfd -This function yields the interface index corresponding to a particular -name. If no interface exists with the name given, it returns 0. -@end deftypefun - -@comment net/if.h -@comment IPv6 basic API -@deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} -@c It opens a socket with opensock to use ioctl on the fd to get the -@c name from the index. -This function maps an interface index to its corresponding name. The -returned name is placed in the buffer pointed to by @code{ifname}, which -must be at least @code{IFNAMSIZ} bytes in length. If the index was -invalid, the function's return value is a null pointer, otherwise it is -@code{ifname}. -@end deftypefun - -@comment net/if.h -@comment IPv6 basic API -@deftp {Data Type} {struct if_nameindex} -This data type is used to hold the information about a single -interface. It has the following members: - -@table @code -@item unsigned int if_index; -This is the interface index. - -@item char *if_name -This is the null-terminated index name. - -@end table -@end deftp - -@comment net/if.h -@comment IPv6 basic API -@deftypefun {struct if_nameindex *} if_nameindex (void) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@aculock{/hurd} @acsfd{} @acsmem{}}} -@c if_nameindex @ascuheap @asulock/hurd @aculock/hurd @acsfd @acsmem -@c [linux] -@c netlink_open @acsfd @acsmem/hurd -@c socket dup @acsfd -@c memset dup ok -@c bind dup ok -@c netlink_close dup @acsfd -@c getsockname dup @acsmem/hurd -@c netlink_request @ascuheap @acsmem -@c getpagesize dup ok -@c malloc dup @ascuheap @acsmem -@c netlink_sendreq ok -@c memset dup ok -@c sendto dup ok -@c recvmsg dup ok -@c memcpy dup ok -@c free dup @ascuheap @acsmem -@c netlink_free_handle @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c netlink_close @acsfd -@c close dup @acsfd -@c malloc dup @asuheap @acsmem -@c strndup @ascuheap @acsmem -@c if_freenameindex @ascuheap @acsmem -@c [hurd] -@c opensock dup @asulock @aculock @acsfd -@c hurd_socket_server ok -@c pfinet_siocgifconf ok -@c malloc @ascuheap @acsmem -@c strdup @ascuheap @acsmem -@c ioctl dup ok -@c free @ascuheap @acsmem -This function returns an array of @code{if_nameindex} structures, one -for every interface that is present. The end of the list is indicated -by a structure with an interface of 0 and a null name pointer. If an -error occurs, this function returns a null pointer. - -The returned structure must be freed with @code{if_freenameindex} after -use. -@end deftypefun - -@comment net/if.h -@comment IPv6 basic API -@deftypefun void if_freenameindex (struct if_nameindex *@var{ptr}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -@c if_freenameindex @ascuheap @acsmem -@c free dup @ascuheap @acsmem -This function frees the structure returned by an earlier call to -@code{if_nameindex}. -@end deftypefun - -@node Local Namespace -@section The Local Namespace -@cindex local namespace, for sockets - -This section describes the details of the local namespace, whose -symbolic name (required when you create a socket) is @code{PF_LOCAL}. -The local namespace is also known as ``Unix domain sockets''. Another -name is file namespace since socket addresses are normally implemented -as file names. - -@menu -* Concepts: Local Namespace Concepts. What you need to understand. -* Details: Local Namespace Details. Address format, symbolic names, etc. -* Example: Local Socket Example. Example of creating a socket. -@end menu - -@node Local Namespace Concepts -@subsection Local Namespace Concepts - -In the local namespace socket addresses are file names. You can specify -any file name you want as the address of the socket, but you must have -write permission on the directory containing it. -@c XXX The following was said to be wrong. -@c In order to connect to a socket you must have read permission for it. -It's common to put these files in the @file{/tmp} directory. - -One peculiarity of the local namespace is that the name is only used -when opening the connection; once open the address is not meaningful and -may not exist. - -Another peculiarity is that you cannot connect to such a socket from -another machine--not even if the other machine shares the file system -which contains the name of the socket. You can see the socket in a -directory listing, but connecting to it never succeeds. Some programs -take advantage of this, such as by asking the client to send its own -process ID, and using the process IDs to distinguish between clients. -However, we recommend you not use this method in protocols you design, -as we might someday permit connections from other machines that mount -the same file systems. Instead, send each new client an identifying -number if you want it to have one. - -After you close a socket in the local namespace, you should delete the -file name from the file system. Use @code{unlink} or @code{remove} to -do this; see @ref{Deleting Files}. - -The local namespace supports just one protocol for any communication -style; it is protocol number @code{0}. - -@node Local Namespace Details -@subsection Details of Local Namespace - -@pindex sys/socket.h -To create a socket in the local namespace, use the constant -@code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or -@code{socketpair}. This constant is defined in @file{sys/socket.h}. - -@comment sys/socket.h -@comment POSIX -@deftypevr Macro int PF_LOCAL -This designates the local namespace, in which socket addresses are local -names, and its associated family of protocols. @code{PF_LOCAL} is the -macro used by POSIX.1g. -@end deftypevr - -@comment sys/socket.h -@comment BSD -@deftypevr Macro int PF_UNIX -This is a synonym for @code{PF_LOCAL}, for compatibility's sake. -@end deftypevr - -@comment sys/socket.h -@comment GNU -@deftypevr Macro int PF_FILE -This is a synonym for @code{PF_LOCAL}, for compatibility's sake. -@end deftypevr - -The structure for specifying socket names in the local namespace is -defined in the header file @file{sys/un.h}: -@pindex sys/un.h - -@comment sys/un.h -@comment BSD -@deftp {Data Type} {struct sockaddr_un} -This structure is used to specify local namespace socket addresses. It has -the following members: - -@table @code -@item short int sun_family -This identifies the address family or format of the socket address. -You should store the value @code{AF_LOCAL} to designate the local -namespace. @xref{Socket Addresses}. - -@item char sun_path[108] -This is the file name to use. - -@strong{Incomplete:} Why is 108 a magic number? RMS suggests making -this a zero-length array and tweaking the following example to use -@code{alloca} to allocate an appropriate amount of storage based on -the length of the filename. -@end table -@end deftp - -You should compute the @var{length} parameter for a socket address in -the local namespace as the sum of the size of the @code{sun_family} -component and the string length (@emph{not} the allocation size!) of -the file name string. This can be done using the macro @code{SUN_LEN}: - -@comment sys/un.h -@comment BSD -@deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This macro computes the length of the socket address in the local namespace. -@end deftypefn - -@node Local Socket Example -@subsection Example of Local-Namespace Sockets - -Here is an example showing how to create and name a socket in the local -namespace. - -@smallexample -@include mkfsock.c.texi -@end smallexample - -@node Internet Namespace -@section The Internet Namespace -@cindex Internet namespace, for sockets - -This section describes the details of the protocols and socket naming -conventions used in the Internet namespace. - -Originally the Internet namespace used only IP version 4 (IPv4). With -the growing number of hosts on the Internet, a new protocol with a -larger address space was necessary: IP version 6 (IPv6). IPv6 -introduces 128-bit addresses (IPv4 has 32-bit addresses) and other -features, and will eventually replace IPv4. - -To create a socket in the IPv4 Internet namespace, use the symbolic name -@code{PF_INET} of this namespace as the @var{namespace} argument to -@code{socket} or @code{socketpair}. For IPv6 addresses you need the -macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}. -@pindex sys/socket.h - -@comment sys/socket.h -@comment BSD -@deftypevr Macro int PF_INET -This designates the IPv4 Internet namespace and associated family of -protocols. -@end deftypevr - -@comment sys/socket.h -@comment X/Open -@deftypevr Macro int PF_INET6 -This designates the IPv6 Internet namespace and associated family of -protocols. -@end deftypevr - -A socket address for the Internet namespace includes the following components: - -@itemize @bullet -@item -The address of the machine you want to connect to. Internet addresses -can be specified in several ways; these are discussed in @ref{Internet -Address Formats}, @ref{Host Addresses} and @ref{Host Names}. - -@item -A port number for that machine. @xref{Ports}. -@end itemize - -You must ensure that the address and port number are represented in a -canonical format called @dfn{network byte order}. @xref{Byte Order}, -for information about this. - -@menu -* Internet Address Formats:: How socket addresses are specified in the - Internet namespace. -* Host Addresses:: All about host addresses of Internet host. -* Ports:: Internet port numbers. -* Services Database:: Ports may have symbolic names. -* Byte Order:: Different hosts may use different byte - ordering conventions; you need to - canonicalize host address and port number. -* Protocols Database:: Referring to protocols by name. -* Inet Example:: Putting it all together. -@end menu - -@node Internet Address Formats -@subsection Internet Socket Address Formats - -In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6 -(@code{AF_INET6}), a socket address consists of a host address -and a port on that host. In addition, the protocol you choose serves -effectively as a part of the address because local port numbers are -meaningful only within a particular protocol. - -The data types for representing socket addresses in the Internet namespace -are defined in the header file @file{netinet/in.h}. -@pindex netinet/in.h - -@comment netinet/in.h -@comment BSD -@deftp {Data Type} {struct sockaddr_in} -This is the data type used to represent socket addresses in the -Internet namespace. It has the following members: - -@table @code -@item sa_family_t sin_family -This identifies the address family or format of the socket address. -You should store the value @code{AF_INET} in this member. -@xref{Socket Addresses}. - -@item struct in_addr sin_addr -This is the Internet address of the host machine. @xref{Host -Addresses}, and @ref{Host Names}, for how to get a value to store -here. - -@item unsigned short int sin_port -This is the port number. @xref{Ports}. -@end table -@end deftp - -When you call @code{bind} or @code{getsockname}, you should specify -@code{sizeof (struct sockaddr_in)} as the @var{length} parameter if -you are using an IPv4 Internet namespace socket address. - -@deftp {Data Type} {struct sockaddr_in6} -This is the data type used to represent socket addresses in the IPv6 -namespace. It has the following members: - -@table @code -@item sa_family_t sin6_family -This identifies the address family or format of the socket address. -You should store the value of @code{AF_INET6} in this member. -@xref{Socket Addresses}. - -@item struct in6_addr sin6_addr -This is the IPv6 address of the host machine. @xref{Host -Addresses}, and @ref{Host Names}, for how to get a value to store -here. - -@item uint32_t sin6_flowinfo -This is a currently unimplemented field. - -@item uint16_t sin6_port -This is the port number. @xref{Ports}. - -@end table -@end deftp - -@node Host Addresses -@subsection Host Addresses - -Each computer on the Internet has one or more @dfn{Internet addresses}, -numbers which identify that computer among all those on the Internet. -Users typically write IPv4 numeric host addresses as sequences of four -numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6 -numeric host addresses as sequences of up to eight numbers separated by -colons, as in @samp{5f03:1200:836f:c100::1}. - -Each computer also has one or more @dfn{host names}, which are strings -of words separated by periods, as in @samp{www.gnu.org}. - -Programs that let the user specify a host typically accept both numeric -addresses and host names. To open a connection a program needs a -numeric address, and so must convert a host name to the numeric address -it stands for. - -@menu -* Abstract Host Addresses:: What a host number consists of. -* Data type: Host Address Data Type. Data type for a host number. -* Functions: Host Address Functions. Functions to operate on them. -* Names: Host Names. Translating host names to host numbers. -@end menu - -@node Abstract Host Addresses -@subsubsection Internet Host Addresses -@cindex host address, Internet -@cindex Internet host address - -@ifinfo -Each computer on the Internet has one or more Internet addresses, -numbers which identify that computer among all those on the Internet. -@end ifinfo - -@cindex network number -@cindex local network address number -An IPv4 Internet host address is a number containing four bytes of data. -Historically these are divided into two parts, a @dfn{network number} and a -@dfn{local network address number} within that network. In the -mid-1990s classless addresses were introduced which changed this -behavior. Since some functions implicitly expect the old definitions, -we first describe the class-based network and will then describe -classless addresses. IPv6 uses only classless addresses and therefore -the following paragraphs don't apply. - -The class-based IPv4 network number consists of the first one, two or -three bytes; the rest of the bytes are the local address. - -IPv4 network numbers are registered with the Network Information Center -(NIC), and are divided into three classes---A, B and C. The local -network address numbers of individual machines are registered with the -administrator of the particular network. - -Class A networks have single-byte numbers in the range 0 to 127. There -are only a small number of Class A networks, but they can each support a -very large number of hosts. Medium-sized Class B networks have two-byte -network numbers, with the first byte in the range 128 to 191. Class C -networks are the smallest; they have three-byte network numbers, with -the first byte in the range 192-255. Thus, the first 1, 2, or 3 bytes -of an Internet address specify a network. The remaining bytes of the -Internet address specify the address within that network. - -The Class A network 0 is reserved for broadcast to all networks. In -addition, the host number 0 within each network is reserved for broadcast -to all hosts in that network. These uses are obsolete now but for -compatibility reasons you shouldn't use network 0 and host number 0. - -The Class A network 127 is reserved for loopback; you can always use -the Internet address @samp{127.0.0.1} to refer to the host machine. - -Since a single machine can be a member of multiple networks, it can -have multiple Internet host addresses. However, there is never -supposed to be more than one machine with the same host address. - -@c !!! this section could document the IN_CLASS* macros in <netinet/in.h>. -@c No, it shouldn't since they're obsolete. - -@cindex standard dot notation, for Internet addresses -@cindex dot notation, for Internet addresses -There are four forms of the @dfn{standard numbers-and-dots notation} -for Internet addresses: - -@table @code -@item @var{a}.@var{b}.@var{c}.@var{d} -This specifies all four bytes of the address individually and is the -commonly used representation. - -@item @var{a}.@var{b}.@var{c} -The last part of the address, @var{c}, is interpreted as a 2-byte quantity. -This is useful for specifying host addresses in a Class B network with -network address number @code{@var{a}.@var{b}}. - -@item @var{a}.@var{b} -The last part of the address, @var{b}, is interpreted as a 3-byte quantity. -This is useful for specifying host addresses in a Class A network with -network address number @var{a}. - -@item @var{a} -If only one part is given, this corresponds directly to the host address -number. -@end table - -Within each part of the address, the usual C conventions for specifying -the radix apply. In other words, a leading @samp{0x} or @samp{0X} implies -hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal -radix is assumed. - -@subsubheading Classless Addresses - -IPv4 addresses (and IPv6 addresses also) are now considered classless; -the distinction between classes A, B and C can be ignored. Instead an -IPv4 host address consists of a 32-bit address and a 32-bit mask. The -mask contains set bits for the network part and cleared bits for the -host part. The network part is contiguous from the left, with the -remaining bits representing the host. As a consequence, the netmask can -simply be specified as the number of set bits. Classes A, B and C are -just special cases of this general rule. For example, class A addresses -have a netmask of @samp{255.0.0.0} or a prefix length of 8. - -Classless IPv4 network addresses are written in numbers-and-dots -notation with the prefix length appended and a slash as separator. For -example the class A network 10 is written as @samp{10.0.0.0/8}. - -@subsubheading IPv6 Addresses - -IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data. A host -address is usually written as eight 16-bit hexadecimal numbers that are -separated by colons. Two colons are used to abbreviate strings of -consecutive zeros. For example, the IPv6 loopback address -@samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}. - -@node Host Address Data Type -@subsubsection Host Address Data Type - -IPv4 Internet host addresses are represented in some contexts as integers -(type @code{uint32_t}). In other contexts, the integer is -packaged inside a structure of type @code{struct in_addr}. It would -be better if the usage were made consistent, but it is not hard to extract -the integer from the structure or put the integer into a structure. - -You will find older code that uses @code{unsigned long int} for -IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct -in_addr}. Historically @code{unsigned long int} was a 32-bit number but -with 64-bit machines this has changed. Using @code{unsigned long int} -might break the code if it is used on machines where this type doesn't -have 32 bits. @code{uint32_t} is specified by Unix98 and guaranteed to have -32 bits. - -IPv6 Internet host addresses have 128 bits and are packaged inside a -structure of type @code{struct in6_addr}. - -The following basic definitions for Internet addresses are declared in -the header file @file{netinet/in.h}: -@pindex netinet/in.h - -@comment netinet/in.h -@comment BSD -@deftp {Data Type} {struct in_addr} -This data type is used in certain contexts to contain an IPv4 Internet -host address. It has just one field, named @code{s_addr}, which records -the host address number as an @code{uint32_t}. -@end deftp - -@comment netinet/in.h -@comment BSD -@deftypevr Macro {uint32_t} INADDR_LOOPBACK -You can use this constant to stand for ``the address of this machine,'' -instead of finding its actual address. It is the IPv4 Internet address -@samp{127.0.0.1}, which is usually called @samp{localhost}. This -special constant saves you the trouble of looking up the address of your -own machine. Also, the system usually implements @code{INADDR_LOOPBACK} -specially, avoiding any network traffic for the case of one machine -talking to itself. -@end deftypevr - -@comment netinet/in.h -@comment BSD -@deftypevr Macro {uint32_t} INADDR_ANY -You can use this constant to stand for ``any incoming address'' when -binding to an address. @xref{Setting Address}. This is the usual -address to give in the @code{sin_addr} member of @w{@code{struct -sockaddr_in}} when you want to accept Internet connections. -@end deftypevr - -@comment netinet/in.h -@comment BSD -@deftypevr Macro {uint32_t} INADDR_BROADCAST -This constant is the address you use to send a broadcast message. -@c !!! broadcast needs further documented -@end deftypevr - -@comment netinet/in.h -@comment BSD -@deftypevr Macro {uint32_t} INADDR_NONE -This constant is returned by some functions to indicate an error. -@end deftypevr - -@comment netinet/in.h -@comment IPv6 basic API -@deftp {Data Type} {struct in6_addr} -This data type is used to store an IPv6 address. It stores 128 bits of -data, which can be accessed (via a union) in a variety of ways. -@end deftp - -@comment netinet/in.h -@comment IPv6 basic API -@deftypevr Constant {struct in6_addr} in6addr_loopback -This constant is the IPv6 address @samp{::1}, the loopback address. See -above for a description of what this means. The macro -@code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your -own variables to this value. -@end deftypevr - -@comment netinet/in.h -@comment IPv6 basic API -@deftypevr Constant {struct in6_addr} in6addr_any -This constant is the IPv6 address @samp{::}, the unspecified address. See -above for a description of what this means. The macro -@code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your -own variables to this value. -@end deftypevr - -@node Host Address Functions -@subsubsection Host Address Functions - -@pindex arpa/inet.h -@noindent -These additional functions for manipulating Internet addresses are -declared in the header file @file{arpa/inet.h}. They represent Internet -addresses in network byte order, and network numbers and -local-address-within-network numbers in host byte order. @xref{Byte -Order}, for an explanation of network and host byte order. - -@comment arpa/inet.h -@comment BSD -@deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} -@c inet_aton @mtslocale -@c isdigit dup @mtslocale -@c strtoul dup @mtslocale -@c isascii dup @mtslocale -@c isspace dup @mtslocale -@c htonl dup ok -This function converts the IPv4 Internet host address @var{name} -from the standard numbers-and-dots notation into binary data and stores -it in the @code{struct in_addr} that @var{addr} points to. -@code{inet_aton} returns nonzero if the address is valid, zero if not. -@end deftypefun - -@comment arpa/inet.h -@comment BSD -@deftypefun {uint32_t} inet_addr (const char *@var{name}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} -@c inet_addr @mtslocale -@c inet_aton dup @mtslocale -This function converts the IPv4 Internet host address @var{name} from the -standard numbers-and-dots notation into binary data. If the input is -not valid, @code{inet_addr} returns @code{INADDR_NONE}. This is an -obsolete interface to @code{inet_aton}, described immediately above. It -is obsolete because @code{INADDR_NONE} is a valid address -(255.255.255.255), and @code{inet_aton} provides a cleaner way to -indicate error return. -@end deftypefun - -@comment arpa/inet.h -@comment BSD -@deftypefun {uint32_t} inet_network (const char *@var{name}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} -@c inet_network @mtslocale -@c isdigit dup @mtslocale -@c isxdigit dup @mtslocale -@c tolower dup @mtslocale -@c isspace dup @mtslocale -This function extracts the network number from the address @var{name}, -given in the standard numbers-and-dots notation. The returned address is -in host order. If the input is not valid, @code{inet_network} returns -@code{-1}. - -The function works only with traditional IPv4 class A, B and C network -types. It doesn't work with classless addresses and shouldn't be used -anymore. -@end deftypefun - -@comment arpa/inet.h -@comment BSD -@deftypefun {char *} inet_ntoa (struct in_addr @var{addr}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asurace{}}@acsafe{}} -@c inet_ntoa @mtslocale @asurace -@c writes to a thread-local static buffer -@c snprintf @mtslocale [no @ascuheap or @acsmem] -This function converts the IPv4 Internet host address @var{addr} to a -string in the standard numbers-and-dots notation. The return value is -a pointer into a statically-allocated buffer. Subsequent calls will -overwrite the same buffer, so you should copy the string if you need -to save it. - -In multi-threaded programs each thread has its own statically-allocated -buffer. But still subsequent calls of @code{inet_ntoa} in the same -thread will overwrite the result of the last call. - -Instead of @code{inet_ntoa} the newer function @code{inet_ntop} which is -described below should be used since it handles both IPv4 and IPv6 -addresses. -@end deftypefun - -@comment arpa/inet.h -@comment BSD -@deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c inet_makeaddr ok -@c htonl dup ok -This function makes an IPv4 Internet host address by combining the network -number @var{net} with the local-address-within-network number -@var{local}. -@end deftypefun - -@comment arpa/inet.h -@comment BSD -@deftypefun uint32_t inet_lnaof (struct in_addr @var{addr}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c inet_lnaof ok -@c ntohl dup ok -@c IN_CLASSA ok -@c IN_CLASSB ok -This function returns the local-address-within-network part of the -Internet host address @var{addr}. - -The function works only with traditional IPv4 class A, B and C network -types. It doesn't work with classless addresses and shouldn't be used -anymore. -@end deftypefun - -@comment arpa/inet.h -@comment BSD -@deftypefun uint32_t inet_netof (struct in_addr @var{addr}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c inet_netof ok -@c ntohl dup ok -@c IN_CLASSA ok -@c IN_CLASSB ok -This function returns the network number part of the Internet host -address @var{addr}. - -The function works only with traditional IPv4 class A, B and C network -types. It doesn't work with classless addresses and shouldn't be used -anymore. -@end deftypefun - -@comment arpa/inet.h -@comment IPv6 basic API -@deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} -@c inet_pton @mtslocale -@c inet_pton4 ok -@c memcpy dup ok -@c inet_pton6 @mtslocale -@c memset dup ok -@c tolower dup @mtslocale -@c strchr dup ok -@c inet_pton4 dup ok -@c memcpy dup ok -This function converts an Internet address (either IPv4 or IPv6) from -presentation (textual) to network (binary) format. @var{af} should be -either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of -address being converted. @var{cp} is a pointer to the input string, and -@var{buf} is a pointer to a buffer for the result. It is the caller's -responsibility to make sure the buffer is large enough. -@end deftypefun - -@comment arpa/inet.h -@comment IPv6 basic API -@deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} -@c inet_ntop @mtslocale -@c inet_ntop4 @mtslocale -@c sprintf dup @mtslocale [no @ascuheap or @acsmem] -@c strcpy dup ok -@c inet_ntop6 @mtslocale -@c memset dup ok -@c inet_ntop4 dup @mtslocale -@c sprintf dup @mtslocale [no @ascuheap or @acsmem] -@c strcpy dup ok -This function converts an Internet address (either IPv4 or IPv6) from -network (binary) to presentation (textual) form. @var{af} should be -either @code{AF_INET} or @code{AF_INET6}, as appropriate. @var{cp} is a -pointer to the address to be converted. @var{buf} should be a pointer -to a buffer to hold the result, and @var{len} is the length of this -buffer. The return value from the function will be this buffer address. -@end deftypefun - -@node Host Names -@subsubsection Host Names -@cindex hosts database -@cindex converting host name to address -@cindex converting host address to name - -Besides the standard numbers-and-dots notation for Internet addresses, -you can also refer to a host by a symbolic name. The advantage of a -symbolic name is that it is usually easier to remember. For example, -the machine with Internet address @samp{158.121.106.19} is also known as -@samp{alpha.gnu.org}; and other machines in the @samp{gnu.org} -domain can refer to it simply as @samp{alpha}. - -@pindex /etc/hosts -@pindex netdb.h -Internally, the system uses a database to keep track of the mapping -between host names and host numbers. This database is usually either -the file @file{/etc/hosts} or an equivalent provided by a name server. -The functions and other symbols for accessing this database are declared -in @file{netdb.h}. They are BSD features, defined unconditionally if -you include @file{netdb.h}. - -@comment netdb.h -@comment BSD -@deftp {Data Type} {struct hostent} -This data type is used to represent an entry in the hosts database. It -has the following members: - -@table @code -@item char *h_name -This is the ``official'' name of the host. - -@item char **h_aliases -These are alternative names for the host, represented as a null-terminated -vector of strings. - -@item int h_addrtype -This is the host address type; in practice, its value is always either -@code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6 -hosts. In principle other kinds of addresses could be represented in -the database as well as Internet addresses; if this were done, you -might find a value in this field other than @code{AF_INET} or -@code{AF_INET6}. @xref{Socket Addresses}. - -@item int h_length -This is the length, in bytes, of each address. - -@item char **h_addr_list -This is the vector of addresses for the host. (Recall that the host -might be connected to multiple networks and have different addresses on -each one.) The vector is terminated by a null pointer. - -@item char *h_addr -This is a synonym for @code{h_addr_list[0]}; in other words, it is the -first host address. -@end table -@end deftp - -As far as the host database is concerned, each address is just a block -of memory @code{h_length} bytes long. But in other contexts there is an -implicit assumption that you can convert IPv4 addresses to a -@code{struct in_addr} or an @code{uint32_t}. Host addresses in -a @code{struct hostent} structure are always given in network byte -order; see @ref{Byte Order}. - -You can use @code{gethostbyname}, @code{gethostbyname2} or -@code{gethostbyaddr} to search the hosts database for information about -a particular host. The information is returned in a -statically-allocated structure; you must copy the information if you -need to save it across calls. You can also use @code{getaddrinfo} and -@code{getnameinfo} to obtain this information. - -@comment netdb.h -@comment BSD -@deftypefun {struct hostent *} gethostbyname (const char *@var{name}) -@safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} -@c gethostbyname @mtasurace:hostbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd -@c libc_lock_lock dup @asulock @aculock -@c malloc dup @ascuheap @acsmem -@c nss_hostname_digits_dots @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c res_maybe_init(!preinit) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c res_iclose @acsuheap @acsmem @acsfd -@c close_not_cancel_no_status dup @acsfd -@c free dup @acsuheap @acsmem -@c res_vinit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c res_randomid ok -@c getpid dup ok -@c getenv dup @mtsenv -@c strncpy dup ok -@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock -@c fsetlocking dup ok [no concurrent uses] -@c fgets_unlocked dup ok [no concurrent uses] -@c MATCH ok -@c strncmp dup ok -@c strpbrk dup ok -@c strchr dup ok -@c inet_aton dup @mtslocale -@c htons dup -@c inet_pton dup @mtslocale -@c malloc dup @ascuheap @acsmem -@c IN6_IS_ADDR_LINKLOCAL ok -@c htonl dup ok -@c IN6_IS_ADDR_MC_LINKLOCAL ok -@c if_nametoindex dup @asulock @aculock @acsfd -@c strtoul dup @mtslocale -@c ISSORTMASK ok -@c strchr dup ok -@c isascii dup @mtslocale -@c isspace dup @mtslocale -@c net_mask ok -@c ntohl dup ok -@c IN_CLASSA dup ok -@c htonl dup ok -@c IN_CLASSB dup ok -@c res_setoptions @mtslocale -@c strncmp dup ok -@c atoi dup @mtslocale -@c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd -@c inet_makeaddr dup ok -@c gethostname dup ok -@c strcpy dup ok -@c rawmemchr dup ok -@c res_ninit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c res_vinit dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c isdigit dup @mtslocale -@c isxdigit dup @mtslocale -@c strlen dup ok -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c memset dup ok -@c inet_aton dup @mtslocale -@c inet_pton dup @mtslocale -@c strcpy dup ok -@c memcpy dup ok -@c strchr dup ok -@c gethostbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c set_h_errno ok -The @code{gethostbyname} function returns information about the host -named @var{name}. If the lookup fails, it returns a null pointer. -@end deftypefun - -@comment netdb.h -@comment IPv6 Basic API -@deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af}) -@safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname2} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} -@c gethostbyname2 @mtasurace:hostbyname2 @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd -@c libc_lock_lock dup @asulock @aculock -@c malloc dup @ascuheap @acsmem -@c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c gethostbyname2_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c set_h_errno dup ok -The @code{gethostbyname2} function is like @code{gethostbyname}, but -allows the caller to specify the desired address family (e.g.@: -@code{AF_INET} or @code{AF_INET6}) of the result. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun {struct hostent *} gethostbyaddr (const void *@var{addr}, socklen_t @var{length}, int @var{format}) -@safety{@prelim{}@mtunsafe{@mtasurace{:hostbyaddr} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} -@c gethostbyaddr @mtasurace:hostbyaddr @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd -@c libc_lock_lock dup @asulock @aculock -@c malloc dup @ascuheap @acsmem -@c gethostbyaddr_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c set_h_errno dup ok -The @code{gethostbyaddr} function returns information about the host -with Internet address @var{addr}. The parameter @var{addr} is not -really a pointer to char - it can be a pointer to an IPv4 or an IPv6 -address. The @var{length} argument is the size (in bytes) of the address -at @var{addr}. @var{format} specifies the address format; for an IPv4 -Internet address, specify a value of @code{AF_INET}; for an IPv6 -Internet address, use @code{AF_INET6}. - -If the lookup fails, @code{gethostbyaddr} returns a null pointer. -@end deftypefun - -@vindex h_errno -If the name lookup by @code{gethostbyname} or @code{gethostbyaddr} -fails, you can find out the reason by looking at the value of the -variable @code{h_errno}. (It would be cleaner design for these -functions to set @code{errno}, but use of @code{h_errno} is compatible -with other systems.) - -Here are the error codes that you may find in @code{h_errno}: - -@vtable @code -@comment netdb.h -@comment BSD -@item HOST_NOT_FOUND -No such host is known in the database. - -@comment netdb.h -@comment BSD -@item TRY_AGAIN -This condition happens when the name server could not be contacted. If -you try again later, you may succeed then. - -@comment netdb.h -@comment BSD -@item NO_RECOVERY -A non-recoverable error occurred. - -@comment netdb.h -@comment BSD -@item NO_ADDRESS -The host database contains an entry for the name, but it doesn't have an -associated Internet address. -@end vtable - -The lookup functions above all have one thing in common: they are not -reentrant and therefore unusable in multi-threaded applications. -Therefore provides @theglibc{} a new set of functions which can be -used in this context. - -@comment netdb.h -@comment GNU -@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}) -@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} -@c gethostbyname_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd -@c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c nscd_gethostbyname_r @mtsenv @ascuheap @acsfd @acsmem -@c nscd_gethst_r @mtsenv @ascuheap @acsfd @acsmem -@c getenv dup @mtsenv -@c nscd_get_map_ref dup @ascuheap @acsfd @acsmem -@c nscd_cache_search dup ok -@c memcpy dup ok -@c nscd_open_socket dup @acsfd -@c readvall dup ok -@c readall dup ok -@c close_not_cancel_no_status dup @acsfd -@c nscd_drop_map_ref dup @ascuheap @acsmem -@c nscd_unmap dup @ascuheap @acsmem -@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c res_hconf_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called] -@c res_hconf.c:do_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem -@c memset dup ok -@c getenv dup @mtsenv -@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock -@c fsetlocking dup ok [no concurrent uses] -@c fgets_unlocked dup ok [no concurrent uses] -@c strchrnul dup ok -@c res_hconf.c:parse_line @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem -@c skip_ws dup @mtslocale -@c skip_string dup @mtslocale -@c strncasecmp dup @mtslocale -@c strlen dup ok -@c asprintf dup @mtslocale @ascuheap @acsmem -@c fxprintf dup @asucorrupt @aculock @acucorrupt -@c free dup @ascuheap @acsmem -@c arg_trimdomain_list dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem -@c arg_spoof dup @mtslocale -@c arg_bool dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem -@c isspace dup @mtslocale -@c fclose dup @ascuheap @asulock @acsmem @acsfd @aculock -@c arg_spoof @mtslocale -@c skip_string @mtslocale -@c isspace dup @mtslocale -@c strncasecmp dup @mtslocale -@c arg_bool @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem -@c strncasecmp dup @mtslocale -@c asprintf dup @mtslocale @ascuheap @acsmem -@c fxprintf dup @asucorrupt @aculock @acucorrupt -@c free dup @ascuheap @acsmem -@c arg_trimdomain_list @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem -@c skip_string dup @mtslocale -@c asprintf dup @mtslocale @ascuheap @acsmem -@c fxprintf dup @asucorrupt @aculock @acucorrupt -@c free dup @ascuheap @acsmem -@c strndup dup @ascuheap @acsmem -@c skip_ws @mtslocale -@c isspace dup @mtslocale -@c nss_hosts_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nss_database_lookup dup @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock -@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.l -> _nss_*_gethostbyname_r @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c res_hconf_reorder_addrs @asulock @ascuheap @aculock @acsmem @acsfd -@c socket dup @acsfd -@c libc_lock_lock dup @asulock @aculock -@c ifreq @ascuheap @acsmem -@c malloc dup @ascuheap @acsmem -@c if_nextreq dup ok -@c ioctl dup ok -@c realloc dup @ascuheap @acsmem -@c if_freereq dup @acsmem -@c libc_lock_unlock dup @aculock -@c close dup @acsfd -The @code{gethostbyname_r} function returns information about the host -named @var{name}. The caller must pass a pointer to an object of type -@code{struct hostent} in the @var{result_buf} parameter. In addition -the function may need extra buffer space and the caller must pass a -pointer and the size of the buffer in the @var{buf} and @var{buflen} -parameters. - -A pointer to the buffer, in which the result is stored, is available in -@code{*@var{result}} after the function call successfully returned. The -buffer passed as the @var{buf} parameter can be freed only once the caller -has finished with the result hostent struct, or has copied it including all -the other memory that it points to. If an error occurs or if no entry is -found, the pointer @code{*@var{result}} is a null pointer. Success is -signalled by a zero return value. If the function failed the return value -is an error number. In addition to the errors defined for -@code{gethostbyname} it can also be @code{ERANGE}. In this case the call -should be repeated with a larger buffer. Additional error information is -not stored in the global variable @code{h_errno} but instead in the object -pointed to by @var{h_errnop}. - -Here's a small example: -@smallexample -struct hostent * -gethostname (char *host) -@{ - struct hostent *hostbuf, *hp; - size_t hstbuflen; - char *tmphstbuf; - int res; - int herr; - - hostbuf = malloc (sizeof (struct hostent)); - hstbuflen = 1024; - tmphstbuf = malloc (hstbuflen); - - while ((res = gethostbyname_r (host, hostbuf, tmphstbuf, hstbuflen, - &hp, &herr)) == ERANGE) - @{ - /* Enlarge the buffer. */ - hstbuflen *= 2; - tmphstbuf = realloc (tmphstbuf, hstbuflen); - @} - - free (tmphstbuf); - /* Check for errors. */ - if (res || hp == NULL) - return NULL; - return hp; -@} -@end smallexample -@end deftypefun - -@comment netdb.h -@comment GNU -@deftypefun int gethostbyname2_r (const char *@var{name}, int @var{af}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) -@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} -@c gethostbyname2_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd -@c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c nscd_gethostbyname2_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem -@c nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem -@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called] -@c nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.l -> _nss_*_gethostbyname2_r @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd -The @code{gethostbyname2_r} function is like @code{gethostbyname_r}, but -allows the caller to specify the desired address family (e.g.@: -@code{AF_INET} or @code{AF_INET6}) for the result. -@end deftypefun - -@comment netdb.h -@comment GNU -@deftypefun int gethostbyaddr_r (const void *@var{addr}, socklen_t @var{length}, int @var{format}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) -@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} -@c gethostbyaddr_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd -@c memcmp dup ok -@c nscd_gethostbyaddr_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem -@c nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem -@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called] -@c nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.l -> _nss_*_gethostbyaddr_r @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd -@c res_hconf_trim_domains @mtslocale -@c res_hconf_trim_domain @mtslocale -@c strlen dup ok -@c strcasecmp dup @mtslocale -The @code{gethostbyaddr_r} function returns information about the host -with Internet address @var{addr}. The parameter @var{addr} is not -really a pointer to char - it can be a pointer to an IPv4 or an IPv6 -address. The @var{length} argument is the size (in bytes) of the address -at @var{addr}. @var{format} specifies the address format; for an IPv4 -Internet address, specify a value of @code{AF_INET}; for an IPv6 -Internet address, use @code{AF_INET6}. - -Similar to the @code{gethostbyname_r} function, the caller must provide -buffers for the result and memory used internally. In case of success -the function returns zero. Otherwise the value is an error number where -@code{ERANGE} has the special meaning that the caller-provided buffer is -too small. -@end deftypefun - -You can also scan the entire hosts database one entry at a time using -@code{sethostent}, @code{gethostent} and @code{endhostent}. Be careful -when using these functions because they are not reentrant. - -@comment netdb.h -@comment BSD -@deftypefun void sethostent (int @var{stayopen}) -@safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c sethostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_setent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c set_h_errno dup ok -@c setup(nss_hosts_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *lookup_fct = nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:hostent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_unlock dup @aculock -This function opens the hosts database to begin scanning it. You can -then call @code{gethostent} to read the entries. - -@c There was a rumor that this flag has different meaning if using the DNS, -@c but it appears this description is accurate in that case also. -If the @var{stayopen} argument is nonzero, this sets a flag so that -subsequent calls to @code{gethostbyname} or @code{gethostbyaddr} will -not close the database (as they usually would). This makes for more -efficiency if you call those functions several times, by avoiding -reopening the database for each call. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun {struct hostent *} gethostent (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtasurace{:hostentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c gethostent @mtasurace:hostent @mtasurace:hostentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_getent(gethostent_r) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c malloc dup @ascuheap @acsmem -@c *func = gethostent_r dup @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c -@c gethostent_r @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_getent_r(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c setup(nss_hosts_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:hostent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *sfct.f @mtasurace:hostent @ascuplugin -@c libc_lock_unlock dup @aculock - -This function returns the next entry in the hosts database. It -returns a null pointer if there are no more entries. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun void endhostent (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c endhostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock @asulock @aculock -@c nss_endent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c setup(nss_passwd_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:hostent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_unlock @aculock -This function closes the hosts database. -@end deftypefun - -@node Ports -@subsection Internet Ports -@cindex port number - -A socket address in the Internet namespace consists of a machine's -Internet address plus a @dfn{port number} which distinguishes the -sockets on a given machine (for a given protocol). Port numbers range -from 0 to 65,535. - -Port numbers less than @code{IPPORT_RESERVED} are reserved for standard -servers, such as @code{finger} and @code{telnet}. There is a database -that keeps track of these, and you can use the @code{getservbyname} -function to map a service name onto a port number; see @ref{Services -Database}. - -If you write a server that is not one of the standard ones defined in -the database, you must choose a port number for it. Use a number -greater than @code{IPPORT_USERRESERVED}; such numbers are reserved for -servers and won't ever be generated automatically by the system. -Avoiding conflicts with servers being run by other users is up to you. - -When you use a socket without specifying its address, the system -generates a port number for it. This number is between -@code{IPPORT_RESERVED} and @code{IPPORT_USERRESERVED}. - -On the Internet, it is actually legitimate to have two different -sockets with the same port number, as long as they never both try to -communicate with the same socket address (host address plus port -number). You shouldn't duplicate a port number except in special -circumstances where a higher-level protocol requires it. Normally, -the system won't let you do it; @code{bind} normally insists on -distinct port numbers. To reuse a port number, you must set the -socket option @code{SO_REUSEADDR}. @xref{Socket-Level Options}. - -@pindex netinet/in.h -These macros are defined in the header file @file{netinet/in.h}. - -@comment netinet/in.h -@comment BSD -@deftypevr Macro int IPPORT_RESERVED -Port numbers less than @code{IPPORT_RESERVED} are reserved for -superuser use. -@end deftypevr - -@comment netinet/in.h -@comment BSD -@deftypevr Macro int IPPORT_USERRESERVED -Port numbers greater than or equal to @code{IPPORT_USERRESERVED} are -reserved for explicit use; they will never be allocated automatically. -@end deftypevr - -@node Services Database -@subsection The Services Database -@cindex services database -@cindex converting service name to port number -@cindex converting port number to service name - -@pindex /etc/services -The database that keeps track of ``well-known'' services is usually -either the file @file{/etc/services} or an equivalent from a name server. -You can use these utilities, declared in @file{netdb.h}, to access -the services database. -@pindex netdb.h - -@comment netdb.h -@comment BSD -@deftp {Data Type} {struct servent} -This data type holds information about entries from the services database. -It has the following members: - -@table @code -@item char *s_name -This is the ``official'' name of the service. - -@item char **s_aliases -These are alternate names for the service, represented as an array of -strings. A null pointer terminates the array. - -@item int s_port -This is the port number for the service. Port numbers are given in -network byte order; see @ref{Byte Order}. - -@item char *s_proto -This is the name of the protocol to use with this service. -@xref{Protocols Database}. -@end table -@end deftp - -To get information about a particular service, use the -@code{getservbyname} or @code{getservbyport} functions. The information -is returned in a statically-allocated structure; you must copy the -information if you need to save it across calls. - -@comment netdb.h -@comment BSD -@deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto}) -@safety{@prelim{}@mtunsafe{@mtasurace{:servbyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c getservbyname =~ getpwuid @mtasurace:servbyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c malloc dup @ascuheap @acsmem -@c getservbyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c -@c getservbyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nscd_getservbyname_r @ascuheap @acsfd @acsmem -@c nscd_getserv_r @ascuheap @acsfd @acsmem -@c nscd_get_map_ref dup @ascuheap @acsfd @acsmem -@c strlen dup ok -@c malloc dup @ascuheap @acsmem -@c mempcpy dup ok -@c memcpy dup ok -@c nscd_cache_search dup ok -@c nscd_open_socket dup @acsfd -@c readvall dup ok -@c readall dup ok -@c close_not_cancel_no_status dup @acsfd -@c nscd_drop_map_ref dup @ascuheap @acsmem -@c nscd_unmap dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.l -> _nss_*_getservbyname_r @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -The @code{getservbyname} function returns information about the -service named @var{name} using protocol @var{proto}. If it can't find -such a service, it returns a null pointer. - -This function is useful for servers as well as for clients; servers -use it to determine which port they should listen on (@pxref{Listening}). -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto}) -@safety{@prelim{}@mtunsafe{@mtasurace{:servbyport} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c getservbyport =~ getservbyname @mtasurace:servbyport @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c malloc dup @ascuheap @acsmem -@c getservbyport_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c -@c getservbyport_r =~ getservbyname_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nscd_getservbyport_r @ascuheap @acsfd @acsmem -@c nscd_getserv_r dup @ascuheap @acsfd @acsmem -@c nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.l -> _nss_*_getservbyport_r @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -The @code{getservbyport} function returns information about the -service at port @var{port} using protocol @var{proto}. If it can't -find such a service, it returns a null pointer. -@end deftypefun - -@noindent -You can also scan the services database using @code{setservent}, -@code{getservent} and @code{endservent}. Be careful when using these -functions because they are not reentrant. - -@comment netdb.h -@comment BSD -@deftypefun void setservent (int @var{stayopen}) -@safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c setservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_setent(nss_services_lookup2) @mtasurace:servenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c setup(nss_services_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *lookup_fct = nss_services_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:servent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_unlock dup @aculock -This function opens the services database to begin scanning it. - -If the @var{stayopen} argument is nonzero, this sets a flag so that -subsequent calls to @code{getservbyname} or @code{getservbyport} will -not close the database (as they usually would). This makes for more -efficiency if you call those functions several times, by avoiding -reopening the database for each call. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun {struct servent *} getservent (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtasurace{:serventbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c getservent @mtasurace:servent @mtasurace:serventbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_getent(getservent_r) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c malloc dup @ascuheap @acsmem -@c *func = getservent_r dup @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c -@c getservent_r @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_getent_r(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:servent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *sfct.f @mtasurace:servent @ascuplugin -@c libc_lock_unlock dup @aculock -This function returns the next entry in the services database. If -there are no more entries, it returns a null pointer. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun void endservent (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c endservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock @asulock @aculock -@c nss_endent(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:servent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_unlock @aculock -This function closes the services database. -@end deftypefun - -@node Byte Order -@subsection Byte Order Conversion -@cindex byte order conversion, for socket -@cindex converting byte order - -@cindex big-endian -@cindex little-endian -Different kinds of computers use different conventions for the -ordering of bytes within a word. Some computers put the most -significant byte within a word first (this is called ``big-endian'' -order), and others put it last (``little-endian'' order). - -@cindex network byte order -So that machines with different byte order conventions can -communicate, the Internet protocols specify a canonical byte order -convention for data transmitted over the network. This is known -as @dfn{network byte order}. - -When establishing an Internet socket connection, you must make sure that -the data in the @code{sin_port} and @code{sin_addr} members of the -@code{sockaddr_in} structure are represented in network byte order. -If you are encoding integer data in the messages sent through the -socket, you should convert this to network byte order too. If you don't -do this, your program may fail when running on or talking to other kinds -of machines. - -If you use @code{getservbyname} and @code{gethostbyname} or -@code{inet_addr} to get the port number and host address, the values are -already in network byte order, and you can copy them directly into -the @code{sockaddr_in} structure. - -Otherwise, you have to convert the values explicitly. Use @code{htons} -and @code{ntohs} to convert values for the @code{sin_port} member. Use -@code{htonl} and @code{ntohl} to convert IPv4 addresses for the -@code{sin_addr} member. (Remember, @code{struct in_addr} is equivalent -to @code{uint32_t}.) These functions are declared in -@file{netinet/in.h}. -@pindex netinet/in.h - -@comment netinet/in.h -@comment BSD -@deftypefun {uint16_t} htons (uint16_t @var{hostshort}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c htons ok -@c bswap_16 ok -@c bswap_constant_16 ok - -This function converts the @code{uint16_t} integer @var{hostshort} from -host byte order to network byte order. -@end deftypefun - -@comment netinet/in.h -@comment BSD -@deftypefun {uint16_t} ntohs (uint16_t @var{netshort}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Alias to htons. -This function converts the @code{uint16_t} integer @var{netshort} from -network byte order to host byte order. -@end deftypefun - -@comment netinet/in.h -@comment BSD -@deftypefun {uint32_t} htonl (uint32_t @var{hostlong}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c htonl ok -@c bswap_32 dup ok -This function converts the @code{uint32_t} integer @var{hostlong} from -host byte order to network byte order. - -This is used for IPv4 Internet addresses. -@end deftypefun - -@comment netinet/in.h -@comment BSD -@deftypefun {uint32_t} ntohl (uint32_t @var{netlong}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Alias to htonl. -This function converts the @code{uint32_t} integer @var{netlong} from -network byte order to host byte order. - -This is used for IPv4 Internet addresses. -@end deftypefun - -@node Protocols Database -@subsection Protocols Database -@cindex protocols database - -The communications protocol used with a socket controls low-level -details of how data are exchanged. For example, the protocol implements -things like checksums to detect errors in transmissions, and routing -instructions for messages. Normal user programs have little reason to -mess with these details directly. - -@cindex TCP (Internet protocol) -The default communications protocol for the Internet namespace depends on -the communication style. For stream communication, the default is TCP -(``transmission control protocol''). For datagram communication, the -default is UDP (``user datagram protocol''). For reliable datagram -communication, the default is RDP (``reliable datagram protocol''). -You should nearly always use the default. - -@pindex /etc/protocols -Internet protocols are generally specified by a name instead of a -number. The network protocols that a host knows about are stored in a -database. This is usually either derived from the file -@file{/etc/protocols}, or it may be an equivalent provided by a name -server. You look up the protocol number associated with a named -protocol in the database using the @code{getprotobyname} function. - -Here are detailed descriptions of the utilities for accessing the -protocols database. These are declared in @file{netdb.h}. -@pindex netdb.h - -@comment netdb.h -@comment BSD -@deftp {Data Type} {struct protoent} -This data type is used to represent entries in the network protocols -database. It has the following members: - -@table @code -@item char *p_name -This is the official name of the protocol. - -@item char **p_aliases -These are alternate names for the protocol, specified as an array of -strings. The last element of the array is a null pointer. - -@item int p_proto -This is the protocol number (in host byte order); use this member as the -@var{protocol} argument to @code{socket}. -@end table -@end deftp - -You can use @code{getprotobyname} and @code{getprotobynumber} to search -the protocols database for a specific protocol. The information is -returned in a statically-allocated structure; you must copy the -information if you need to save it across calls. - -@comment netdb.h -@comment BSD -@deftypefun {struct protoent *} getprotobyname (const char *@var{name}) -@safety{@prelim{}@mtunsafe{@mtasurace{:protobyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c getprotobyname =~ getpwuid @mtasurace:protobyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c malloc dup @ascuheap @acsmem -@c getprotobyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c -@c getprotobyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c no nscd support -@c nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.l -> _nss_*_getprotobyname_r @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -The @code{getprotobyname} function returns information about the -network protocol named @var{name}. If there is no such protocol, it -returns a null pointer. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun {struct protoent *} getprotobynumber (int @var{protocol}) -@safety{@prelim{}@mtunsafe{@mtasurace{:protobynumber} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c getprotobynumber =~ getpwuid @mtasurace:protobynumber @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c malloc dup @ascuheap @acsmem -@c getprotobynumber_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c -@c getprotobynumber_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c no nscd support -@c nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.l -> _nss_*_getprotobynumber_r @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -The @code{getprotobynumber} function returns information about the -network protocol with number @var{protocol}. If there is no such -protocol, it returns a null pointer. -@end deftypefun - -You can also scan the whole protocols database one protocol at a time by -using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}. -Be careful when using these functions because they are not reentrant. - -@comment netdb.h -@comment BSD -@deftypefun void setprotoent (int @var{stayopen}) -@safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c setprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_setent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c setup(nss_protocols_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *lookup_fct = nss_protocols_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:protoent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_unlock dup @aculock -This function opens the protocols database to begin scanning it. - -If the @var{stayopen} argument is nonzero, this sets a flag so that -subsequent calls to @code{getprotobyname} or @code{getprotobynumber} will -not close the database (as they usually would). This makes for more -efficiency if you call those functions several times, by avoiding -reopening the database for each call. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun {struct protoent *} getprotoent (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtasurace{:protoentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c getprotoent @mtasurace:protoent @mtasurace:protoentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_getent(getprotoent_r) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c malloc dup @ascuheap @acsmem -@c *func = getprotoent_r dup @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c -@c getprotoent_r @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_getent_r(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:servent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *sfct.f @mtasurace:protoent @ascuplugin -@c libc_lock_unlock dup @aculock -This function returns the next entry in the protocols database. It -returns a null pointer if there are no more entries. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun void endprotoent (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c endprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock @asulock @aculock -@c nss_endent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:protoent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_unlock @aculock -This function closes the protocols database. -@end deftypefun - -@node Inet Example -@subsection Internet Socket Example - -Here is an example showing how to create and name a socket in the -Internet namespace. The newly created socket exists on the machine that -the program is running on. Rather than finding and using the machine's -Internet address, this example specifies @code{INADDR_ANY} as the host -address; the system replaces that with the machine's actual address. - -@smallexample -@include mkisock.c.texi -@end smallexample - -Here is another example, showing how you can fill in a @code{sockaddr_in} -structure, given a host name string and a port number: - -@smallexample -@include isockad.c.texi -@end smallexample - -@node Misc Namespaces -@section Other Namespaces - -@vindex PF_NS -@vindex PF_ISO -@vindex PF_CCITT -@vindex PF_IMPLINK -@vindex PF_ROUTE -Certain other namespaces and associated protocol families are supported -but not documented yet because they are not often used. @code{PF_NS} -refers to the Xerox Network Software protocols. @code{PF_ISO} stands -for Open Systems Interconnect. @code{PF_CCITT} refers to protocols from -CCITT. @file{socket.h} defines these symbols and others naming protocols -not actually implemented. - -@code{PF_IMPLINK} is used for communicating between hosts and Internet -Message Processors. For information on this and @code{PF_ROUTE}, an -occasionally-used local area routing protocol, see the GNU Hurd Manual -(to appear in the future). - -@node Open/Close Sockets -@section Opening and Closing Sockets - -This section describes the actual library functions for opening and -closing sockets. The same functions work for all namespaces and -connection styles. - -@menu -* Creating a Socket:: How to open a socket. -* Closing a Socket:: How to close a socket. -* Socket Pairs:: These are created like pipes. -@end menu - -@node Creating a Socket -@subsection Creating a Socket -@cindex creating a socket -@cindex socket, creating -@cindex opening a socket - -The primitive for creating a socket is the @code{socket} function, -declared in @file{sys/socket.h}. -@pindex sys/socket.h - -@comment sys/socket.h -@comment BSD -@deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} -This function creates a socket and specifies communication style -@var{style}, which should be one of the socket styles listed in -@ref{Communication Styles}. The @var{namespace} argument specifies -the namespace; it must be @code{PF_LOCAL} (@pxref{Local Namespace}) or -@code{PF_INET} (@pxref{Internet Namespace}). @var{protocol} -designates the specific protocol (@pxref{Socket Concepts}); zero is -usually right for @var{protocol}. - -The return value from @code{socket} is the file descriptor for the new -socket, or @code{-1} in case of error. The following @code{errno} error -conditions are defined for this function: - -@table @code -@item EPROTONOSUPPORT -The @var{protocol} or @var{style} is not supported by the -@var{namespace} specified. - -@item EMFILE -The process already has too many file descriptors open. - -@item ENFILE -The system already has too many file descriptors open. - -@item EACCES -The process does not have the privilege to create a socket of the specified -@var{style} or @var{protocol}. - -@item ENOBUFS -The system ran out of internal buffer space. -@end table - -The file descriptor returned by the @code{socket} function supports both -read and write operations. However, like pipes, sockets do not support file -positioning operations. -@end deftypefun - -For examples of how to call the @code{socket} function, -see @ref{Local Socket Example}, or @ref{Inet Example}. - - -@node Closing a Socket -@subsection Closing a Socket -@cindex socket, closing -@cindex closing a socket -@cindex shutting down a socket -@cindex socket shutdown - -When you have finished using a socket, you can simply close its -file descriptor with @code{close}; see @ref{Opening and Closing Files}. -If there is still data waiting to be transmitted over the connection, -normally @code{close} tries to complete this transmission. You -can control this behavior using the @code{SO_LINGER} socket option to -specify a timeout period; see @ref{Socket Options}. - -@pindex sys/socket.h -You can also shut down only reception or transmission on a -connection by calling @code{shutdown}, which is declared in -@file{sys/socket.h}. - -@comment sys/socket.h -@comment BSD -@deftypefun int shutdown (int @var{socket}, int @var{how}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{shutdown} function shuts down the connection of socket -@var{socket}. The argument @var{how} specifies what action to -perform: - -@table @code -@item 0 -Stop receiving data for this socket. If further data arrives, -reject it. - -@item 1 -Stop trying to transmit data from this socket. Discard any data -waiting to be sent. Stop looking for acknowledgement of data already -sent; don't retransmit it if it is lost. - -@item 2 -Stop both reception and transmission. -@end table - -The return value is @code{0} on success and @code{-1} on failure. The -following @code{errno} error conditions are defined for this function: - -@table @code -@item EBADF -@var{socket} is not a valid file descriptor. - -@item ENOTSOCK -@var{socket} is not a socket. - -@item ENOTCONN -@var{socket} is not connected. -@end table -@end deftypefun - -@node Socket Pairs -@subsection Socket Pairs -@cindex creating a socket pair -@cindex socket pair -@cindex opening a socket pair - -@pindex sys/socket.h -A @dfn{socket pair} consists of a pair of connected (but unnamed) -sockets. It is very similar to a pipe and is used in much the same -way. Socket pairs are created with the @code{socketpair} function, -declared in @file{sys/socket.h}. A socket pair is much like a pipe; the -main difference is that the socket pair is bidirectional, whereas the -pipe has one input-only end and one output-only end (@pxref{Pipes and -FIFOs}). - -@comment sys/socket.h -@comment BSD -@deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} -This function creates a socket pair, returning the file descriptors in -@code{@var{filedes}[0]} and @code{@var{filedes}[1]}. The socket pair -is a full-duplex communications channel, so that both reading and writing -may be performed at either end. - -The @var{namespace}, @var{style} and @var{protocol} arguments are -interpreted as for the @code{socket} function. @var{style} should be -one of the communication styles listed in @ref{Communication Styles}. -The @var{namespace} argument specifies the namespace, which must be -@code{AF_LOCAL} (@pxref{Local Namespace}); @var{protocol} specifies the -communications protocol, but zero is the only meaningful value. - -If @var{style} specifies a connectionless communication style, then -the two sockets you get are not @emph{connected}, strictly speaking, -but each of them knows the other as the default destination address, -so they can send packets to each other. - -The @code{socketpair} function returns @code{0} on success and @code{-1} -on failure. The following @code{errno} error conditions are defined -for this function: - -@table @code -@item EMFILE -The process has too many file descriptors open. - -@item EAFNOSUPPORT -The specified namespace is not supported. - -@item EPROTONOSUPPORT -The specified protocol is not supported. - -@item EOPNOTSUPP -The specified protocol does not support the creation of socket pairs. -@end table -@end deftypefun - -@node Connections -@section Using Sockets with Connections - -@cindex connection -@cindex client -@cindex server -The most common communication styles involve making a connection to a -particular other socket, and then exchanging data with that socket -over and over. Making a connection is asymmetric; one side (the -@dfn{client}) acts to request a connection, while the other side (the -@dfn{server}) makes a socket and waits for the connection request. - -@iftex -@itemize @bullet -@item -@ref{Connecting}, describes what the client program must do to -initiate a connection with a server. - -@item -@ref{Listening} and @ref{Accepting Connections} describe what the -server program must do to wait for and act upon connection requests -from clients. - -@item -@ref{Transferring Data}, describes how data are transferred through the -connected socket. -@end itemize -@end iftex - -@menu -* Connecting:: What the client program must do. -* Listening:: How a server program waits for requests. -* Accepting Connections:: What the server does when it gets a request. -* Who is Connected:: Getting the address of the - other side of a connection. -* Transferring Data:: How to send and receive data. -* Byte Stream Example:: An example program: a client for communicating - over a byte stream socket in the Internet namespace. -* Server Example:: A corresponding server program. -* Out-of-Band Data:: This is an advanced feature. -@end menu - -@node Connecting -@subsection Making a Connection -@cindex connecting a socket -@cindex socket, connecting -@cindex socket, initiating a connection -@cindex socket, client actions - -In making a connection, the client makes a connection while the server -waits for and accepts the connection. Here we discuss what the client -program must do with the @code{connect} function, which is declared in -@file{sys/socket.h}. - -@comment sys/socket.h -@comment BSD -@deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{connect} function initiates a connection from the socket -with file descriptor @var{socket} to the socket whose address is -specified by the @var{addr} and @var{length} arguments. (This socket -is typically on another machine, and it must be already set up as a -server.) @xref{Socket Addresses}, for information about how these -arguments are interpreted. - -Normally, @code{connect} waits until the server responds to the request -before it returns. You can set nonblocking mode on the socket -@var{socket} to make @code{connect} return immediately without waiting -for the response. @xref{File Status Flags}, for information about -nonblocking mode. -@c !!! how do you tell when it has finished connecting? I suspect the -@c way you do it is select for writing. - -The normal return value from @code{connect} is @code{0}. If an error -occurs, @code{connect} returns @code{-1}. The following @code{errno} -error conditions are defined for this function: - -@table @code -@item EBADF -The socket @var{socket} is not a valid file descriptor. - -@item ENOTSOCK -File descriptor @var{socket} is not a socket. - -@item EADDRNOTAVAIL -The specified address is not available on the remote machine. - -@item EAFNOSUPPORT -The namespace of the @var{addr} is not supported by this socket. - -@item EISCONN -The socket @var{socket} is already connected. - -@item ETIMEDOUT -The attempt to establish the connection timed out. - -@item ECONNREFUSED -The server has actively refused to establish the connection. - -@item ENETUNREACH -The network of the given @var{addr} isn't reachable from this host. - -@item EADDRINUSE -The socket address of the given @var{addr} is already in use. - -@item EINPROGRESS -The socket @var{socket} is non-blocking and the connection could not be -established immediately. You can determine when the connection is -completely established with @code{select}; @pxref{Waiting for I/O}. -Another @code{connect} call on the same socket, before the connection is -completely established, will fail with @code{EALREADY}. - -@item EALREADY -The socket @var{socket} is non-blocking and already has a pending -connection in progress (see @code{EINPROGRESS} above). -@end table - -This function is defined as a cancellation point in multi-threaded -programs, so one has to be prepared for this and make sure that -allocated resources (like memory, file descriptors, semaphores or -whatever) are freed even if the thread is canceled. -@c @xref{pthread_cleanup_push}, for a method how to do this. -@end deftypefun - -@node Listening -@subsection Listening for Connections -@cindex listening (sockets) -@cindex sockets, server actions -@cindex sockets, listening - -Now let us consider what the server process must do to accept -connections on a socket. First it must use the @code{listen} function -to enable connection requests on the socket, and then accept each -incoming connection with a call to @code{accept} (@pxref{Accepting -Connections}). Once connection requests are enabled on a server socket, -the @code{select} function reports when the socket has a connection -ready to be accepted (@pxref{Waiting for I/O}). - -The @code{listen} function is not allowed for sockets using -connectionless communication styles. - -You can write a network server that does not even start running until a -connection to it is requested. @xref{Inetd Servers}. - -In the Internet namespace, there are no special protection mechanisms -for controlling access to a port; any process on any machine -can make a connection to your server. If you want to restrict access to -your server, make it examine the addresses associated with connection -requests or implement some other handshaking or identification -protocol. - -In the local namespace, the ordinary file protection bits control who has -access to connect to the socket. - -@comment sys/socket.h -@comment BSD -@deftypefun int listen (int @var{socket}, int @var{n}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} -The @code{listen} function enables the socket @var{socket} to accept -connections, thus making it a server socket. - -The argument @var{n} specifies the length of the queue for pending -connections. When the queue fills, new clients attempting to connect -fail with @code{ECONNREFUSED} until the server calls @code{accept} to -accept a connection from the queue. - -The @code{listen} function returns @code{0} on success and @code{-1} -on failure. The following @code{errno} error conditions are defined -for this function: - -@table @code -@item EBADF -The argument @var{socket} is not a valid file descriptor. - -@item ENOTSOCK -The argument @var{socket} is not a socket. - -@item EOPNOTSUPP -The socket @var{socket} does not support this operation. -@end table -@end deftypefun - -@node Accepting Connections -@subsection Accepting Connections -@cindex sockets, accepting connections -@cindex accepting connections - -When a server receives a connection request, it can complete the -connection by accepting the request. Use the function @code{accept} -to do this. - -A socket that has been established as a server can accept connection -requests from multiple clients. The server's original socket -@emph{does not become part of the connection}; instead, @code{accept} -makes a new socket which participates in the connection. -@code{accept} returns the descriptor for this socket. The server's -original socket remains available for listening for further connection -requests. - -The number of pending connection requests on a server socket is finite. -If connection requests arrive from clients faster than the server can -act upon them, the queue can fill up and additional requests are refused -with an @code{ECONNREFUSED} error. You can specify the maximum length of -this queue as an argument to the @code{listen} function, although the -system may also impose its own internal limit on the length of this -queue. - -@comment sys/socket.h -@comment BSD -@deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length_ptr}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} -This function is used to accept a connection request on the server -socket @var{socket}. - -The @code{accept} function waits if there are no connections pending, -unless the socket @var{socket} has nonblocking mode set. (You can use -@code{select} to wait for a pending connection, with a nonblocking -socket.) @xref{File Status Flags}, for information about nonblocking -mode. - -The @var{addr} and @var{length-ptr} arguments are used to return -information about the name of the client socket that initiated the -connection. @xref{Socket Addresses}, for information about the format -of the information. - -Accepting a connection does not make @var{socket} part of the -connection. Instead, it creates a new socket which becomes -connected. The normal return value of @code{accept} is the file -descriptor for the new socket. - -After @code{accept}, the original socket @var{socket} remains open and -unconnected, and continues listening until you close it. You can -accept further connections with @var{socket} by calling @code{accept} -again. - -If an error occurs, @code{accept} returns @code{-1}. The following -@code{errno} error conditions are defined for this function: - -@table @code -@item EBADF -The @var{socket} argument is not a valid file descriptor. - -@item ENOTSOCK -The descriptor @var{socket} argument is not a socket. - -@item EOPNOTSUPP -The descriptor @var{socket} does not support this operation. - -@item EWOULDBLOCK -@var{socket} has nonblocking mode set, and there are no pending -connections immediately available. -@end table - -This function is defined as a cancellation point in multi-threaded -programs, so one has to be prepared for this and make sure that -allocated resources (like memory, file descriptors, semaphores or -whatever) are freed even if the thread is canceled. -@c @xref{pthread_cleanup_push}, for a method how to do this. -@end deftypefun - -The @code{accept} function is not allowed for sockets using -connectionless communication styles. - -@node Who is Connected -@subsection Who is Connected to Me? - -@comment sys/socket.h -@comment BSD -@deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{getpeername} function returns the address of the socket that -@var{socket} is connected to; it stores the address in the memory space -specified by @var{addr} and @var{length-ptr}. It stores the length of -the address in @code{*@var{length-ptr}}. - -@xref{Socket Addresses}, for information about the format of the -address. In some operating systems, @code{getpeername} works only for -sockets in the Internet domain. - -The return value is @code{0} on success and @code{-1} on error. The -following @code{errno} error conditions are defined for this function: - -@table @code -@item EBADF -The argument @var{socket} is not a valid file descriptor. - -@item ENOTSOCK -The descriptor @var{socket} is not a socket. - -@item ENOTCONN -The socket @var{socket} is not connected. - -@item ENOBUFS -There are not enough internal buffers available. -@end table -@end deftypefun - - -@node Transferring Data -@subsection Transferring Data -@cindex reading from a socket -@cindex writing to a socket - -Once a socket has been connected to a peer, you can use the ordinary -@code{read} and @code{write} operations (@pxref{I/O Primitives}) to -transfer data. A socket is a two-way communications channel, so read -and write operations can be performed at either end. - -There are also some I/O modes that are specific to socket operations. -In order to specify these modes, you must use the @code{recv} and -@code{send} functions instead of the more generic @code{read} and -@code{write} functions. The @code{recv} and @code{send} functions take -an additional argument which you can use to specify various flags to -control special I/O modes. For example, you can specify the -@code{MSG_OOB} flag to read or write out-of-band data, the -@code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag -to control inclusion of routing information on output. - -@menu -* Sending Data:: Sending data with @code{send}. -* Receiving Data:: Reading data with @code{recv}. -* Socket Data Options:: Using @code{send} and @code{recv}. -@end menu - -@node Sending Data -@subsubsection Sending Data - -@pindex sys/socket.h -The @code{send} function is declared in the header file -@file{sys/socket.h}. If your @var{flags} argument is zero, you can just -as well use @code{write} instead of @code{send}; see @ref{I/O -Primitives}. If the socket was connected but the connection has broken, -you get a @code{SIGPIPE} signal for any use of @code{send} or -@code{write} (@pxref{Miscellaneous Signals}). - -@comment sys/socket.h -@comment BSD -@deftypefun ssize_t send (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{send} function is like @code{write}, but with the additional -flags @var{flags}. The possible values of @var{flags} are described -in @ref{Socket Data Options}. - -This function returns the number of bytes transmitted, or @code{-1} on -failure. If the socket is nonblocking, then @code{send} (like -@code{write}) can return after sending just part of the data. -@xref{File Status Flags}, for information about nonblocking mode. - -Note, however, that a successful return value merely indicates that -the message has been sent without error, not necessarily that it has -been received without error. - -The following @code{errno} error conditions are defined for this function: - -@table @code -@item EBADF -The @var{socket} argument is not a valid file descriptor. - -@item EINTR -The operation was interrupted by a signal before any data was sent. -@xref{Interrupted Primitives}. - -@item ENOTSOCK -The descriptor @var{socket} is not a socket. - -@item EMSGSIZE -The socket type requires that the message be sent atomically, but the -message is too large for this to be possible. - -@item EWOULDBLOCK -Nonblocking mode has been set on the socket, and the write operation -would block. (Normally @code{send} blocks until the operation can be -completed.) - -@item ENOBUFS -There is not enough internal buffer space available. - -@item ENOTCONN -You never connected this socket. - -@item EPIPE -This socket was connected but the connection is now broken. In this -case, @code{send} generates a @code{SIGPIPE} signal first; if that -signal is ignored or blocked, or if its handler returns, then -@code{send} fails with @code{EPIPE}. -@end table - -This function is defined as a cancellation point in multi-threaded -programs, so one has to be prepared for this and make sure that -allocated resources (like memory, file descriptors, semaphores or -whatever) are freed even if the thread is canceled. -@c @xref{pthread_cleanup_push}, for a method how to do this. -@end deftypefun - -@node Receiving Data -@subsubsection Receiving Data - -@pindex sys/socket.h -The @code{recv} function is declared in the header file -@file{sys/socket.h}. If your @var{flags} argument is zero, you can -just as well use @code{read} instead of @code{recv}; see @ref{I/O -Primitives}. - -@comment sys/socket.h -@comment BSD -@deftypefun ssize_t recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{recv} function is like @code{read}, but with the additional -flags @var{flags}. The possible values of @var{flags} are described -in @ref{Socket Data Options}. - -If nonblocking mode is set for @var{socket}, and no data are available to -be read, @code{recv} fails immediately rather than waiting. @xref{File -Status Flags}, for information about nonblocking mode. - -This function returns the number of bytes received, or @code{-1} on failure. -The following @code{errno} error conditions are defined for this function: - -@table @code -@item EBADF -The @var{socket} argument is not a valid file descriptor. - -@item ENOTSOCK -The descriptor @var{socket} is not a socket. - -@item EWOULDBLOCK -Nonblocking mode has been set on the socket, and the read operation -would block. (Normally, @code{recv} blocks until there is input -available to be read.) - -@item EINTR -The operation was interrupted by a signal before any data was read. -@xref{Interrupted Primitives}. - -@item ENOTCONN -You never connected this socket. -@end table - -This function is defined as a cancellation point in multi-threaded -programs, so one has to be prepared for this and make sure that -allocated resources (like memory, file descriptors, semaphores or -whatever) are freed even if the thread is canceled. -@c @xref{pthread_cleanup_push}, for a method how to do this. -@end deftypefun - -@node Socket Data Options -@subsubsection Socket Data Options - -@pindex sys/socket.h -The @var{flags} argument to @code{send} and @code{recv} is a bit -mask. You can bitwise-OR the values of the following macros together -to obtain a value for this argument. All are defined in the header -file @file{sys/socket.h}. - -@comment sys/socket.h -@comment BSD -@deftypevr Macro int MSG_OOB -Send or receive out-of-band data. @xref{Out-of-Band Data}. -@end deftypevr - -@comment sys/socket.h -@comment BSD -@deftypevr Macro int MSG_PEEK -Look at the data but don't remove it from the input queue. This is -only meaningful with input functions such as @code{recv}, not with -@code{send}. -@end deftypevr - -@comment sys/socket.h -@comment BSD -@deftypevr Macro int MSG_DONTROUTE -Don't include routing information in the message. This is only -meaningful with output operations, and is usually only of interest for -diagnostic or routing programs. We don't try to explain it here. -@end deftypevr - -@node Byte Stream Example -@subsection Byte Stream Socket Example - -Here is an example client program that makes a connection for a byte -stream socket in the Internet namespace. It doesn't do anything -particularly interesting once it has connected to the server; it just -sends a text string to the server and exits. - -This program uses @code{init_sockaddr} to set up the socket address; see -@ref{Inet Example}. - -@smallexample -@include inetcli.c.texi -@end smallexample - -@node Server Example -@subsection Byte Stream Connection Server Example - -The server end is much more complicated. Since we want to allow -multiple clients to be connected to the server at the same time, it -would be incorrect to wait for input from a single client by simply -calling @code{read} or @code{recv}. Instead, the right thing to do is -to use @code{select} (@pxref{Waiting for I/O}) to wait for input on -all of the open sockets. This also allows the server to deal with -additional connection requests. - -This particular server doesn't do anything interesting once it has -gotten a message from a client. It does close the socket for that -client when it detects an end-of-file condition (resulting from the -client shutting down its end of the connection). - -This program uses @code{make_socket} to set up the socket address; see -@ref{Inet Example}. - -@smallexample -@include inetsrv.c.texi -@end smallexample - -@node Out-of-Band Data -@subsection Out-of-Band Data - -@cindex out-of-band data -@cindex high-priority data -Streams with connections permit @dfn{out-of-band} data that is -delivered with higher priority than ordinary data. Typically the -reason for sending out-of-band data is to send notice of an -exceptional condition. To send out-of-band data use -@code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending -Data}). - -Out-of-band data are received with higher priority because the -receiving process need not read it in sequence; to read the next -available out-of-band data, use @code{recv} with the @code{MSG_OOB} -flag (@pxref{Receiving Data}). Ordinary read operations do not read -out-of-band data; they read only ordinary data. - -@cindex urgent socket condition -When a socket finds that out-of-band data are on their way, it sends a -@code{SIGURG} signal to the owner process or process group of the -socket. You can specify the owner using the @code{F_SETOWN} command -to the @code{fcntl} function; see @ref{Interrupt Input}. You must -also establish a handler for this signal, as described in @ref{Signal -Handling}, in order to take appropriate action such as reading the -out-of-band data. - -Alternatively, you can test for pending out-of-band data, or wait -until there is out-of-band data, using the @code{select} function; it -can wait for an exceptional condition on the socket. @xref{Waiting -for I/O}, for more information about @code{select}. - -Notification of out-of-band data (whether with @code{SIGURG} or with -@code{select}) indicates that out-of-band data are on the way; the data -may not actually arrive until later. If you try to read the -out-of-band data before it arrives, @code{recv} fails with an -@code{EWOULDBLOCK} error. - -Sending out-of-band data automatically places a ``mark'' in the stream -of ordinary data, showing where in the sequence the out-of-band data -``would have been''. This is useful when the meaning of out-of-band -data is ``cancel everything sent so far''. Here is how you can test, -in the receiving process, whether any ordinary data was sent before -the mark: - -@smallexample -success = ioctl (socket, SIOCATMARK, &atmark); -@end smallexample - -The @code{integer} variable @var{atmark} is set to a nonzero value if -the socket's read pointer has reached the ``mark''. - -@c Posix 1.g specifies sockatmark for this ioctl. sockatmark is not -@c implemented yet. - -Here's a function to discard any ordinary data preceding the -out-of-band mark: - -@smallexample -int -discard_until_mark (int socket) -@{ - while (1) - @{ - /* @r{This is not an arbitrary limit; any size will do.} */ - char buffer[1024]; - int atmark, success; - - /* @r{If we have reached the mark, return.} */ - success = ioctl (socket, SIOCATMARK, &atmark); - if (success < 0) - perror ("ioctl"); - if (result) - return; - - /* @r{Otherwise, read a bunch of ordinary data and discard it.} - @r{This is guaranteed not to read past the mark} - @r{if it starts before the mark.} */ - success = read (socket, buffer, sizeof buffer); - if (success < 0) - perror ("read"); - @} -@} -@end smallexample - -If you don't want to discard the ordinary data preceding the mark, you -may need to read some of it anyway, to make room in internal system -buffers for the out-of-band data. If you try to read out-of-band data -and get an @code{EWOULDBLOCK} error, try reading some ordinary data -(saving it so that you can use it when you want it) and see if that -makes room. Here is an example: - -@smallexample -struct buffer -@{ - char *buf; - int size; - struct buffer *next; -@}; - -/* @r{Read the out-of-band data from SOCKET and return it} - @r{as a `struct buffer', which records the address of the data} - @r{and its size.} - - @r{It may be necessary to read some ordinary data} - @r{in order to make room for the out-of-band data.} - @r{If so, the ordinary data are saved as a chain of buffers} - @r{found in the `next' field of the value.} */ - -struct buffer * -read_oob (int socket) -@{ - struct buffer *tail = 0; - struct buffer *list = 0; - - while (1) - @{ - /* @r{This is an arbitrary limit.} - @r{Does anyone know how to do this without a limit?} */ -#define BUF_SZ 1024 - char *buf = (char *) xmalloc (BUF_SZ); - int success; - int atmark; - - /* @r{Try again to read the out-of-band data.} */ - success = recv (socket, buf, BUF_SZ, MSG_OOB); - if (success >= 0) - @{ - /* @r{We got it, so return it.} */ - struct buffer *link - = (struct buffer *) xmalloc (sizeof (struct buffer)); - link->buf = buf; - link->size = success; - link->next = list; - return link; - @} - - /* @r{If we fail, see if we are at the mark.} */ - success = ioctl (socket, SIOCATMARK, &atmark); - if (success < 0) - perror ("ioctl"); - if (atmark) - @{ - /* @r{At the mark; skipping past more ordinary data cannot help.} - @r{So just wait a while.} */ - sleep (1); - continue; - @} - - /* @r{Otherwise, read a bunch of ordinary data and save it.} - @r{This is guaranteed not to read past the mark} - @r{if it starts before the mark.} */ - success = read (socket, buf, BUF_SZ); - if (success < 0) - perror ("read"); - - /* @r{Save this data in the buffer list.} */ - @{ - struct buffer *link - = (struct buffer *) xmalloc (sizeof (struct buffer)); - link->buf = buf; - link->size = success; - - /* @r{Add the new link to the end of the list.} */ - if (tail) - tail->next = link; - else - list = link; - tail = link; - @} - @} -@} -@end smallexample - -@node Datagrams -@section Datagram Socket Operations - -@cindex datagram socket -This section describes how to use communication styles that don't use -connections (styles @code{SOCK_DGRAM} and @code{SOCK_RDM}). Using -these styles, you group data into packets and each packet is an -independent communication. You specify the destination for each -packet individually. - -Datagram packets are like letters: you send each one independently -with its own destination address, and they may arrive in the wrong -order or not at all. - -The @code{listen} and @code{accept} functions are not allowed for -sockets using connectionless communication styles. - -@menu -* Sending Datagrams:: Sending packets on a datagram socket. -* Receiving Datagrams:: Receiving packets on a datagram socket. -* Datagram Example:: An example program: packets sent over a - datagram socket in the local namespace. -* Example Receiver:: Another program, that receives those packets. -@end menu - -@node Sending Datagrams -@subsection Sending Datagrams -@cindex sending a datagram -@cindex transmitting datagrams -@cindex datagrams, transmitting - -@pindex sys/socket.h -The normal way of sending data on a datagram socket is by using the -@code{sendto} function, declared in @file{sys/socket.h}. - -You can call @code{connect} on a datagram socket, but this only -specifies a default destination for further data transmission on the -socket. When a socket has a default destination you can use -@code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O -Primitives}) to send a packet there. You can cancel the default -destination by calling @code{connect} using an address format of -@code{AF_UNSPEC} in the @var{addr} argument. @xref{Connecting}, for -more information about the @code{connect} function. - -@comment sys/socket.h -@comment BSD -@deftypefun ssize_t sendto (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{sendto} function transmits the data in the @var{buffer} -through the socket @var{socket} to the destination address specified -by the @var{addr} and @var{length} arguments. The @var{size} argument -specifies the number of bytes to be transmitted. - -The @var{flags} are interpreted the same way as for @code{send}; see -@ref{Socket Data Options}. - -The return value and error conditions are also the same as for -@code{send}, but you cannot rely on the system to detect errors and -report them; the most common error is that the packet is lost or there -is no-one at the specified address to receive it, and the operating -system on your machine usually does not know this. - -It is also possible for one call to @code{sendto} to report an error -owing to a problem related to a previous call. - -This function is defined as a cancellation point in multi-threaded -programs, so one has to be prepared for this and make sure that -allocated resources (like memory, file descriptors, semaphores or -whatever) are freed even if the thread is canceled. -@c @xref{pthread_cleanup_push}, for a method how to do this. -@end deftypefun - -@node Receiving Datagrams -@subsection Receiving Datagrams -@cindex receiving datagrams - -The @code{recvfrom} function reads a packet from a datagram socket and -also tells you where it was sent from. This function is declared in -@file{sys/socket.h}. - -@comment sys/socket.h -@comment BSD -@deftypefun ssize_t recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{recvfrom} function reads one packet from the socket -@var{socket} into the buffer @var{buffer}. The @var{size} argument -specifies the maximum number of bytes to be read. - -If the packet is longer than @var{size} bytes, then you get the first -@var{size} bytes of the packet and the rest of the packet is lost. -There's no way to read the rest of the packet. Thus, when you use a -packet protocol, you must always know how long a packet to expect. - -The @var{addr} and @var{length-ptr} arguments are used to return the -address where the packet came from. @xref{Socket Addresses}. For a -socket in the local domain the address information won't be meaningful, -since you can't read the address of such a socket (@pxref{Local -Namespace}). You can specify a null pointer as the @var{addr} argument -if you are not interested in this information. - -The @var{flags} are interpreted the same way as for @code{recv} -(@pxref{Socket Data Options}). The return value and error conditions -are also the same as for @code{recv}. - -This function is defined as a cancellation point in multi-threaded -programs, so one has to be prepared for this and make sure that -allocated resources (like memory, file descriptors, semaphores or -whatever) are freed even if the thread is canceled. -@c @xref{pthread_cleanup_push}, for a method how to do this. -@end deftypefun - -You can use plain @code{recv} (@pxref{Receiving Data}) instead of -@code{recvfrom} if you don't need to find out who sent the packet -(either because you know where it should come from or because you -treat all possible senders alike). Even @code{read} can be used if -you don't want to specify @var{flags} (@pxref{I/O Primitives}). - -@ignore -@c sendmsg and recvmsg are like readv and writev in that they -@c use a series of buffers. It's not clear this is worth -@c supporting or that we support them. -@c !!! they can do more; it is hairy - -@comment sys/socket.h -@comment BSD -@deftp {Data Type} {struct msghdr} -@end deftp - -@comment sys/socket.h -@comment BSD -@deftypefun ssize_t sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} - -This function is defined as a cancellation point in multi-threaded -programs, so one has to be prepared for this and make sure that -allocated resources (like memory, files descriptors, semaphores or -whatever) are freed even if the thread is cancel. -@c @xref{pthread_cleanup_push}, for a method how to do this. -@end deftypefun - -@comment sys/socket.h -@comment BSD -@deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} - -This function is defined as a cancellation point in multi-threaded -programs, so one has to be prepared for this and make sure that -allocated resources (like memory, files descriptors, semaphores or -whatever) are freed even if the thread is canceled. -@c @xref{pthread_cleanup_push}, for a method how to do this. -@end deftypefun -@end ignore - -@node Datagram Example -@subsection Datagram Socket Example - -Here is a set of example programs that send messages over a datagram -stream in the local namespace. Both the client and server programs use -the @code{make_named_socket} function that was presented in @ref{Local -Socket Example}, to create and name their sockets. - -First, here is the server program. It sits in a loop waiting for -messages to arrive, bouncing each message back to the sender. -Obviously this isn't a particularly useful program, but it does show -the general ideas involved. - -@smallexample -@include filesrv.c.texi -@end smallexample - -@node Example Receiver -@subsection Example of Reading Datagrams - -Here is the client program corresponding to the server above. - -It sends a datagram to the server and then waits for a reply. Notice -that the socket for the client (as well as for the server) in this -example has to be given a name. This is so that the server can direct -a message back to the client. Since the socket has no associated -connection state, the only way the server can do this is by -referencing the name of the client. - -@smallexample -@include filecli.c.texi -@end smallexample - -Keep in mind that datagram socket communications are unreliable. In -this example, the client program waits indefinitely if the message -never reaches the server or if the server's response never comes -back. It's up to the user running the program to kill and restart -it if desired. A more automatic solution could be to use -@code{select} (@pxref{Waiting for I/O}) to establish a timeout period -for the reply, and in case of timeout either re-send the message or -shut down the socket and exit. - -@node Inetd -@section The @code{inetd} Daemon - -We've explained above how to write a server program that does its own -listening. Such a server must already be running in order for anyone -to connect to it. - -Another way to provide a service on an Internet port is to let the daemon -program @code{inetd} do the listening. @code{inetd} is a program that -runs all the time and waits (using @code{select}) for messages on a -specified set of ports. When it receives a message, it accepts the -connection (if the socket style calls for connections) and then forks a -child process to run the corresponding server program. You specify the -ports and their programs in the file @file{/etc/inetd.conf}. - -@menu -* Inetd Servers:: -* Configuring Inetd:: -@end menu - -@node Inetd Servers -@subsection @code{inetd} Servers - -Writing a server program to be run by @code{inetd} is very simple. Each time -someone requests a connection to the appropriate port, a new server -process starts. The connection already exists at this time; the -socket is available as the standard input descriptor and as the -standard output descriptor (descriptors 0 and 1) in the server -process. Thus the server program can begin reading and writing data -right away. Often the program needs only the ordinary I/O facilities; -in fact, a general-purpose filter program that knows nothing about -sockets can work as a byte stream server run by @code{inetd}. - -You can also use @code{inetd} for servers that use connectionless -communication styles. For these servers, @code{inetd} does not try to accept -a connection since no connection is possible. It just starts the -server program, which can read the incoming datagram packet from -descriptor 0. The server program can handle one request and then -exit, or you can choose to write it to keep reading more requests -until no more arrive, and then exit. You must specify which of these -two techniques the server uses when you configure @code{inetd}. - -@node Configuring Inetd -@subsection Configuring @code{inetd} - -The file @file{/etc/inetd.conf} tells @code{inetd} which ports to listen to -and what server programs to run for them. Normally each entry in the -file is one line, but you can split it onto multiple lines provided -all but the first line of the entry start with whitespace. Lines that -start with @samp{#} are comments. - -Here are two standard entries in @file{/etc/inetd.conf}: - -@smallexample -ftp stream tcp nowait root /libexec/ftpd ftpd -talk dgram udp wait root /libexec/talkd talkd -@end smallexample - -An entry has this format: - -@smallexample -@var{service} @var{style} @var{protocol} @var{wait} @var{username} @var{program} @var{arguments} -@end smallexample - -The @var{service} field says which service this program provides. It -should be the name of a service defined in @file{/etc/services}. -@code{inetd} uses @var{service} to decide which port to listen on for -this entry. - -The fields @var{style} and @var{protocol} specify the communication -style and the protocol to use for the listening socket. The style -should be the name of a communication style, converted to lower case -and with @samp{SOCK_} deleted---for example, @samp{stream} or -@samp{dgram}. @var{protocol} should be one of the protocols listed in -@file{/etc/protocols}. The typical protocol names are @samp{tcp} for -byte stream connections and @samp{udp} for unreliable datagrams. - -The @var{wait} field should be either @samp{wait} or @samp{nowait}. -Use @samp{wait} if @var{style} is a connectionless style and the -server, once started, handles multiple requests as they come in. -Use @samp{nowait} if @code{inetd} should start a new process for each message -or request that comes in. If @var{style} uses connections, then -@var{wait} @strong{must} be @samp{nowait}. - -@var{user} is the user name that the server should run as. @code{inetd} runs -as root, so it can set the user ID of its children arbitrarily. It's -best to avoid using @samp{root} for @var{user} if you can; but some -servers, such as Telnet and FTP, read a username and password -themselves. These servers need to be root initially so they can log -in as commanded by the data coming over the network. - -@var{program} together with @var{arguments} specifies the command to -run to start the server. @var{program} should be an absolute file -name specifying the executable file to run. @var{arguments} consists -of any number of whitespace-separated words, which become the -command-line arguments of @var{program}. The first word in -@var{arguments} is argument zero, which should by convention be the -program name itself (sans directories). - -If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the -file and obey its new contents by sending the @code{inetd} process the -@code{SIGHUP} signal. You'll have to use @code{ps} to determine the -process ID of the @code{inetd} process as it is not fixed. - -@c !!! could document /etc/inetd.sec - -@node Socket Options -@section Socket Options -@cindex socket options - -This section describes how to read or set various options that modify -the behavior of sockets and their underlying communications protocols. - -@cindex level, for socket options -@cindex socket option level -When you are manipulating a socket option, you must specify which -@dfn{level} the option pertains to. This describes whether the option -applies to the socket interface, or to a lower-level communications -protocol interface. - -@menu -* Socket Option Functions:: The basic functions for setting and getting - socket options. -* Socket-Level Options:: Details of the options at the socket level. -@end menu - -@node Socket Option Functions -@subsection Socket Option Functions - -@pindex sys/socket.h -Here are the functions for examining and modifying socket options. -They are declared in @file{sys/socket.h}. - -@comment sys/socket.h -@comment BSD -@deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{getsockopt} function gets information about the value of -option @var{optname} at level @var{level} for socket @var{socket}. - -The option value is stored in the buffer that @var{optval} points to. -Before the call, you should supply in @code{*@var{optlen-ptr}} the -size of this buffer; on return, it contains the number of bytes of -information actually stored in the buffer. - -Most options interpret the @var{optval} buffer as a single @code{int} -value. - -The actual return value of @code{getsockopt} is @code{0} on success -and @code{-1} on failure. The following @code{errno} error conditions -are defined: - -@table @code -@item EBADF -The @var{socket} argument is not a valid file descriptor. - -@item ENOTSOCK -The descriptor @var{socket} is not a socket. - -@item ENOPROTOOPT -The @var{optname} doesn't make sense for the given @var{level}. -@end table -@end deftypefun - -@comment sys/socket.h -@comment BSD -@deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, const void *@var{optval}, socklen_t @var{optlen}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function is used to set the socket option @var{optname} at level -@var{level} for socket @var{socket}. The value of the option is passed -in the buffer @var{optval} of size @var{optlen}. - -@c Argh. -zw -@iftex -@hfuzz 6pt -The return value and error codes for @code{setsockopt} are the same as -for @code{getsockopt}. -@end iftex -@ifinfo -The return value and error codes for @code{setsockopt} are the same as -for @code{getsockopt}. -@end ifinfo - -@end deftypefun - -@node Socket-Level Options -@subsection Socket-Level Options - -@comment sys/socket.h -@comment BSD -@deftypevr Constant int SOL_SOCKET -Use this constant as the @var{level} argument to @code{getsockopt} or -@code{setsockopt} to manipulate the socket-level options described in -this section. -@end deftypevr - -@pindex sys/socket.h -@noindent -Here is a table of socket-level option names; all are defined in the -header file @file{sys/socket.h}. - -@vtable @code -@comment sys/socket.h -@comment BSD -@item SO_DEBUG -@c Extra blank line here makes the table look better. - -This option toggles recording of debugging information in the underlying -protocol modules. The value has type @code{int}; a nonzero value means -``yes''. -@c !!! should say how this is used -@c OK, anyone who knows, please explain. - -@comment sys/socket.h -@comment BSD -@item SO_REUSEADDR -This option controls whether @code{bind} (@pxref{Setting Address}) -should permit reuse of local addresses for this socket. If you enable -this option, you can actually have two sockets with the same Internet -port number; but the system won't allow you to use the two -identically-named sockets in a way that would confuse the Internet. The -reason for this option is that some higher-level Internet protocols, -including FTP, require you to keep reusing the same port number. - -The value has type @code{int}; a nonzero value means ``yes''. - -@comment sys/socket.h -@comment BSD -@item SO_KEEPALIVE -This option controls whether the underlying protocol should -periodically transmit messages on a connected socket. If the peer -fails to respond to these messages, the connection is considered -broken. The value has type @code{int}; a nonzero value means -``yes''. - -@comment sys/socket.h -@comment BSD -@item SO_DONTROUTE -This option controls whether outgoing messages bypass the normal -message routing facilities. If set, messages are sent directly to the -network interface instead. The value has type @code{int}; a nonzero -value means ``yes''. - -@comment sys/socket.h -@comment BSD -@item SO_LINGER -This option specifies what should happen when the socket of a type -that promises reliable delivery still has untransmitted messages when -it is closed; see @ref{Closing a Socket}. The value has type -@code{struct linger}. - -@comment sys/socket.h -@comment BSD -@deftp {Data Type} {struct linger} -This structure type has the following members: - -@table @code -@item int l_onoff -This field is interpreted as a boolean. If nonzero, @code{close} -blocks until the data are transmitted or the timeout period has expired. - -@item int l_linger -This specifies the timeout period, in seconds. -@end table -@end deftp - -@comment sys/socket.h -@comment BSD -@item SO_BROADCAST -This option controls whether datagrams may be broadcast from the socket. -The value has type @code{int}; a nonzero value means ``yes''. - -@comment sys/socket.h -@comment BSD -@item SO_OOBINLINE -If this option is set, out-of-band data received on the socket is -placed in the normal input queue. This permits it to be read using -@code{read} or @code{recv} without specifying the @code{MSG_OOB} -flag. @xref{Out-of-Band Data}. The value has type @code{int}; a -nonzero value means ``yes''. - -@comment sys/socket.h -@comment BSD -@item SO_SNDBUF -This option gets or sets the size of the output buffer. The value is a -@code{size_t}, which is the size in bytes. - -@comment sys/socket.h -@comment BSD -@item SO_RCVBUF -This option gets or sets the size of the input buffer. The value is a -@code{size_t}, which is the size in bytes. - -@comment sys/socket.h -@comment GNU -@item SO_STYLE -@comment sys/socket.h -@comment BSD -@itemx SO_TYPE -This option can be used with @code{getsockopt} only. It is used to -get the socket's communication style. @code{SO_TYPE} is the -historical name, and @code{SO_STYLE} is the preferred name in GNU. -The value has type @code{int} and its value designates a communication -style; see @ref{Communication Styles}. - -@comment sys/socket.h -@comment BSD -@item SO_ERROR -@c Extra blank line here makes the table look better. - -This option can be used with @code{getsockopt} only. It is used to reset -the error status of the socket. The value is an @code{int}, which represents -the previous error status. -@c !!! what is "socket error status"? this is never defined. -@end vtable - -@node Networks Database -@section Networks Database -@cindex networks database -@cindex converting network number to network name -@cindex converting network name to network number - -@pindex /etc/networks -@pindex netdb.h -Many systems come with a database that records a list of networks known -to the system developer. This is usually kept either in the file -@file{/etc/networks} or in an equivalent from a name server. This data -base is useful for routing programs such as @code{route}, but it is not -useful for programs that simply communicate over the network. We -provide functions to access this database, which are declared in -@file{netdb.h}. - -@comment netdb.h -@comment BSD -@deftp {Data Type} {struct netent} -This data type is used to represent information about entries in the -networks database. It has the following members: - -@table @code -@item char *n_name -This is the ``official'' name of the network. - -@item char **n_aliases -These are alternative names for the network, represented as a vector -of strings. A null pointer terminates the array. - -@item int n_addrtype -This is the type of the network number; this is always equal to -@code{AF_INET} for Internet networks. - -@item unsigned long int n_net -This is the network number. Network numbers are returned in host -byte order; see @ref{Byte Order}. -@end table -@end deftp - -Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search -the networks database for information about a specific network. The -information is returned in a statically-allocated structure; you must -copy the information if you need to save it. - -@comment netdb.h -@comment BSD -@deftypefun {struct netent *} getnetbyname (const char *@var{name}) -@safety{@prelim{}@mtunsafe{@mtasurace{:netbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c getnetbyname =~ getpwuid @mtasurace:netbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c malloc dup @ascuheap @acsmem -@c getnetbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c -@c getnetbyname_r =~ getpwuid_r @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c no nscd support -@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.l -> _nss_*_getnetbyname_r @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -The @code{getnetbyname} function returns information about the network -named @var{name}. It returns a null pointer if there is no such -network. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun {struct netent *} getnetbyaddr (uint32_t @var{net}, int @var{type}) -@safety{@prelim{}@mtunsafe{@mtasurace{:netbyaddr} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c getnetbyaddr =~ getpwuid @mtasurace:netbyaddr @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c malloc dup @ascuheap @acsmem -@c getnetbyaddr_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c -@c getnetbyaddr_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c no nscd support -@c nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.l -> _nss_*_getnetbyaddr_r @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -The @code{getnetbyaddr} function returns information about the network -of type @var{type} with number @var{net}. You should specify a value of -@code{AF_INET} for the @var{type} argument for Internet networks. - -@code{getnetbyaddr} returns a null pointer if there is no such -network. -@end deftypefun - -You can also scan the networks database using @code{setnetent}, -@code{getnetent} and @code{endnetent}. Be careful when using these -functions because they are not reentrant. - -@comment netdb.h -@comment BSD -@deftypefun void setnetent (int @var{stayopen}) -@safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c setnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_setent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c setup(nss_networks_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *lookup_fct = nss_networks_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:netent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_unlock dup @aculock -This function opens and rewinds the networks database. - -If the @var{stayopen} argument is nonzero, this sets a flag so that -subsequent calls to @code{getnetbyname} or @code{getnetbyaddr} will -not close the database (as they usually would). This makes for more -efficiency if you call those functions several times, by avoiding -reopening the database for each call. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun {struct netent *} getnetent (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtasurace{:netentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c getnetent @mtasurace:netent @mtasurace:netentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_getent(getnetent_r) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c malloc dup @ascuheap @acsmem -@c *func = getnetent_r dup @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c realloc dup @ascuheap @acsmem -@c free dup @ascuheap @acsmem -@c libc_lock_unlock dup @aculock -@c -@c getnetent_r @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock dup @asulock @aculock -@c nss_getent_r(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:servent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *sfct.f @mtasurace:netent @ascuplugin -@c libc_lock_unlock dup @aculock -This function returns the next entry in the networks database. It -returns a null pointer if there are no more entries. -@end deftypefun - -@comment netdb.h -@comment BSD -@deftypefun void endnetent (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c endnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_lock @asulock @aculock -@c nss_endent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd -@c setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c *fct.f @mtasurace:netent @ascuplugin -@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem -@c libc_lock_unlock @aculock -This function closes the networks database. -@end deftypefun |