libsocket 0.8.0 Manual ********************** libsocket 0.8.0 Manual Copyright (C) 1999-2002 by Richard Dawe and Alain Magloire Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License" (*note GNU Free Documentation License::). Introduction ************ libsocket: Copyright (C) 1997, 1998 by Indrek Mandre Copyright (C) 1997-2002 by Richard Dawe Portions of libsocket: * Copyright (C) 1985-1993 Regents of the University of California; * Copyright (C) 1991, 1992 Free Software Foundation Inc.; * Copyright (C) 1997, 1998 by the RegDos Group. libsocket is distributed under the terms of the GNU Library General Public License (the GNU LGPL) (*note License::). Please read the license before using libsocket. What is libsocket? ================== libsocket is a BSD sockets library for DJGPP. It provides DJGPP programs with TCP/IP networking as well as Unix domain sockets, a form of Interprocess Communication (IPC). "BSD sockets" are the _de facto_ programming interface for networking on Unix systems. Programs written to this interface can be ported to many platforms. The Windows network programming interface, "Winsock", is derived from BSD sockets. libsocket supports the following operating systems: * Windows 3.x * Windows '95 * Windows '98 * Windows NT - Unix domain sockets only; no TCP/IP networking. Please note that libsocket has not been tested under Windows 3.x for a long time. It should work, since it uses mostly the same methods as Windows '95. Any feedback would be appreciated here. Please also note that libsocket has not been tested under Windows '98 during development, since the maintainer does not have Windows '98. It has been reported variously to work/not work. How to get started ================== * Install libsocket (*note Installation::); * Configure libsocket (*note Configuration::); * Check libsocket is configured correctly using the demo programs `demo/diag.exe' and `demo/httpget.exe'. "diag" lists libsocket's configuration (a diagnostic tool); "httpget" retrieves the specified URL from the web and dumps it to the screen, e.g.: httpget http://www.slashdot.org/ * Browse the function reference (*note Alphabetical List::). The libsocket binary and source distributiosn also contains "Beej's Guide to Network Programming" in HTML - if you are new to BSD sockets programming, this will help greatly. Beej's guide can be found in `contrib/ls080/doc/beejng'. You can jump directly to functions in the alphabetical index: info libsocket alpha socket What to do when things go wrong =============================== Firstly check that you haven't encountered one of the known bugs (*note Known Bugs::). You should also read the release notes (if any) that came with libsocket. Secondly check that there isn't any news at the libsocket home page (http://libsocket.tsx.org/). More directly: * `http://www.phekda.freeserve.co.uk/richdawe/lsck/lsck_new.htm' * `http://libsocket.vip.ee/lsck_new.htm' If this doesn't help, please ask a question in the DJGPP newsgroup (`mailto:djgpp@delorie.com' or `news:comp.os.msdos.djgpp') _and_ the libsocket mailing list (mailto:libsocket@egroups.com). Please include the output of `demo/diag.exe' and your libsocket configuration files (*note Configuration::). Contact Details =============== libsocket is maintained by Richard Dawe (mailto:richdawe@bigfoot.com): `http://www.bigfoot.com/~richdawe/' Functional Categories ********************* io functions ============ libsocket functions =================== resolver functions ================== rexec functions =============== socket functions ================ Alphabetical List ***************** accept ====== Syntax ------ #include #include int accept (int s, struct sockaddr *address, size_t *addresslen); Description ----------- The `accept()' function returns the first completed connection from the the pending connection queue form a listening socket. The parameter S is a socket descriptor that has been created with `socket()', bound to a local socket-address with `bind()' and is listening for connections after `listen()'. The `accept()' will return a brand new socket descriptor. If the socket is not marked non-blocking, `accept()' blocks the caller until a connection is present. If marked non-blocking and no pending connections are present it returns -1 and set ERRNO to EWOULDBLOCK. If ADDRESS is not NULL it specifies a buffer in which to return the socket address, the ADDRESSLEN is a value-result that specified the amount of space for ADDRESS. On return when ADDRESSLEN will hold the size written to ADDRESS. Return Value ------------ On successful completion the function returns the descriptor of the accepted socket. Otherwise, a value of -1, and ERRNO is set. `EBADF' The parameter s is not valid. `ECONNABORTED' The peer has closed the connection. `EINTR' The call was interrupted by a signal. `EINVAL' The socket was not in the listening state. `EMFILE' The per-process descriptor table is full. `ENFILE' The system file table is full. `ENOBUFS' Insufficient resources. `ENOTSOCK' The descriptor is not a socket. `EOPNOTSUPP' The interface does not support `accept()' `EWOULDBLOCK' The socket is marked non-blocking and no connections are present. Portability ----------- POSIX, Unix98 Example ------- bind ==== Syntax ------ #include #include int bind (int s, const struct sockaddr *address, size_t addresslen); Description ----------- The `bind()' function assigns a local socket-address to socket S that has no local socket-address assigned. When a socket is created with `socket()' it is associated with a specific protocol from the protocol and in the case of libsocket also an interface, but has no local socket-address assigned. This function requests that the local socket-address ADDRESS be assigned to it. The format of the socket-address depends on the address family, for example `AF_INET', `AF_UNIX' (also known as `AF_LOCAL'). Return Value ------------ On successful completion the function returns 0. Otherwise, a value of -1, and ERRNO is set. `EACCESS' The requested socket-address is reserved, and the calling process does not have the appropriate privileges. `EADDRINUSE' The specified socket-address is already in use. `EADDRNOTAVAIL' THe specifeid socket-address is not available from the local machine. `EBADF' The parameter s is not valid. `EINVAL' The socket is already associated with a local socket-address or the parameter is not the size of a valid socket-address for the specified address family. `ENOBUFS' Insufficient resources. `ENOTSOCK' The descriptor is not a socket. Portability ----------- POSIX, Unix98 Example ------- connect ======= Syntax ------ #include #include int connect (int s, struct sockaddr *serv_addr, size_t *addrlen); Description ----------- If S refers to a stream socket (`SOCK_STREAM'), `connect()' will attempt to establish a connection to the specified destination address. If S refers to a datagram socket (`SOCK_DGRAM'), `connect()' associates a default destination address for use by `send()' and `sendto()'. It also limits `recv()' calls to receiving from this address, rather than the default of any. To remove the association, call `connect()' with an invalid address, e.g. a null address (0.0.0.0). Return Value ------------ On successful completion the function returns zero. Otherwise, a value of -1 is returned and ERRNO is set appropriately. `EBADF' The parameter S is not valid. `EFAULT' The address data cannot be accessed. `ENOTSOCK' The descriptor is not a socket. `EISCONN' The socket is already connected. `ECONNREFUSED' The connection was refused by the server. `ETIMEDOUT' The connection timed out. `ENETUNREACH' The network is unreachable. `EADDRINUSE' The address is already in use. `EINTR' The call was interrupted by a signal. `EOPNOTSUPP' The interface does not support `connect()'. `EINPROGRESS' The socket is non-blocking and the connection cannot be made immediately. On completion, the socket can be selected for writing (*note select: (libc)select.). Use `getsockopt()' to read the option `SO_ERROR' at level `SOL_SOCKET' to check if the call completed successfully - `SO_ERROR''s value will be 0 on success, or an ERRNO value otherwise. `EALREADY' The socket is non-blocking and a previous `connect()' request is completing. Portability ----------- POSIX, Unix98 Example ------- dn_comp ======= Syntax ------ #include int dn_comp (unsigned char *exp_dn, unsigned char *comp_dn, int length, unsigned char **dnptrs, unsigned char *exp_dn, unsigned char **lastdnptr); Description ----------- The `dn_comp()' function compresses the domain name EXP_DN and stores it in the buffer COMP_DN of length `length'. The compression uses an array of pointers `dnptrs' to previously compressed names in the current message. The first pointer points to the beginning of the message and the list ends with NULL. The limit of the array is specified by LASTDNPTR. If DNPTR is NULL, domain names are not compressed. If LASTDNPTR is NULL, the list of labels is not updated. *Note dn_expand::. Return Value ------------ The `dn_comp()' function returns the length of the compressed name, or -1 if an error occurs. Portability ----------- This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. Example ------- dn_expand ========= Syntax ------ #include int dn_expand (unsigned char *msg, unsigned char *eomorig, unsigned char *comp_dn, unsigned char *exp_dn, int length); Description ----------- The `dn_expand()' function expands the compressed domain name COMP_DN to a full domain name, which is placed in the buffer EXP_DN of size LENGTH. The compressed name is contained in a query or reply message, and MSG points to the beginning of the message. *Note dn_comp::. Return Value ------------ The `dn_expand()' function returns the length of the compressed name, or -1 if an error occurs. Portability ----------- This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. Example ------- endhostent ========== Syntax ------ #include void endhostent (void); Description ----------- The `endhostent()' function ends the use of a TCP connection for name server queries. Return Values ------------- None Portability ----------- Unix98 Example ------- endnetent ========= Syntax ------ #include void endnetent (void); Description ----------- The `endnetent()' function closes `networks' (*note networks::). Return Values ------------- None Portability ----------- Unix98 Example ------- endprotoent =========== Syntax ------ #include void endprotoent (void); Description ----------- The `endprotoent()' function closes the `protocols' file (*note protocols::). Return Values ------------- None Portability ----------- Unix98 Example ------- endservent ========== Syntax ------ #include void endservent (void); Description ----------- The `endservent()' function closes `services' (*note services::). Return Values ------------- None Portability ----------- Unix98 Example ------- getdomainname ============= Syntax ------ #include int getdomainname (char *name, size_t len); Description ----------- This function is used to access the domain name. The domain name can be set by `setdomainname()' (*note setdomainname::). The domain name is the last component of the host name (*note gethostname::). Return Value ------------ On success, zero is returned. On error, -1 is returned, and ERRNO is set appropriately. `EINVAL' NAME points to `NULL' or NAME is longer than LEN. Portability ----------- not POSIX, not Unix98 This function is defined in `unistd.h' on Linux. Example ------- gethostbyaddr ============= Syntax ------ #include #include extern int h_errno; struct hostent *gethostbyaddr (const char *addr, int len, int type); Description ----------- The `gethostbyaddr()' function returns a structure of type `hostent' for the given host address ADDR of length LEN and address type TYPE. The only valid address type is currently AF_INET. The `hostent' structure is defined in the description of `gethostbyname()' (*note gethostbyname::). Return Values ------------- The `gethostbyaddr()' function return the `hostent' structure or a NULL pointer if an error occurs. On error, the `h_errno' variable holds an error number. `h_errno' can have the same values as for `gethostbyname()' (*note gethostbyname::). The `herror()' function will print an error message, based on the value of H_ERRNO (*note herror::). Portability ----------- Unix98 Example ------- gethostbyname ============= Syntax ------ #include extern int h_errno; struct hostent *gethostbyname (const char *name) Description ----------- The `gethostbyname()' function returns a structure of type `hostent' for the given host NAME. Here NAME is either a host name, or an IPv4 address in standard dot notation, or an IPv6 address in colon (and possibly dot) notation. (See RFC 1884 for the description of IPv6 addresses.) If NAME doesn't end in a dot and the environment variable HOSTALIASES is set, the alias file pointed to by HOSTALIASES will first be searched for NAME. The current domain and its parents are searched unless NAME ends in a dot. The domain name queries carried out by `gethostbyname()' use a combination of any or all of: * the name server `named'; * a broken out line from `hosts' (*note hosts::); * the Network Information Service (NIS or YP)(1). depending upon the contents of the `order' line in host.conf (*note host.conf::). The default action is to query `hosts' (*note hosts::). The "hostent" structure is defined in `netdb.h' as follows: struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* host address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses */ } #define h_addr h_addr_list[0] /* for backward compatibility */ The members of the `hostent' structure are: `h_name' The official name of the host. `h_aliases' A zero-terminated array of alternative names for the host. `h_addrtype' The type of address; always AF_INET at present. `h_length' The length of the address in bytes. `h_addr_list' A zero-terminated array of network addresses for the host in network byte order. `h_addr' The first address in `h_addr_list' for backward compatibility. Return Values ------------- The `gethostbyname()' function returns a `hostent' structure or a NULL pointer if an error occurs. On error, the H_ERRNO variable holds an error number. The variable H_ERRNO can have the following values: `HOST_NOT_FOUND' The specified host is unknown. `NO_ADDRESS' The requested name is valid but does not have an IP address. `NO_RECOVERY' A non-recoverable name server error occurred. `TRY_AGAIN' A temporary error occurred on an authoritative name server. Try again later. The `herror()' function will print an error message, based on the value of H_ERRNO (*note herror::). Portability ----------- Unix98 Example ------- ---------- Footnotes ---------- (1) libsocket does not support this. gethostent ========== Syntax ------ #include struct hostent *gethostent (void); Description ----------- The `gethostent()' function reads the next line from the file `hosts' (*note hosts::) and returns a structure `hostent' containing the broken out fields from the line. The `hosts' file is opened if necessary. The `hostent' structure is defined in the description of `gethostbyname()' (*note gethostbyname::). Return Value ------------ The `gethostent()' function return the `hostent' structure, or a NULL pointer if an error occurs or the end of the file is reached. Portability ----------- Unix98 Example ------- gethostname =========== Syntax ------ #include int gethostname (char *name, size_t len); Description ----------- This function is used to access the host name of the current processor. The host name is set using `sethostname()' (*note sethostname::). The domain name component can be retrieved and set using `getdomainname()' and `setdomainname()' respectively (*note getdomainname::, *note setdomainname::). libsocket's implementation of `gethostname()' overrides DJGPP's implementation (*note gethostname: (libc)gethostname.). libsocket will fall back the DJGPP's implementation when it cannot find the host name from its additional sources. If a host name has not been set using `sethostname()', then it is determined in the following order: 1. from the environment variable `HOSTNAME'; 2. from libsocket's configuration file; 3. from any automatic configuration; 4. from DJGPP's original `gethostname()' implementation. Return value ------------ On success, zero is returned. On error, -1 is returned, and `errno' is set appropriately. Errors ------ `EINVAL' LEN is negative or smaller than the actual size. `EFAULT' NAME is an invalid address. Portability ----------- not POSIX, not Unix98 Example ------- getnetbyaddr ============ Syntax ------ #include struct netent *getnetbyaddr (long net, int type); Description ----------- The `getnetbyaddr()' function returns a `netent' structure for the line from `networks' (*note networks::) that matches the network number NET of type TYPE. The `netent' structure is defined in the description of `getnetbyname()' (*note getnetbyname::). Return Values ------------- The `getnetbyaddr()' function return the `netent' structure, or a NULL pointer if an error occurs or the end of the file is reached. Portability ----------- Unix98 Example ------- getnetbyname ============ Syntax ------ #include struct netent *getnetbyname (const char *name); Description ----------- The `getnetbyname()' function returns a `netent' structure for the line from `networks' (*note networks::) that matches the network NAME. The `netent' structure is defined in `netdb.h' as follows: struct netent { char *n_name; /* official network name */ char **n_aliases; /* alias list */ int n_addrtype; /* net address type */ unsigned long int n_net; /* network number */ } The members of the `netent' structure are: `n_name' The official name of the network. `n_aliases' A zero terminated list of alternative names for the network. `n_addrtype' The type of the network number; always AF_INET. `n_net' The network number in host byte order. Return Values ------------- The `getnetbyname()' function return the `netent' structure, or a NULL pointer if an error occurs or the end of the file is reached. Portability ----------- Unix98 Example ------- getnetent ========= Syntax ------ #include struct netent *getnetent(void); Description ----------- The `getnetent()' function reads the next line from the file `networks' (*note networks::) and returns a structure `netent' containing the broken out fields from the line. The `networks' file is opened if necessary. The `netent' structure is defined in the description of `getnetbyname()' (*note getnetbyname::). Return Values ------------- The `getnetent()' function return the `netent' structure, or a NULL pointer if an error occurs or the end of the file is reached. Portability ----------- Unix98 Example ------- getpeername =========== Syntax ------ #include int getpeername (int s, struct sockaddr *name, size_t *namelen); Description ----------- `getpeername()' returns the name of the peer connected to the socket S. NAMELEN should be set to the size of the space pointed to by NAME. On completion NAMELEN will contain the length of the address returned. If the buffer is too small, the address is truncated to fit. `getsockname()' returns the local name for the socket (*note getsockname::). Return Value ------------ On successful completion the function returns 0. Otherwise, a value of -1 is returned and ERRNO is set appropriately. `EBADF' S is not a valid file descriptor. `ENOTSOCK' S is not a socket. `ENOTCONN' The socket S is not connected. `ENOBUFS' There were not enough resources to complete this operation. `EFAULT' NAME could not be accessed. Portability ----------- POSIX, Unix98 Example ------- getprotobyname ============== Syntax ------ #include struct protoent *getprotobyname (const char *name); Description ----------- The `getprotobyname()' function returns a `protoent' structure for the line from `protocols' (*note protocols::) that matches the protocol name NAME. The `protoent' structure is defined in `netdb.h' as follows: struct protoent { char *p_name; /* official protocol name */ char **p_aliases; /* alias list */ int p_proto; /* protocol number */ } The members of the `protoent' structure are: `p_name' The official name of the protocol. `p_aliases' A zero terminated list of alternative names for the protocol. `p_proto' The protocol number. Return Values ------------- The `getprotobyname()' function returns the `protoent' structure, or a NULL pointer if an error occurs or the end of the file is reached. Portability ----------- Unix98 Example ------- getprotobynumber ================ Syntax ------ #include struct protoent *getprotobynumber (int proto); Description ----------- The `getprotobynumber()' function returns a `protoent' structure for the line from `protocols' (*note protocols::) that matches the protocol number NUMBER. The `protoent' structure is defined in the description of `getprotobyname()' (*note getprotobyname::). Return Values ------------- The `getprotobynumber()' function return the `protoent' structure, or a NULL pointer if an error occurs or the end of the file is reached. Portability ----------- Unix98 Example ------- getprotoent =========== Syntax ------ #include struct protoent *getprotoent (void); Description ----------- The `getprotoent()' function reads the next line from the file `protocols' (*note protocols::) and returns a structure `protoent' containing the broken out fields from the line. The `protocols' file is opened if necessary. The `protoent' structure is defined in the description of `getprotobyname()' (*note getprotobyname::). Return Values ------------- On successful completion the function returns a `protoent' structure, or a NULL pointer if an error occurs or the end of the file is reached. Portability ----------- Unix98 Example ------- getservbyname ============= Syntax ------ #include struct servent *getservbyname (const char *name, const char *proto); Description ----------- The `getservbyname()' function returns a `servent' structure for the line from `services' (*note services::) that matches the service NAME using protocol PROTO. The `servent' structure is defined in `netdb.h' as follows: struct servent { char *s_name; /* official service name */ char **s_aliases; /* alias list */ int s_port; /* port number */ char *s_proto; /* protocol to use */ } The members of the `servent' structure are: `s_name' The official name of the service. `s_aliases' A zero terminated list of alternative names for the service. `s_port' The port number for the service given in network byte order. `s_proto' The name of the protocol to use with this service. Return Values ------------- The `getservbyname()' function return the `servent' structure, or a NULL pointer if an error occurs or the end of the file is reached. Portability ----------- Unix98 Example ------- getservbyport ============= Syntax ------ #include struct servent *getservbyport (int port, const char *proto); Description ----------- The `getservbyport()' function returns a `servent' structure for the line from `services' (*note services::) that matches the port PORT given in network byte order using protocol PROTO. The `servent' structure is defined in the description of `getservbyname()' (*note getservbyname::). Return Values ------------- The `getservbyport()' function return the `servent' structure, or a NULL pointer if an error occurs or the end of the file is reached. Portability ----------- Unix98 Example ------- getservent ========== Syntax ------ #include struct servent *getservent (void); Description ----------- The `getservent()' function reads the next line from the file `services' (*note services::) and returns a structure `servent' containing the broken out fields from the line. The `services' file is opened if necessary. The `servent' structure is defined in the description of `getservbyname()' (*note getservbyname::). Return Values ------------- The `getservent()' function return the `servent' structure, or a NULL pointer if an error occurs or the end of the file is reached. Portability ----------- Unix98 Example ------- getsockname =========== Syntax ------ #include int getsockname (int s, struct sockaddr *name, size_t *namelen); Description ----------- `getsockname()' returns the local name of the socket S. NAMELEN should be set to the size of the space pointed to by NAME. On completion NAMELEN will contain the length of the address returned. If the buffer is too small, the address is truncated to fit. `getpeername()' returns the peer name for the socket (*note getpeername::). Return Value ------------ On successful completion the function returns 0. Otherwise, a value of -1 is returned and ERRNO is set appropriately. `EBADF' S is not a valid file descriptor. `ENOTSOCK' S is not a socket. `ENOBUFS' There were not enough resources to complete this operation. `EFAULT' NAME could not be accessed. Portability ----------- POSIX, Unix98 Example ------- getsockopt ========== Syntax ------ #include #include int getsockopt (int s, int level, int optname, void *optval, int *optlen); Description ----------- The `getsockopt()' function manipulates the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost socket level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, LEVEL is specified as `SOL_SOCKET'. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, LEVEL should be set to the protocol number of TCP, e.g. `IPPROTO_TCP' (*note getprotoent::). The parameters OPTVAL and OPTLEN are used to identify a buffer in which the value for the requested option(s) are to be returned. OPTLEN is a value-result parameter, initially containing the size of the buffer pointed to by OPTVAL, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, OPTVAL may be NULL. OPTNAME and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file `sys/socket.h' contains definitions for socket level options, described below. Options at other protocol levels vary in format and name. Most socket-level options utilize an `int' parameter for OPTVAL. `SO_LINGER' uses a `struct linger' parameter, defined in `sys/socket.h', which specifies the desired state of the option and the linger interval (see below). `SO_SNDTIMEO' and `SO_RCVTIMEO' use a `struct timeval' parameter, defined in `sys/time.h'. The following options are recognized at the socket level: `SO_DEBUG' Enables recording of debugging information `SO_REUSEADDR' Enables local address reuse `SO_KEEPALIVE' Enables keep connections alive `SO_DONTROUTE' Enables routing bypass for outgoing messages `SO_LINGER' Linger on close if data present `SO_BROADCAST' Enables permission to transmit broadcast messages `SO_OOBINLINE' Enables reception of out-of-band data in band `SO_SNDBUF' Get buffer size for output `SO_RCVBUF' Get buffer size for input `SO_SNDLOWAT' Get minimum count for output `SO_RCVLOWAT' Get minimum count for input `SO_SNDTIMEO' Get timeout value for output `SO_RCVTIMEO' Get timeout value for input `SO_TYPE' Get the type of the socket `SO_ERROR' Get and clear error on the socket `SO_DEBUG' enables debugging in the underlying protocol modules. `SO_REUSEADDR' indicates that the rules used in validating addresses supplied in a `bind()' call should allow reuse of local addresses (*note bind::). `SO_KEEPALIVE' enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified via a `SIGPIPE' signal when attempting to send data. `SO_DONTROUTE' indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. `SO_LINGER' controls the action taken when unsent messages are queued on socket and a `close()' is performed (*note close: (libc)close.). If the socket promises reliable delivery of data and `SO_LINGER' is set, the system will block the process on the `close()' attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in the `setsockopt()' call when `SO_LINGER' is requested). If `SO_LINGER' is disabled and a `close()' is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The `linger' structure is defined in `sys/socket.h' as follows: struct linger { int l_onoff; /* Linger active */ int l_linger; /* How long to linger for */ }; L_ONOFF indicates whether to linger or not. If it is set to 1 then L_LINGER contains the time in hundredths of seconds how long the process should linger to complete the `close()'. If L_ONOFF is set to zero the process returns immediately. The option `SO_BROADCAST' requests permission to send broadcast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the `SO_OOBINLINE' option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with `recv()' or `read()' calls without the `MSG_OOB' flag (*note recv::, *note read: (libc)read.). Some protocols behave as if this option were always set. `SO_SNDBUF' and `SO_RCVBUF' are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values. `SO_SNDLOWAT' is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A `select()' (*note select: (libc)select.) operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for `SO_SNDLOWAT' is set to a convenient size for network efficiency, often 1024. `SO_RCVLOWAT' is an option to set the minimum count for input operations. In general, receive calls (*note recv::, *note recvfrom::) will block until any (non-zero) amount of data is received, then return with smaller of the amount available or the amount requested. The default value for `SO_RCVLOWAT' is 1. If `SO_RCVLOWAT' is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. `SO_SNDTIMEO' is an option to get the timeout value for output operations. It returns a `struct timeval' parameter with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, it returns with a partial count or with the error `EWOULDBLOCK' if no data were sent. In the current implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies to output portions ranging in size from the low water mark to the high water mark for output. `SO_RCVTIMEO' is an option to get the timeout value for input operations. It returns a `struct timeval' parameter with the number of seconds and microseconds used to limit waits for input operations to complete. In the current implementation, this timer is restarted each time additional data are received by the protocol, and thus the limit is in effect an inactivity timer. If a receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with the error `EWOULDBLOCK' if no data were received. `SO_TYPE' returns the type of the socket, such as `SOCK_STREAM'; it is useful for servers that inherit sockets on startup. `SO_ERROR' returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. Return Values ------------- On success, zero is returned. On error, -1 is returned, and `errno' is set appropriately. Errors ------ `EBADF' The argument S is not a valid descriptor. `ENOTSOCK' The argument S is a file, not a socket. `ENOPROTOOPT' The option is unknown at the level indicated. `EFAULT' The address pointed to by OPTVAL is not in a valid part of the process address space. This error may also be returned if OPTLEN is not in a valid part of the process address space. Portability ----------- POSIX, Unix98 Example ------- herror ====== Syntax ------ #include extern int h_errno; void herror (const char *s); Description ----------- The `herror()' function prints the error message associated with the current value of `h_errno' on stderr. The values for H_ERRNO are described with `gethostbyname()' (*note gethostbyname::). Return Values ------------- None Portability ----------- not Unix98 While the `herror()' function is not portable to Unix98, the H_ERRNO variable is. Example ------- if_freenameindex ================ Syntax ------ #include void if_freenameindex (struct if_nameindex *ptr); Description ----------- This function frees the memory used by the array returned by *Note if_nameindex::. The program should not use PTR after calling `if_freenameindex()'. Return Value ------------ None. However, an error may occur. The error code will be stored in ERRNO. Possible errors for this function are: `EFAULT' The memory pointed to by PTR could not be accessed. Portability ----------- Open Group XNS 5.2 Draft 1.0 Example ------- if_indextoname ============== Syntax ------ #include char *if_nametoindex (unsigned int ifindex, char *ifname); Description ----------- This returns the interface name corresponding to IFINDEX in the buffer IFNAME. The buffer pointed to IFNAME must be at least `IFNAMESIZE' bytes in size. Return Value ------------ The interface name will be placed into IFNAME, if IFINDEX is a valid interface index. Otherwise `NULL' is returned and ERRNO contains the error code. Possible errors for this function are: `EFAULT' The name pointed to by IFNAME cannot be accessed. `ENXIO' There is no interface referred to by IFINDEX. Portability ----------- Open Group XNS 5.2 Draft 1.0 Example ------- if_nameindex ============ Syntax ------ #include struct if_nameindex *if_nameindex (void); Description ----------- This function returns an array of `if_nameindex' structures, one per interface. The array is terminated with an entry with a `if_index' field of 0 and a `if_name' field of `NULL'. The function `if_freenameindex()' (*note if_freenameindex::) should be called, passing the pointer returned by this function, in order to free memory. Return Value ------------ A pointer to the array of `if_nameindex' structures or `NULL' on error. On error, ERRNO will contain the error code. Possible errors for this function are: `ENOBUFS' There were insufficient system resources to complete the request. Portability ----------- Open Group XNS 5.2 Draft 1.0 Example ------- if_nametoindex ============== Syntax ------ #include unsigned int if_nametoindex (const char *ifname); Description ----------- This returns the interface index corresponding to IFNAME. Return Value ------------ The interface index will be returned if IFNAME is an interface name, else 0. If an error occurs, -1 will be returned and the error will be stored in ERRNO. Possible errors for this function are: `EFAULT' The name pointed to by IFNAME cannot be accessed. Portability ----------- Open Group XNS 5.2 Draft 1.0 Example ------- inet_addr ========= Syntax ------ #include #include #include unsigned long int inet_addr (const char *cp); Description ----------- The `inet_addr()' function converts the Internet host address CP from numbers-and-dots notation into binary data in network byte order. If the input is invalid, -1 is returned. This is an _obsolete_ interface to `inet_aton()' (*note inet_aton::); it is obsolete because -1 is a valid address (255.255.255.255), and `inet_aton()' provides a cleaner way to indicate error return. Return Values ------------- If the input is invalid, -1 is returned. Otherwise, the IP address is returned as a 32-bit unsigned integer in network order. Portability ----------- Unix98 Example ------- inet_aton ========= Syntax ------ #include #include #include int inet_aton (const char *cp, struct in_addr *inp); Description ----------- `inet_aton()' converts the Internet host address CP from the standard numbers-and-dots notation into binary data and stores it in the structure that INP points to. The structure `in_addr' is defined in the description of `inet_ntoa()' (*note inet_ntoa::). Return Values ------------- Non-zero is returned, if the address is valid; otherwise zero is returned. Portability ----------- Unix98 Example ------- inet_lnaof ========== Syntax ------ #include #include #include unsigned long int inet_lnaof (struct in_addr in); Description ----------- The `inet_lnaof()' function returns the local host address part of the Internet address IN. The local host address is returned in local host byte order. The structure `in_addr' is defined in the description of `inet_ntoa()' (*note inet_ntoa::). Return Values ------------- The local host address portion is returned. Portability ----------- Unix98 Example ------- inet_makeaddr ============= Syntax ------ #include #include #include struct in_addr inet_makeaddr (int net, int host); Description ----------- The `inet_makeaddr()' function makes an Internet host address in network byte order by combining the network number NET with the local address HOST in network NET, both in local host byte order. The structure `in_addr' is defined in the description of `inet_ntoa()' (*note inet_ntoa::). Return Values ------------- An Internet host addess is returned. Portability ----------- Unix98 Example ------- inet_netof ========== Syntax ------ #include #include #include unsigned long int inet_netof (struct in_addr in); Description ----------- The `inet_netof()' function returns the network number part of the Internet Address IN. The network number is returned in local host byte order. The structure `in_addr' is defined in the description of `inet_ntoa()' (*note inet_ntoa::). Return Values ------------- The network number portion is returned. Portability ----------- Unix98 Example ------- inet_network ============ Syntax ------ #include #include #include unsigned long int inet_network (const char *cp); Description ----------- The `inet_network()' function extracts the network number in network byte order from the address CP in numbers-and-dots notation. Return Values ------------- If the input is invalid, -1 is returned. Portability ----------- Unix98 Example ------- inet_ntoa ========= Syntax ------ #include #include #include char *inet_ntoa (struct in_addr in); Description ----------- The `inet_ntoa()' function converts the Internet host address IN given in network byte order to a string in standard numbers-and-dots notation. The string is returned in a statically allocated buffer, which subsequent calls will overwrite. The structure `in_addr' is defined in `netinet/in.h' as: struct in_addr { unsigned long int s_addr; } Note that on the i80x86 the host byte order is Least Significant Byte first, whereas the network byte order, as used on the Internet, is Most Significant Byte first. Return Value ------------ `inet_ntoa()' returns a pointer to the address in string form. Portability ----------- Unix98 Example ------- inet_ntop ========= Syntax ------ #include #include const char *inet_ntop (int af, const void *src, char *dst, size_t size); Description ----------- This function converts network addresses from numeric format (i.e. binary) into presentation format (i.e. strings). This is a replacement for `inet_ntoa' (*note inet_ntoa::), which cannot cope with IPv6 addresses. AF specifies the address family of the numeric format, e.g. `AF_INET' or `AF_INET6'. The numeric data in SRC will be converted in presentation format and stored in DST. SIZE specifies the size of the buffer pointed to by DST - it must be large enough to store the presentation format address. The constants `INET_ADDRSTRLEN' and `INET6_ADDRSTRLEN' are defined in `netinet/in.h' as the maximum presentation string lengths, including terminating nuls. Return Values ------------- On successful completion the function returns a pointer to the presentation format string. Otherwise, a value of NULL is returned and ERRNO is set appropriately. `EFAULT' DST did not point to a valid buffer. `ENOSPC' The size of DST specified by SIZE was not large enough to store the presentation format string. `EAFNOSUPPORT' The address family AF is not known or supported. Portability ----------- POSIX Example ------- inet_pton ========= Syntax ------ #include #include int inet_pton (int af, const char *src, void *dst); Description ----------- This function converts network addresses from presentation format (i.e. strings) into numeric format (i.e. binary). This is a replacement for `inet_aton' (*note inet_aton::), which cannot cope with IPv6 addresses. AF specifies the address family of the presentation format, e.g. `AF_INET' or `AF_INET6'. The address string SRC will be converted to the appropriate address format, e.g. `struct in_addr' or `struct in6_addr', and stored in DST. Return Values ------------- On successful completion the function returns 1. If the presentation format is not understood, 0 is returned. If the address family AF is not known or supported, -1 is returned and ERRNO is set to `EAFNOSUPPORT'. Portability ----------- POSIX Example ------- ioctl_list ========== Syntax ------ #include #include #include #include Description ----------- This page documents the ioctls that are supported by libsocket. These are used with the `ioctl()' function (*note ioctl: (libc)ioctl.). Many BSD ioctls are not listed here, because libsocket does not support them. Some BSD socket ioctls are supported. `FIONBIO' This can be used to toggle non-blocking I/O. `ioctl()' should be passed an integer - if this is non-zero, non-blocking I/O will be enabled, otherwise blocking I/O will be used. /* Flip into non-blocking mode */ int x = 1; ioctl(sock, FIONBIO, &x); `FIONBIO' is like the `O_NONBLOCK' flag that can be set using `fcntl()' (*note libc: (libc)fcntl.): /* Flip into non-blocking mode */ int flags = flags = fcntl(sock, F_GETFL); flags |= O_NONBLOCK; fcntl(sock, F_SETFL, flags); `FIONREAD' This can be used to discover the maximum atomic read that can be performed on the socket, i.e. the largest single read operation. `ioctl()' should be passed an integer - on return this will contain the maximum read size. int maxsz = 0; ioctl(sock, FIONREAD, &maxsz) `SIOCATMARK' This determines if all out-of-band data has been read. This only applies to `SOCK_STREAM' type sockets that have been set with the option `SO_OOBINLINE' (*note getsockopt::, *note setsockopt::). It returns 1 (true) or 0 (false) in the ioctl parameter. The `sockatmark()' function should be used instead (*note sockatmark::). `SIOCGIFNAME' This copies the interface name into a user buffer of size `IFNAMSIZ'. The pointer to the buffer is passed as the parameter to ioctl, e.g. ioctl(sock, SIOCGIFNAME, (int *) name) `SIOCGIFADDR' This copies the local socket address into a user structure of type `struct ifreq'. The pointer to the buffer is passed as the parameter to ioctl, e.g. ioctl(sock, SIOCGIFADDR, (int *) &ifr) The socket address can then be accessed via the `ifr_ifru.ifru_addr' member of `struct ifreq'. `SIOCGIFDSTADDR' This copies the peer's socket address into a user structure of type `struct ifreq'. The pointer to the buffer is passed as the parameter to ioctl, e.g. ioctl(sock, SIOCGIFDSTADDR, (int *) &ifr) The peer's socket address can then be accessed via the `ifr_ifru.ifru_dstaddr' member of `struct ifreq'. `SIOCGIFNETMASK' This copies the socket's network mask into a user structure of type `struct ifreq'. The pointer to the buffer is passed as the parameter to ioctl, e.g. ioctl(sock, SIOCGIFDSTADDR, (int *) &ifr) The peer's socket address can then be accessed via the `ifr_ifru.ifru_netmask' member of `struct ifreq'. Return Values ------------- Portability ----------- ioctls cannot be guaranteed to be portable. However, because of the ubiquity of BSD sockets, these ioctls should work on most Unices. isfdtype ======== Syntax ------ #include int isfdtype (int fd, int fd_type); Description ----------- The `isfdtype()' function determines whether the file descriptor FD has the properties specified by FD_TYPE. Valid values of FD_TYPE include: `S_IFSOCK' Tests whether FD is a socket Return Value ------------ 1 if the type matches, 0 otherwise. If an error occurs, -1 is returned and ERRNO is set to: `EBADF' FD is not a valid file descriptor. Portability ----------- POSIX, not Unix98 `isfdtype()' is usually declared in `sys/stat.h' rather than `sys/socket.h'. Example ------- listen ====== Syntax ------ #include int listen (int s, int backlog); Description ----------- To create a passive/listening (server) socket, a socket is created with `socket()' (*note socket::), bound to a local address with `bind()' (*note bind::) and then given a connection queue with `listen()'. Connections can then be accepted with `accept()' (*note accept::). `listen()' sets the maximum number of connections, BACKLOG, that can be waiting for handling by `accept()'. Any further waiting connections will be refused. `listen()' is only a valid operation for sockets of type `SOCK_STREAM' or `SOCK_SEQPACKET'. Return Value ------------ On successful completion the function returns 0. Otherwise, a value of -1 is returned and ERRNO is set appropriately. `EBADF' S is not a valid file descriptor. `ENOTSOCK' S is not a socket. `EOPNOTSUPP' `listen()' is not a valid operation on this type of socket. Portability ----------- POSIX, Unix98 Example ------- __lsck_get_copyright ==================== Syntax ------ #include char *__lsck_get_copyright (void); Description ----------- This function returns a string containing the copyright information for libsocket. If this is longer than one line, it will be formatted to fit on an 80-column terminal. Return Values ------------- A pointer to the string is returned on success; on failure, `NULL' is returned. Portability ----------- not ANSI, not POSIX, not Unix98 This function is specific to libsocket. Example ------- char *p = __lsck_get_copyright(); puts(p); __lsck_get_version ================== Syntax ------ #include char *__lsck_get_version (void); Description ----------- This function returns a string containing the version information for libsocket. If this is longer than one line, it will be formatted to fit on an 80-column terminal. The version message is constructed from constants defined in `lsck/copyrite.h'. The ones that should be used in user programs are listed in the table below. As an example, consider the version number 0.8.0. `LSCK_VERSION_MAJOR' This is libsocket's major version, which is `0' for the example. `LSCK_VERSION_MINOR' This is libsocket's minor version, which is `8' for the example. `LSCK_VERSION_SUBMINOR' This is libsocket's minor-minor or subminor version, which is `0' for the example. Return Values ------------- A pointer to the string is returned on success; on failure, `NULL' is returned. Portability ----------- not ANSI, not POSIX, not Unix98 This function is specific to libsocket. Example ------- char *p = __lsck_get_version(); puts(p); rcmd ==== Syntax ------ #include #include int rcmd (char **ahost, int inport, const char *locuser, const char *remuser, const char *cmd, int *fd2p); Description ----------- The `rcmd()' function is used by the super-user to execute a command on a remote machine using an authentication scheme based on reserved port numbers. The `rcmd()' function looks up the host *AHOST using `gethostbyname()' (*note gethostbyname::), returning -1 if the host does not exist. Otherwise *AHOST is set to the standard name of the host and a connection is established to a server residing at the well-known Internet port INPORT. If the connection succeeds, a socket in the Internet domain of type `SOCK_STREAM' is returned to the caller, and given to the remote command as stdin and stdout. If FD2P is non-zero, then an auxiliary channel to a control process will be set up, and a descriptor for it will be placed in *FD2P. The control process will return diagnostic output from the command (unit 2) on this channel, and will also accept bytes on this channel as being UNIX signal numbers, to be forwarded to the process group of the command. If FD2P is 0, then the stderr (unit 2 of the remote command) will be made the same as the stdout and no provision is made for sending arbitrary signals to the remote process, although you may be able to get its attention by using out-of-band data. The protocol is described in detail in the rshd documentation. Return Value ------------ The `rcmd()' function returns a valid socket descriptor on success. It returns -1 on error and prints a diagnostic message on the standard error. Portability ----------- libsocket declares this function in `sys/socket.h', but it's usually defined in `unistd.h'. Example ------- readv ===== Syntax ------ #include ssize_t readv (int fd, const struct iovec *iov, int iovcnt); Description ----------- `readv()' performs a scatter-gather read from the specified file descriptor FD. The data is written into a group of buffers described by the array IOV with IOVCNT entries in a similar way to `read()' (*note read: (libc)read.). `struct iovec' is described in the section on `writev()' (*note writev::). Return Value ------------ On successful completion the function returns the number of bytes read. Otherwise, a value of -1 is returned and ERRNO is set appropriately. `EINVAL' One of the following conditions is true: * The total length to read could overflow a `ssize_t'. * IOVCNT was negative, zero or larger than `IOV_MAX'. Portability ----------- POSIX, Unix98 Example ------- recv ==== Syntax ------ #include #include ssize_t recv (int s, void * buf, size_t len, int flags); Description ----------- The `recv()' function is used on a connected socket and is identical to `recvfrom()' (*note recvfrom::) with NULL FROM and FROMLEN parameters. Return Values ------------- On success the number of octets received is return, or -1 and errno is set. *Note recvfrom::. Portability ----------- POSIX, Unix98 Example ------- recvfrom ======== Syntax ------ #include #include ssize_t recvfrom (int s, void * buf, size_t len, unsigned int flags, struct sockaddr *from, size_t *fromlen); Description ----------- `recvfrom()' is used to receive messages from a socket. If FROM is non-NULL, the source address of the message is stored in it. FROMLEN is a value-result parameter, it indicates the size of FROM on entry and the size of FROM stored. If FROMLEN was too small, it is truncated to the initial size. FLAGS may have the value zero or be the bitwise OR of any combination of one or more of the values: `MSG_OOB' Receipt of out-of-band data that would not be received in the normal data stream. Application should use MSG_OOB flag after catching a SIGURG or if `select()' (*note select: (libc)select.) indicates an exception condition. `MSG_PEEK' The receive operation data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data. `MSG_WAITALL' Requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. Return Values ------------- On success the number of octets received is return, or -1 and ERRNO is set: `EWOULDBLOCK.' The socket is marked non-blocking and the receive operation would block. `EBADF' The paramater is not a valid descriptor. `ENOTCONN' The socket is associated with a connection-oriented protocol and has not been connected. `ENOTSOCK' The argument does not refer to a socket. `EINTR' The receive was interrupted by delivery of a signal before any data were available. `EFAULT' The receive buffer pointer(s) point outside the process's address space. Portability ----------- POSIX, Unix98 Example ------- res_init ======== Syntax ------ #include #include #include extern struct state _res; int res_init (void); Description ----------- The `res_init()' function reads the configuration files (*note host.conf::, *note resolv.conf::) to get the default domain name, search order and name server address(es). If no server is given, the local host is tried. If no domain is given, that associated with the local host is used. It can be overridden with the environment variable `LOCALDOMAIN'. `res_init()' is normally executed by the first call to one of the other resolver functions, e.g. `res_query()', `gethostbyname()' (*note res_query::, *note gethostbyname::). Return Value ------------ The `res_init()' function returns 0 on success, or -1 if an error occurs. Portability ----------- This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. Example ------- res_mkquery =========== Syntax ------ #include #include #include extern struct state _res; int res_mkquery (int op, const char *dname, int class, int type, char *data, int datalen, struct rrec *newrr, char *buf, int buflen); Description ----------- This function is a low-level routine used by *Note res_query::. The `res_mkquery()' function constructs a query message in BUF of length BUFLEN for the domain name DNAME. The query type OP is usually `QUERY', but can be any of the types defined in `arpa/nameser.h'. NEWRR is currently unused. The resolver routines use global configuration and state information contained in the structure `_res', which is described with `res_query()' (*note res_query::). Return Value ------------ The `res_mkquery()' function returns the length of the response, or -1 if an error occurs. Portability ----------- This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. Example ------- res_query ========= #include #include #include extern struct state _res; int res_query (const char *dname, int class, int type, unsigned char *answer, int anslen); Description ----------- The `res_query()' function queries the name server for the fully-qualified domain name NAME of specified TYPE and CLASS. The reply is left in the buffer ANSWER of length ANSLEN supplied by the caller. The resolver routines use global configuration and state information contained in the structure `_res', which is defined in `'. The only field that is normally manipulated by the user is `_res.options'. This field can contain the bitwise OR of the following options: `RES_INIT' True if `res_init()' has been called. `RES_DEBUG' Print debugging messages. `RES_AAONLY' Accept authoritative answers only. `res_send()' continues until it fins an authoritative answer or returns an error. [Not currently implemented]. `RES_USEVC' Use TCP connections for queries rather than UDP datagrams. `RES_PRIMARY' Query primary domain name server only. `RES_IGNTC' Ignore truncation errors. Don't retry with TCP. [Not currently implemented]. `RES_RECURSE' Set the recursion desired bit in queries. Recursion is carried out by the domain name server, not by `res_send()'. [Enabled by default]. `RES_DEFNAMES' If set, `res_search()' will append the default domain name to single component names, ie. those that do not contain a dot. [Enabled by default]. `RES_STAYOPEN' Used with RES_USEVC to keep the TCP connection open between queries. `RES_DNSRCH' If set, `res_search()' will search for host names in the current domain and in parent domains. This option is used by `gethostbyname()' (*note gethostbyname::). [Enabled by default]. Return Value ------------ `res_query()' returns the length of the response, or -1 if an error occurs. Portability ----------- This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. Example ------- res_querydomain =============== Syntax ------ #include #include #include extern struct state _res; int res_querydomain (const char *name, const char *domain, int class, int type, unsigned char *answer, int anslen); Description ----------- The `res_querydomain()' function makes a query using `res_query()' (*note res_query::) on the concatenation of NAME and DOMAIN. The resolver routines use global configuration and state information contained in the structure `_res', which is described in `res_query()' (*note res_query::). Return Value ------------ The `res_querydomain()' function returns the length of the response, or -1 if an error occurs. Portability ----------- This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. Example ------- res_search ========== Syntax ------ #include #include #include extern struct state _res; int res_search(const char *dname, int class, int type, unsigned char *answer, int anslen); Description ----------- The `res_search()' function makes a query and waits for the response like `res_query()' (*note res_query::, but in addition implements the default and search rules controlled by `RES_DEFNAMES' and `RES_DNSRCH' (see description of `_res' with `res_query()' (*note res_query::)). Return Value ------------ The `res_search()' function returns the length of the response, or -1 if an error occurs. Portability ----------- This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. Example ------- res_send ======== Syntax ------ #include #include #include extern struct state _res; int res_send (const char *msg, int msglen, char *answer, int anslen); Description ----------- This function is a low-level routine used by `res_query()' (*note res_query::). The `res_send()' function sends a pre-formatted query given in MSG of length MSGLEN and returns the answer in ANSWER which is of length ANSLEN. It will call `res_init()' (*note res_init::), if it has not already been called. The resolver routines use global configuration and state information contained in the structure `_res', which is described with `res_query()' (*note res_query::). Return Value ------------ The `res_send()' function returns the length of the response, or -1 if an error occurs. Portability ----------- This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. Example ------- rexec ===== Syntax ------ #include int rexec (char **ahost, int rport, const char *name, const char *pass, const char *cmd, int *fd2p); Description ----------- Under construction - if you have a good description, please inform the libsocket maintainer. Return Value ------------ Portability ----------- Example ------- rresvport ========= Syntax ------ #include #include int rresvport (int *port); Description ----------- The `rresvport()' function is used to obtain a socket with a privileged address bound to it. This socket is suitable for use by `rcmd()' (*note rcmd::) and several other functions. Privileged Internet ports are those in the range 0 to 1023. Only the super-user is allowed to bind an address of this sort to a socket. Return Value ------------ The `rresvport()' function returns a valid, bound socket descriptor on success. It returns -1 on error with ERRNO set according to the reason for failure. The error code `EAGAIN' is overloaded to mean "All network ports in use". Portability ----------- libsocket declares this function in `sys/socket.h', but it's usually defined in `unistd.h'. Example ------- ruserok ======= Syntax ------ #include #include int ruserok (const char *rhost, int superuser, const char *ruser, const char *luser); Description ----------- The `ruserok()' function is used by servers to authenticate clients requesting service with `rcmd()' (*note rcmd::). The `ruserok()' function takes a remote host's name, two user names and a flag indicating whether the local user's name is that of the super-user. Then, if the user is *NOT* the super-user, it checks the `/etc/hosts.equiv' file. If that lookup is not done, or is unsuccessful, the `.rhosts' in the local user's home directory is checked to see if the request for service is allowed. If this file does not exist, is not a regular file, is owned by anyone other than the user or the super-user, or is writeable by anyone other than the owner, the check automatically fails. If the local domain (as obtained from `gethostname()' (*note gethostname::) is the same as the remote domain, only the machine name need be specified. Return Value ------------ Zero is returned if the machine name is listed in the `hosts.equiv' file, or the host and remote user name are found in the `.rhosts' file; otherwise -1 is returned. Portability ----------- libsocket declares this function in `sys/socket.h', whereas it's usually defined in `unistd.h'. Example ------- send ==== Syntax ------ #include #include int send (int s, const void * msg, size_t len, int flags); Description ----------- The `send()' function is used to transmit data to a peer via socket, `send()' is equivalent to `sendto()' (*note sendto::) call with a NULL to parameter to and tolen. Return values ------------- The function return the number of octets accepted for transmission, Otherwise -1 with errno set. See *Note sendto::. Portability ----------- POSIX, Unix98 Example ------- sendto ====== Syntax ------ #include #include ssize_t sendto (int s, const void * msg, size_t len, int flags, const struct sockaddr *to, size_t tolen); Description ----------- The function `sendto()' is used to transmit a message to another socket. The address of the target is given by TO with TOLEN specifying its size. A NULL value fo TO indicats that no socket-address is specifiend and the socket is in the CONNECTED state, the corresponding TOLEN is then ignored. The length of the message is given by LEN. If the message is too long to pass atomically through the underlying protocol, the error `EMSGSIZE' is returned, and the message is not transmitted. If no messages space is available at the socket to hold the message to be transmitted, then `sendto' normally blocks, unless the socket has been placed in non-blocking I/O mode. The `select()' (*note select: (libc)select.) call may be used to determine when it is possible to send more data. The FLAGS parameter may include one or more of the following: `MSG_OOB' Used to send `out-of-band' data on sockets that support this notion. `MSG_DONTROUTE' Used only by diagnostic or routing programs. `MSG_EOR' Terminates a record for protocols which support that concept. Return values ------------- The call returns the number of characters sent, or -1 and ERRNO set, if an error occurred. `EBADF' An invalid descriptor was specified. `ENOTSOCK' The argument `s' is not a socket. `EFAULT' An invalid user space address was specified for a parameter. `EMSGSIZE' The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. `EWOULDBLOCK' The socket is marked non-blocking and the requested operation would block. `EPIPE' The socket is shut for writing (*note shutdown::). If the socket is a stream, the SIGPIPE signal is raised (*note signal: (libc)signal.). `ENOBUFS' The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. Portability ----------- POSIX, Unix98 Example ------- setdomainname ============= Syntax ------ #include int setdomainname (const char *name, size_t len); Description ----------- This function is used to change the domain name. The domain name can be accessed using `getdomainname()' (*note getdomainname::). Return Value ------------ On success, zero is returned. On error, -1 is returned, and ERRNO is set appropriately. Errors ------ `EPERM' The caller was not the superuser. `EINVAL' LEN was too long. Portability ----------- not POSIX, not Unix98 This function is defined in `unistd.h' on Linux. Example ------- sethostent ========== Syntax ------ #include extern int h_errno; void sethostent (int stayopen); Description ----------- The `sethostent()' function specifies, if STAYOPEN is true (1), that a connected TCP socket should be used for the name server queries and that the connection should remain open during successive queries. Otherwise, name server queries will use UDP datagrams. Return Values ------------- None Portability ----------- Unix98 Example ------- sethostname =========== #include #include int sethostname (const char *name, size_t len); Description ----------- This function is used to change the host name of the current processor. The host name is retrieved using `gethostname()' (*note gethostname::). The domain name component can be retrieved and set using `getdomainname()' and `setdomainname()' respectively (*note getdomainname::, *note setdomainname::). Return value ------------ On success, zero is returned. On error, -1 is returned, and `errno' is set appropriately. Errors ------ `EINVAL' LEN is negative or larger than the maximum allowed size. `EPERM' The caller was not the superuser. `EFAULT' NAME is an invalid address. Portability ----------- not POSIX, not Unix98 `lsck/hostname.h' is particular to libsocket. On Linux it is defined in `unistd.h'. Example ------- setnetent ========= Syntax ------ #include void setnetent (int stayopen); Description ----------- The `setnetent()' function opens and rewinds the `networks' file (*note networks::). If STAYOPEN is true (`1'), then the file will not be closed between calls to `getnetbyname()' or `getnetbyaddr()' (*note getnetbyname::, *note getnetbyaddr::). Return Values ------------- None Portability ----------- Unix98 Example ------- setprotoent =========== Syntax ------ #include void setprotoent (int stayopen); Description ----------- The `setprotoent()' function opens and rewinds the `protocols' file (*note protocols::). If STAYOPEN is true (`1'), then the file will not be closed between calls to `getprotobyname()' or `getprotobynumber()' (*note getprotobyname::, *note getprotobynumber::). Return Values ------------- None Portability ----------- Unix98 Example ------- setservent ========== Syntax ------ #include void setservent (int stayopen); Description ----------- The `setservent()' function opens and rewinds the `services' file (*note services::). If STAYOPEN is true (`1'), then the file will not be closed between calls to `getservbyname()' or `getservbyport()' (*note getservbyname::, *note getservbyport::). Return Values ------------- None Portability ----------- Unix98 Example ------- setsockopt ========== Syntax ------ #include #include int setsockopt (int s, int level, int optname, const void *optval, int optlen); Description ----------- `setsockopt()' manipulates the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost socket level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, LEVEL is specified as `SOL_SOCKET'. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, LEVEL should be set to the protocol number of TCP (*note getprotoent::). The parameters OPTVAL and OPTLEN are used to access option values for `setsockopt()'. OPTNAME and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file `sys/socket.h' contains definitions for socket level options, described below. Options at other protocol levels vary in format and name. Most socket-level options utilize an `int' parameter for OPTVAL. The parameter should be non-zero to enable a boolean option, or zero if the option is to be disabled. `SO_LINGER' uses a `struct linger' parameter, defined in `sys/socket.h', which specifies the desired state of the option and the linger interval (see below). `SO_SNDTIMEO' and `SO_RCVTIMEO' use a `struct timeval' parameter, defined in `sys/time.h'. The following options are recognized at the socket level. `SO_DEBUG' enables recording of debugging information `SO_REUSEADDR' enables local address reuse `SO_KEEPALIVE' enables keep connections alive `SO_DONTROUTE' enables routing bypass for outgoing messages `SO_LINGER' linger on close if data present `SO_BROADCAST' enables permission to transmit broadcast messages `SO_OOBINLINE' enables reception of out-of-band data in band `SO_SNDBUF' set buffer size for output `SO_RCVBUF' set buffer size for input `SO_SNDLOWAT' set minimum count for output `SO_RCVLOWAT' set minimum count for input `SO_DEBUG' enables debugging in the underlying protocol modules. `SO_REUSEADDR' indicates that the rules used in validating addresses supplied in `bind()' (*note bind::) call should allow reuse of local addresses. `SO_KEEPALIVE' enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified via a `SIGPIPE' signal when attempting to send data. `SO_DONTROUTE' indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. `SO_LINGER' controls the action taken when unsent messages are queued on socket and a `close()' is performed (*note close: (libc)close.). If the socket promises reliable delivery of data and `SO_LINGER' is set, the system will block the process on the `close()' attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in the `setsockopt()' call when `SO_LINGER' is requested). If `SO_LINGER' is disabled and a `close()' is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The `linger' structure is defined in `sys/socket.h' as follows: struct linger { int l_onoff; /* Linger active */ int l_linger; /* How long to linger for */ }; `l_onoff' indicates whether to linger or not. If it is set to 1 then `l_linger' contains the time in hundredths of seconds how long the process should linger to complete the `close()'. If `l_onoff' is set to zero the process returns immediately. The option `SO_BROADCAST' requests permission to send broadcast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the `SO_OOBINLINE' option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with `recv' or `read' calls without the `MSG_OOB' flag. Some protocols always behave as if this option is set. `SO_SNDBUF' and `SO_RCVBUF' are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values. `SO_SNDLOWAT' is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A `select()' (*note select: (libc)select.) operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for `SO_SNDLOWAT' is set to a convenient size for network efficiency, often 1024. `SO_RCVLOWAT' is an option to set the minimum count for input operations. In general, receive calls will block until any (non-zero) amount of data is received, then return with smaller of the amount available or the amount requested. The default value for `SO_RCVLOWAT' is 1. If `SO_RCVLOWAT' is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. Return value ------------ On success, zero is returned. On error, -1 is returned, and ERRNO is set appropriately. Possible errors from this function are: `EBADF' The argument S is not a valid descriptor. `ENOTSOCK' The argument S is a file, not a socket. `ENOPROTOOPT' The option is unknown at the LEVEL indicated. `EFAULT' The address pointed to by OPTVAL is not in a valid part of the process address space. Portability ----------- Unix98 Example ------- shutdown ======== Syntax ------ #include int shutdown (int s, int how); Description ----------- `shutdown()' stops communication in one or both directions of a full-duplex connection on socket S. HOW is one of the following: `SHUT_RD' Receives will be disabled. `SHUT_WR' Sends will be disabled. `SHUT_RDWR' Receives and sends will be disabled. These correspond to the values 0, 1 and 2 respectively. If sends are disabled for a stream socket (`SOCK_STREAM'), any further writes on the socket will return `EPIPE' and raise the signal `SIGPIPE' (*note sendto::). Return Value ------------ On successful completion the function returns 0. Otherwise, a value of -1 is returned and ERRNO is set appropriately. `EBADF' S is not a valid file descriptor. `ENOTSOCK' S is not a socket. `ENOTCONN' The socket S is not connected. Portability ----------- POSIX, Unix98 Example ------- sockatmark ========== Syntax ------ #include int sockatmark (int s); Description ----------- The `sockatmark()' function determines whether the socket descriptor S is at the out-of-band data mark. If the libsocket interface supports it, `sockatmark()' will return 1 when all data preceding the mark have been read and the out-of-band data mark is the first element in the receive queue. `sockatmark()' does not remove the mark from the stream. Return Values ------------- On successful initialization the function returns 1, if the protocol has marked the data stream and all data preceeding the mark have been read. It returns 0, if there is no mark, or if data preceeds the mark in the receive queue. Otherwise, -1 is return and errno is set: `EBADF' The parameter is not a valid file descriptor. `ENOSYS' The inteface does not support the `sockatmark()' operation. Portability ----------- not ANSI, POSIX Example ------- socket ====== Syntax ------ #include int socket (int domain, int type, int protocol); Description ----------- `socket()' creates a communication end-point and returns its file descriptor. DOMAIN refers to a communication domain, e.g. Internet domain, Unix domain. These are specified by the `AF_*' constants, e.g. `AF_INET', `AF_UNIX', as defined in `sys/socket.h'. TYPE specifies how the communication takes place, e.g. streams, datagrams. These are specified by the `SOCK_' constants, e.g. `SOCK_STREAM', `SOCK_DGRAM', as defined in `sys/socket.h'. `SOCK_STREAM' supports reliable, sequenced, bidirectional streams of binary data. `SOCK_DGRAM' supports unreliable connectionless packets. These packets may have a maximum size. PROTOCOL specifies the communications protocol to use, e.g. TCP, UDP. For the Internet domain (i.e. IP), these are defined by the `IPPROTO_*' constants in `netinet/in.h', e.g. `IPPROTO_TCP', `IPPROTO_UDP'. If PROTOCOL is zero, the default protocol for the socket's domain & type is used, e.g. to create a TCP/IP socket: fd = socket(AF_INET, SOCK_STREAM, 0); or a UDP/IP socket: fd = socket(AF_INET, SOCK_DGRAM, 0); libsocket supports the following triplets: * AF_INET, SOCK_STREAM, IPPROTO_TCP * AF_INET, SOCK_DGRAM, IPPROTO_UDP * AF_UNIX, SOCK_STREAM, 0 * AF_UNIX, SOCK_DGRAM, 0 Return Values ------------- -1 is returned and ERRNO set on error. Otherwise, a positive non-zero integer number is returned, a file descriptor. Possible errors are: `EMFILE' There is no space left in the per-process file descriptor table. `ENFILE' There is no space left in the system file descriptor table. `ENODEV' No socket transports were found. `ENOAFSUPPORT' The implementation does not support the specified address family. `EPROTONOSUPPORT' The protocol is not supported by the address family or the protocol is not supported by the implementation. Portability ----------- POSIX, Unix98 Example ------- socketpair ========== Syntax ------ #include int socketpair (int domain, int type, int protocol, int sv[2]); Description ----------- `socketpair()' creates a pair of unbound connected sockets. The sockets are identical. SV contains two file descriptors, one for each socket. DOMAIN, TYPE and PROTOCOL are described in the section on `socket()' (*note socket::). Using a PROTOCOL of 0 will give a default protocol. Return Values ------------- 0 is returned on success. Otherwise -1 is returned and the error code is stored in ERRNO. Possible errors for this function are: `EOPNOTSUPP' The specified protocol does not permit creation of socket pairs. `EAFNOTSUPP' The specified address family is not supported. `ENOPROTOSUPPORT' The specified protocol is not supported. Portability ----------- POSIX, Unix98 Example ------- writev ====== Syntax ------ #include ssize_t writev (int fd, const struct iovec *iov, int iovcnt); Description ----------- `writev()' performs a scatter-gather write to the specified file descriptor FD. A group of buffers described by the array IOV, with IOVCNT entries, is written to FD in a similar way to `write()' (*note write: (libc)write.). `struct iovec' is defined as follows: struct iovec { void *iov_base; /* Base address of a memory region for I/O */ size_t iov_len; /* Size of memory region */ }; Return Value ------------ On successful completion the function returns the number of bytes written. Otherwise, a value of -1 is returned and ERRNO is set appropriately. `EINVAL' One of the following conditions is true: * The total length to write would overflow a `ssize_t'. * IOVCNT was negative, zero or larger than `IOV_MAX'. Portability ----------- POSIX, Unix98 Example ------- Unimplemented ************* Installation ************ Installing the Binary Distribution ================================== Installing the binary distribution (ready-to-run) version of libsocket is fairly straightforward. Firstly, back up the DJGPP header file `include/netinet/in.h', because this is overwritten by one of libsocket's header files. Then extract the ZIP file into the DJGPP directory (e.g. `c:\djgpp'), preserving directory names - e.g. use PKUNZIP's `-d' option. The distribution documentation files (e.g. readme files) can then be found off the `c:\djgpp\contrib' directory. To install the info files properly, you will need GNU texinfo 4.0(1). Run the following commands: install-info --info-file=/dev/env/DJDIR/info/lsck.inf \ --info-dir=/dev/env/DJDIR/info install-info --info-file=/dev/env/DJDIR/info/netsetup.inf \ --info-dir=/dev/env/DJDIR/info Now install the Winsock 2 support virtual device driver (see the section below). libsocket should now be installed correctly and ready to use (*note Getting Started::). libsocket's binary distribution is built with debugging information, because it is still in development. Programs built with libsocket may be larger than expected, because of the debugging information. Debugging information can be removed using strip (*note strip: (binutils)strip.). Installing the Documentation Distribution ========================================= Installing the documentation distribution (ready-to-run) version of libsocket is fairly straightforward. Extract the ZIP file into the DJGPP directory (e.g. `c:\djgpp'), preserving directory names - e.g. use PKUNZIP's `-d' option. The distribution documentation files (e.g. readme files) can then be found off the `c:\djgpp\contrib' directory. Installing the Source Distribution ================================== Extract the ZIP into the DJGPP directory (e.g. `c:\djgpp'), preserving directory names - e.g. use PKUNZIP's `-d' option. The sources can then be found off the `c:\djgpp\contrib' directory. Required and Optional Packages ------------------------------ To build libsocket requires the following packages: * DJGPP development environment, version 2.02 or later * GNU bash * GNU C compiler (gcc) * GNU C++ compiler (g++, also known as gxx) * GNU binutils * GNU make * GNU fileutils * GNU shellutils * GNU texinfo, version 4.0 * GNU autoconf, version 2.13 or later * GNU awk * GNU m4 * GNU sed, verson 3.02 or later Optional packages are as follows: * GNU textutils Configuration and Compilation ----------------------------- In the following instructions, I have assumed that bash is the shell. If not, type `bash' and then follow the instructions. 1. Regenerate the configure script: autoconf config.in | sed -e 's/config\.guess/config.gue/' > config It may be necessary to regenerate the configure script, because the DJGPP port of autoconf has some extra m4 macros that make it work on DOS. If a Linux (or other Unix) configure script is used under DOS, it will not work properly. The usage of `sed' above is necessary to convert the filename `config.guess' to the short filename `config.gue' that is used in the libsocket distribution (so that libsocket can be compiled on plain ol' DOS). [ Note that source distributions of libsocket should be set up for compilation with DJGPP, so this step shouldn't be necessary. If it doesn't work, try running `autoconf'. ] 2. Run `./config' to detect programs and the default prefix (the DJGPP directory, `$DJDIR'). If you wish to enable debugging information, use the `--enable-debug' switch, like so: ./config --enable-debug The `--prefix' option can be used to specify the prefix used when installing the built package. This should probably be the DJGPP directory, but you can install it elsewhere if you want. The default is the DJGPP directory. As an example: ./config --prefix=c:/somedir/ls080 3. Build the dependency information: make dep 4. Then build everything (library, documentation, demo programs, tests): make all 5. (_Optional_) Run `make install' to install libsocket. If you want to see what would be installed, use `make -n install' instead. This will install the headers, library and info documentation (including adding an entry to the info directory) into the prefix specified above. Now install the Winsock 2 support virtual device driver (see the section below). libsocket should now be installed correctly and ready to use (*note Getting Started::). Installing the Winsock 2 Support Virtual Device Driver ====================================================== To work with Winsock 2, libsocket needs a virtual device driver (VxD) to be installed. This VxD is called SOCK.VXD and was written as part of the port of the Coda Network File System (http://www.coda.cs.cmu.edu/) to Windows '95. SOCK.VXD is included in the `redist' directory of the libsocket binary and source distributions. The program `sockvxd.exe' is a self-extracting installer. To run this program, use the `installvxd' Makefile target: make installvxd When prompted, select the option to dynamically load SOCK.VXD - then it will only be loaded when used by libsocket programs. ---------- Footnotes ---------- (1) This is available from the DJGPP archive as v2gnu/txi40b.zip Getting Started *************** This section is under construction. *Note Configuration::. Configuration ************* libsocket's configuration can be controlled by a number of files. These files have the same purpose and are in the same format as the ones on Linux, and hence many Unices. Some of these files are also present on Windows - these can be used libsocket. libsocket can run without configuration files, but only in certain circumstances. libsocket comes with a program called "netsetup", which generates the necessary configuration files (*note Introduction: (netsetup)Introduction.). libsocket's main configuration file is `lsck.cfg'. libsocket and environment variables =================================== libsocket's main configuration file is `lsck.cfg'. Its location is specified by the environment variable `LSCK'. If you use the normal DOS shell, `command.com', you would use: SET LSCK=c:\lsck You may want to add this to your `autoexec.bat'. In bash (*note Top: (bash)Top.) you would use: export LSCK=c:/lsck You could also add a line to `DJGPP.ENV' (*note DJGPP.ENV: (kb)DJGPP.ENV.) somewhere near the start, e.g. just after the line like: +LFN=Y add a line like: +LSCK=c:/lsck libsocket and bash ------------------ If you are using bash, you should be aware that it sets the environment variable `HOSTNAME' automatically (*note Bash Variables: (bash)Bash Variables.). This interferes with libsocket's automatic configuration; it may cause problems, when trying to resolve DNS names. To avoid this problem, please add the following line to your _bashrc file (*note Bash Startup Files: (bash)Bash Startup Files.): unset HOSTNAME lsck.cfg ======== `lsck.cfg' is written in a similar way to Windows .INI files - the file is split into different sections. There are four sections: * `main', for libsocket global settings, e.g. resolver files, host name; * `wsock', for the wsock (Winsock 1) interface; * `csock', for the csock (Winsock 2) interface; * `unix', for the unix (Unix domain sockets) interface. The main Section ---------------- Key Possible Values Default Value hostname Host name with domain (Via auto-configuration) debug on, off, verbose, yes, no, 0, 1, 2 off hosts 'hosts' file location 'hosts', Windows directory networks 'networks' file location 'networks', Windows directory services 'services' file location 'services', Windows directory protocols 'protocols' file location 'protocol', Windows directory host.conf 'host.conf' file location resolv.conf 'resolv.conf' file location hosts.equiv 'hosts.equiv' file location .rhosts '.rhosts' file location User's home directory .netrc '.netrc' file location User's home directory The host name could be, for example, myhost.mycompany.com. It is usually a good idea to set hosts, networks, services and protocols to point to your Windows directory, e.g.: hosts=c:\windows\hosts networks=c:\windows\networks services=c:\windows\services protocols=c:\windows\protocol `hosts.equiv', `.rhosts' and `.netrc' are for remote command execution - *Note netrc::. libsocket will look for `.rhosts' and `.netrc' in the current user's home directory with the names `.rhosts', `rhosts', `rhosts' and `.netrc', `netrc' and `_netrc' respectively. The files specified in `lsck.cfg' are global and are only used if none were found in the user's home directory. The home directory is specified by the environment variable `HOME'. The wsock and csock Sections ---------------------------- Key Possible Values Default Value Enabled true, yes, 1, false, no, 0 true IPAddress Computer's IP address (Via auto-configuration) IPMask Computer's IP network mask (Via auto-configuration) Gateway Gateway's IP address (Via auto-configuration) DNS1Address DNS server 1's IP address (Via auto-configuration) DNS2Address DNS server 2's IP address (Via auto-configuration) DNS3Address DNS server 3's IP address (Via auto-configuration) DNS4Address DNS server 4's IP address (Via auto-configuration) The loopback network is always present and should not be included in the list above. The "loopback network" is an internal IP network with the address range 127.x.x.x (also written as 127.0.0.0/8). The "localhost" is the host's IP address on this network - 127.0.0.1. The unix Section ---------------- Key Possible Values Default Value Enabled true, yes, 1, false, no, 0 true host.conf ========= host.conf configures the order of name resolving. This file tells the networking libraries which name resolving resources to use, and in what order. Valid sources are `hosts', `bind' and `nis'. `hosts' refers to the file *Note hosts::, which contains name to IP address mappings. `bind' refers to DNS servers, which are configured elsewhere - *Note resolv.conf::. `nis' refers to Network Information Services (NIS) aka Yellow Pages (YP), which probably won't be very common in a Windows environment, but might be present if Unix hosts are used. [ NIS support is not present in libsocket. ] Basic Configuration ------------------- If you have DNS servers, the recommended order is `bind' then `hosts': order bind, hosts If you don't have a DNS server, then only `hosts' is required, like so: order hosts If you specify `bind' as well as `hosts' without a DNS server, then programs are likely to stall when resolving names. host.conf Options ----------------- `order' order SERVICE-1 ... SERVICE-N This specifies the order in which name resolving services should be used. Valid SERVICE options are `bind', `hosts' and NIS. `trim' trim DOMAINS ? `multi' multi (on|off) This makes the resolver return multiple matches from `hosts' (*note hosts::), which can be slow. `nospoof' nospoof (on|off|warn|warn off) ? `alert' alert (on|off) ? `reorder' reorder (on|off) ? Files ----- * /etc/host.conf (Linux) * e.g. c:\lsck\host.cfg (libsocket) resolv.conf =========== The resolver is a set of routines in the C library (in this case libsocket) that provide access to the Internet Domain Name System (DNS). The resolver configuration file contains information that is read by the resolver routines the first time they are invoked by a process. The file is designed to be human readable and contains a list of keywords with values that provide various types of resolver information. On a normally configured system this file should not be necessary. The only name server to be queried will be on the local machine, the domain name is determined from the host name, and the domain search path is constructed from the domain name. The different configuration options are: `nameserver' nameserver ADDRESS ADDRESS specifies the Internet address (in dot notation) of a name server that the resolver should query. Up to MAXNS (currently 3) name servers may be listed, one per keyword. If there are multiple servers, the resolver library queries them in the order listed. If no `nameserver' entries are present, the default is to use the name server on the local machine. (The algorithm used is to try a name server, and if the query times out, try the next, until out of name servers, then repeat trying all the name servers until a maximum number of retries are made). `domain' domain DOMAIN DOMAIN specifies the local domain name. Most queries for names within this domain can use short names relative to the local domain. If no `domain' entry is present, the domain is determined from the local host name returned by *Note gethostname: (libc)gethostname. The domain part is taken to be everything after the first `.'. Finally, if the host name does not contain a domain part, the root domain is assumed. `search' search DOMAIN-1 ... DOMAIN-N This specifies the search list for host-name lookup. The search list is normally determined from the local domain name; by default, it contains only the local domain name. This may be changed by listing the desired domain search path following the `search' keyword with spaces or tabs separating the names. Most resolver queries will be attempted using each component of the search path in turn until a match is found. Note that this process may be slow and will generate a lot of network traffic if the servers for the listed domains are not local, and that queries will time out if no server is available for one of the domains. The search list is currently limited to six domains with a total of 256 characters. `sortlist' sortlist ADDRESS-1[/NETMASK-1] ... ADDRESS-N[/NETMASK-N] Sortlist allows addresses returned by gethostbyname to be sorted (*note gethostbyname::). A sortlist is specified by IP ADDRESS and NETMASK pairs. The netmask is optional and defaults to the natural netmask of the net. The IP address and optional network pairs are separated by slashes. Up to 10 pairs may be specified. Here is an example: sortlist 130.155.160.0/255.255.240.0 130.155.0.0 `options' options OPTION-1 ... OPTION-N Options allows certain internal resolver variables to be modified. OPTION can be one of the following: `debug' `debug' sets RES_DEBUG in _res.options. `ndots' ndots:N `ndots' sets a threshold, N, for the number of dots which must appear in a name given to `res_query()' (*note res_query::) before an _initial absolute query_ will be made. The default for N is 1, meaning that if there are any dots in a name, the name will be tried first as an absolute name before any _search list_ elements are appended to it. The `domain' and `search' keywords are mutually exclusive. If more than one instance of these keywords is present, the last instance wins. The `search' keyword of a system's `resolv.conf' file can be overridden on a per-process basis by setting the environment variable `LOCALDOMAIN' to a space-separated list of search domains. The `options' keyword of a system's `resolv.conf' file can be amended on a per-process basis by setting the environment variable `RES_OPTIONS' to a space-separated list of resolver options as explained above under `options'. The keyword and value must appear on a single line, and the keyword (e.g. `nameserver') must start the line. The value follows the keyword, separated by white space. Files ----- * /etc/resolv.conf (Linux) * e.g. c:\lsck\resolv.cfg hostname ======== This section describes host name resolution. Hostnames are domains. A domain is a hierarchical, dot-separated list of subdomains. For example, the machine `monet', in the `Berkeley' subdomain of the `EDU' subdomain of the Internet Domain Name System would be represented as: monet.Berkeley.EDU (with no trailing dot). Hostnames are often used with network client and server programs, which must generally translate the name to an address for use. (This task is usually performed by the library routine *Note gethostbyname::.) The default method for resolving hostnames by the Internet name resolver is to follow RFC 1535's security recommendations. Actions can be taken by the administrator to override these recommendations and to have the resolver behave the same as earlier, non-RFC 1535 resolvers. The default method (using RFC 1535 guidelines) follows: If the name consists of a single component, i.e. contains no dot, and if the environment variable `HOSTALIASES' is set to the name of a file, that file is searched for a string matching the input hostname. The file should consist of lines made up of two strings separated by white-space, the first of which is the hostname alias, and the second of which is the complete hostname to be substituted for that alias. If a case-insensitive match is found between the hostname to be resolved and the first field of a line in the file, the substituted name is looked up with no further processing. If there is at least one dot in the name, then the name is first tried as is. The number of dots to cause this action is configurable by setting the threshold using the `ndots' option in `resolv.conf' (*note resolv.conf::) (default: `1'). If the name ends with a dot, the trailing dot is removed, and the remaining name is looked up (regardless of the setting of the 'ndots' option) and no further processing is done. If the input name does not end with a trailing dot, it is looked up by searching through a list of domains until a match is found. If neither the search option in the `resolv.conf' (*note resolv.conf::) file or the `LOCALDOMAIN' environment variable is used, then the search list of domains contains only the full domain specified by the domain option (in `resolv.conf') or the domain used in the local hostname (*note resolv.conf::). For example, if the `domain' option is set to `CS.Berkeley.EDU', then only CS.Berkeley.EDU will be in the search list and will be the only domain appended to the partial hostname, for example, `lithium', making `lithium.CS.Berkeley.EDU' the only name to be tried using the search list. If the search option is used in `resolv.conf' or the environment variable, `LOCALDOMAIN' is set by the user, then the search list will include what is set by these methods. For example, if the `search' option contained ICS.Berkeley.EDU CChem.Berkeley.EDU Berkeley.EDU then the partial hostname (e.g., `lithium') will be tried with each domainname appended (in the same order specified). The resulting hostnames that would be tried are: lithium.CS.Berkeley.EDU lithium.CChem.Berkeley.EDU lithium.Berkeley.EDU The environment variable `LOCALDOMAIN' overrides the `search' and `domain' options, and if both search and domain options are present in the resolver configuration file, then only the last one listed is used (*note resolv.conf::). If the name was not previously tried as-is (i.e., it fell below the `ndots' threshold or did not contain a dot), then the name as originally provided is attempted. hosts ===== `hosts' is the host name to IP address mapping file. This file tells the host name resolver the IP address corresponding to each host name. This is useful if there is no DNS server on the network. It can also be used if the DNS server does not have a record for a particular host name, but its IP address is known. A similar mapping for networks is performed by *Note networks::. The file is a plain ASCII file. Comments are denoted by a hash at the start of a line. Each line has the following format: IP-ADDRESS HOST-NAME [ALIAS] e.g. # hosts - host name to IP address translation file 127.0.0.1 localhost 192.168.0.2 gertrude 192.168.0.3 herbert 192.168.0.4 norman 192.168.0.5 jonathon jon There should always be a line refering to `localhost'. This is the local computer, and is always accessible. Note: Windows doesn't use the aliases, so you will need multiple lines for the same IP address to fake aliasing. Files ----- * /etc/hosts (Linux) * c:\windows\hosts (Windows) networks ======== `networks' is the network name to network IP address mapping file. This file tells the host name resolver the network component of an IP address corresponding to each network name. This is useful if there is no DNS server on the network. It can also be used if the DNS server does not have a record for a particular network name, but its IP address is known. A similar mapping for hosts is performed by *Note hosts::. The file is a plain ASCII file. Comments are denoted by a hash at the start of a line. Each line has the following format: IP-ADDRESS NETWORK-NAME [ALIAS] e.g. # networks - network name to IP address translation file 127 loopback 192.168.0 mynet intranet There should always be a line refering to `loopback'. This is the loopback device, and is always accessible. Note 1: Windows doesn't use the aliases, so you will need multiple lines for the same network IP address to fake aliasing. Note 2: The network IP address can be constructed from an IP address and network mask, e.g. if you have an IP address of 1.2.3.4 and a netmask of 255.255.0.0, then AND'ing them gives a network IP address of 1.2. Files ----- * /etc/networks (Linux) * c:\windows\networks (Windows, libsocket) services ======== `services' is the Internet network services list file. `services' is a plain ASCII file providing a mapping between friendly textual names for internet services, and their underlying assigned port numbers and protocol types. Every networking program should look into this file to get the port number (and protocol) for its service. The following C library routines support querying `services' from programs: * *Note getservent:: * *Note getservbyname:: * *Note getservbyport:: * *Note setservent:: * *Note endservent:: Port numbers are assigned by the IANA (Internet Assigned Numbers Authority), and their current policy is to assign both TCP and UDP protocols when assigning a port number. Therefore, most entries will have two entries, even for TCP only services. Port numbers below 1024 (so-called 'low numbered' ports) can only be bound to by root (*note bind::). This is so that clients connecting to low numbered ports can trust that the service running on the port is the standard implementation, and not a rogue service run by a user of the machine. Well-known port numbers specified by the IANA are normally located in this root only space. The presence of an entry for a service in the `services' file does not necessarily mean that the service is currently running on the machine. The location of the `services' file is defined by `_PATH_SERVICES' in `/usr/include/netdb.h'. This is usually set to `/etc/services'. Each line describes one service, and is of the form: SERVICE-NAME PORT PROTOCOL [ALIAS-1 ... ALIAS-N] where: SERVICE-NAME This is the friendly name the service is known by and looked up under. It is case sensitive. Often, the client program is named after the SERVICE-NAME. PORT This is the port number (in decimal) to use for this service. PROTOCOL This is the type of protocol to be used. This field should match an entry in the protocols file - *Note protocols::. Typical values include `tcp' and `udp'. ALIAS-N These are optional space or tab separated names for this service Again, the names are case sensitive. Either spaces or tabs may be used to separate the fields. Comments are started by the hash sign (#) and continue until the end of the line. Blank lines are skipped. The SERVICE-NAME should begin in the first column of the file, since leading spaces are not stripped. A SERVICE-NAME can be any printable characters excluding space and tab, however, a conservative choice of characters should be used to minimise inter-operability problems. Eg: a-z, 0-9, and hyphen (`-') would seem a sensible choice. Lines not matching this format should not be present in the file. (Currently, they are silently skipped by `getservent()', `getservbyname()' and `getservbyport()'. However, this behaviour should not be relied on.) As a backwards compatibility feature, the slash (/) between the PORT number and PROTOCOL name can in fact be either a slash or a comma (`,'). Use of the comma in modern installations is depreciated. This file might be distributed over a network using a network-wide naming service like Yellow Pages/NIS or BIND/Hesiod. A sample `services' file might look like this: netstat 15/tcp qotd 17/tcp quote msp 18/tcp # message send protocol msp 18/udp # message send protocol chargen 19/tcp ttytst source chargen 19/udp ttytst source ftp 21/tcp # 22 - unassigned telnet 23/tcp Files ----- * /etc/services (Linux) * c:\windows\services (Windows, libsocket) protocols ========= `protocols' is the protocols definition file. This file is a plain ASCII file, describing the various DARPA internet protocols that are available from the TCP/IP subsystem. It should be consulted instead of using the numbers in the ARPA include files, or, even worse, just guessing them. These numbers will occur in the protocol field of any IP header. Keep this file untouched since changes would result in incorrect IP packages. Protocol numbers and names are specified by the DDN Network Information Center. Each line is of the following format: PROTOCOL-NAME PROTOCOL-NUMBER [ALIAS-1 ... ALIAS-N] where the fields are delimited by spaces or tabs. Empty lines and lines starting with a hash mark (#) are ignored. Remainder of lines are also ignored from the occurrence of a hash mark. The field descriptions are: PROTOCOL-NAME The native name for the protocol. For example IP, TCP or UDP. PROTOCOL-NUMBER The official number for this protocol as it will appear within the IP header. ALIAS Optional aliases for the protocol. This file might be distributed over a network using a networkwide naming service like Yellow Pages/NIS or BIND/Hesoid. Files ----- * /etc/protocols (Linux) * c:\windows\protocol (Windows, libsocket) netrc ===== netrc configures auto-logins for remote hosts. [ This was taken from the man page ftp(1) from GNU inetutils. ] The `.netrc' file contains login and initialization information used by the auto-login process. It resides in the user's home directory. The following tokens are recognized; they may be separated by spaces, tabs, or new-lines: `machine' machine NAME This identifies a remote machine NAME. The auto-login process searches the `.netrc' file for a `machine' token that matches the remote machine specified on the ftp(1) command line or as an `open' command argument. Once a match is made, the subsequent `.netrc' tokens are processed, stopping when the end of file is reached or another `machine' or a `default' token is encountered. `default' default NAME This is the same as `machine' except that `default' matches any name. There can be only one `default' token, and it must be after all `machine' tokens. This is normally used as: default login anonymous password USER@SITE thereby giving the user automatic anonymous ftp login to machines not specified in `.netrc'. This can be overridden by using the `-n' flag to disable auto-login. `login' login NAME password PASSWORD If this token is present, the auto-login process will initiate a login using the specified NAME. If the PASSWORD token is present, the auto-login process will supply the specified string if the remote server requires a password as part of the login process. Note that if this token is present in the `.netrc' file for any user other than anonymous, ftp(1) will abort the auto-login process if the `.netrc' is readable by anyone besides the user. `account' account STRING This supplies an additional account password. If this token is present, the auto-login process will supply the specified string if the remote server requires an additional account password, or the auto-login process will initiate an `ACCT' command if it does not. `macdef' macdef NAME This defines a macro. This token functions like the ftp(1) `macdef' command functions. A macro is defined with the specified name; its contents begin with the next `.netrc' line and continue until a null line (consecutive new-line characters) is encountered. If a macro named `init' is defined, it is automatically executed as the last step in the auto-login process. Files ----- * $HOME/.netrc * $HOME/netrc * As specified in libsocket configuration file Miscellaneous Information ************************* mailaddr ======== This section gives a brief introduction to SMTP mail addresses, as used on the Internet. These addresses are in the general format user@domain where a DOMAIN is a hierarchical dot separated list of subdomains. For example, the addresses eric@monet.berkeley.edu Eric Allman eric@monet.berkeley.edu (Eric Allman) are valid forms of the same address. The domain part (`monet.berkeley.edu') may be the name of an internet host, or it may be a logical mail address. The domain part is not case sensitive. The local part (`eric') is often a user name, but its meaning is defined by the local software. It can be case sensitive, but usually isn't. If you see a local-part that looks like garbage, it is usually because of a gateway between an internal e-mail system and the net, here are some examples: "surname/admd=telemail/c=us/o=hp/prmd=hp"@some.where USER%SOMETHING@some.where machine!machine!name@some.where I2461572@some.where (These are, respectively, an X.400 gateway, a gateway to an arbitrary inernal mail system that lacks proper internet support, an UUCP gateway, and the last one is just boring username policy.) The real-name part (`Eric Allman') can either be placed first, outside <>, or last, inside (). (Strictly speaking the two aren't the same, but the difference is outside the scope of this page.) The name may have to be quoted using "" if it contains certain characters, most commonly `.': "Eric P. Allman" Abbreviation ------------ Many mail systems let users abbreviate the domain name. For instance, users at berkeley.edu may get away with `eric@monet' to send mail to Eric Allman. This behavior is deprecated. Route-addrs. ------------ Under some circumstances it may be necessary to route a message through several hosts to get it to the final destination. Normally this happens automatically and invisibly, but sometimes not, particularly with old and broken software. Addresses which show these relays are termed "route-addrs". These use the syntax: <@hosta,@hostb:user@hostc> This specifies that the message should be sent to hosta, from there to hostb, and finally to hostc. Some hosts disregard route-addrs and send directly to hostc. Route-addrs occur frequently on return addresses, since these are generally augmented by the software at each host. It is generally possible to ignore all but the `user@hostc' part of the address to determine the actual sender. Postmaster ---------- Every site is required to have a user or user alias designated "postmaster" to which problems with the mail system may be addressed. The "postmaster" address is not case sensitive. Frequently Asked Questions -------------------------- rtfm.mit.edu and many mirrors store a collection of FAQs. Please find and use a nearby FAQ archive; there are dozens or hundreds around the world. Known Bugs ********** Winsock 1.x Interface - wsock ============================= * Broadcasts do not seem to work. It does not appear to be possible to enable them via the `setsockopt()' call. * Support for out-of-band (OOB) data is incomplete. For instance, there is no support for `SO_OOBINLINE' or a `SIGURG' handler. Winsock 2.x Interface - csock ============================= The Winsock 2.x support is provided by SOCK.VXD from the Windows '95 port of the Coda Network File System. The following are bugs in SOCK.VXD: * SOCK.VXD's sockets always behave as though the socket option `SO_REUSEADDR' is set, so local addresses are reused on the `bind()' call. * SOCK.VXD always closes stream sockets by sending a RST. This causes protocols that require graceful closures to fail, e.g. FTP data transfers. * SOCK.VXD seems to have problems receiving/sending more than 32K through a stream socket. The symptoms are that the DOS box blocks in SOCK.VXD (i.e. Ctrl+C will not kill the program and the DOS box has to be forcefully closed). * SOCK.VXD's `getsockname()' call does not seem to work. libsocket attempts to circumvent this by using a table of IP addresses to determine the local IP address, but this can easily fail. * SOCK.VXD has no out-of-band (OOB) support. * SOCK.VXD has a limit of the number of connections that can be `accept()''d. The number of connections is that specified by the earlier `listen()' call. * There are problems using firewall software: * AtGuard causes libsocket programs to crash, because of an interaction with its virtual device driver, `IAMDRV.VXD'. * ZoneAlarm will block any traffic that doesn't go to ports it considers to be safe, e.g. DNS (UDP, port 23). The solution is to disable ZoneAlarm. This is far from ideal. There may be problems with other firewall software, but no other programs have been reported yet. There are a number of bugs in the csock inteface within libsocket: * SOCK.VXD's `recv()' function is for stream sockets only; its `recvfrom()' function is for datagrams only. The csock interface does not distinguish properly between these two - i.e. it does not map the BSD socket call `recvfrom()' on a stream socket onto SOCK.VXD's `recv()' call. Common TCP/IP Bugs ================== The auto-configuration code does not work for dial-up or WAN links. It should work on LANs for statically or dynamically (DHCP) assigned IP addresses. A method is needed that will obtain the IP address information successfully in all cases. Unix Domain Sockets Interface - unix ==================================== The Unix domain socket code is an alpha state. It uses pairs of LAN Manager mailslots to implement bidirectional communication. It was written using the assumption that local mailslots are 100% reliable. Mailslots are not reliable; hence the code needs to be rewritten to cope with data loss. Windows NT ========== libsocket programs crash on exit on Windows NT. Although Windows NT is not supported by libsocket, these programs should abort gracefully. Credits ******* The following people have contributed to libsocket. The list is in no particular order. A big thank you to all those listed! * Dan M. Hedlund `http://www.geocities.com/SiliconValley/Peaks/8523/' His Wsock library is the base of this library. * Alfons Hoogervorst `http://www.hoogervorst.demon.nl/' His dsock library helped Indrek to get select() and blocking recv() calls work. He also contributed some information on how to obtain Windows machine and DNS IP addresses. * The Regdos Group `http://www.hoogervorst.demon.nl/' They contributed the registry-access code that is used to automatically find out some IP settings. Alfons is the maintainer. * Michael Callahan, Peter Braam and the Coda Project `http://www.coda.cs.cmu.edu/' For Win95 port of the Coda network file system, a VxD for BSD socket networking was produced. This enabled me to add Winsock 2 support to libsocket. This is something I had been trying to do for over a year, so I am extremely grateful and happy that this has happened! Big thanks. - _Rich_ * Heiko Jappe He has a very nice habit of finding all the nastiest bugs and reporting them. There would be some very bad "features" in the library without him. - _Indrek_ * Wojciech Galazka He pointed out some bugs and has some great ideas. A man with an open mind. - _Indrek_ - I agree - _Rich_ * Indrek Mandre `http://www.pld.ttu.ee/~indrek/' Thanks to Indrek for writing the library in the first place, letting me contribute to it, and then, gulp, trusting me to look after it. This man has a lot faith and trust! Thanks also for providing a mirror site. - _Rich_ * Petr Frisch Thanks to Petr for finding that libsocket's non-blocking sockets didn't work properly, and for informing me how they should work. - _Rich_ * Vlad Pambucol Thanks to Vlad for noticing that his data was being mangled by libsocket, which lead to me finding an absolutely _huge_ bug! - _Rich_ * Philippe Hanrigou Thanks to Phillipe for trying to port BSD traceroute, finding problems and then diving into libsocket's internals to find out the problem. Bravery! Thanks for the feedback. - _Rich_ * Ove Kaaven Thanks to Ove for providing me with information about how Windows 3.11 stores its DNS IP addresses. Thanks for your packet driver code - sorry I was unable to integrate it into libsocket. - _Rich_ * Michael Mauch Thanks to Michael for pointing out that the resolving code didn't open the files in text mode, which meant that setting fmode to binary could lead to the resolving code failing inexplicably. - _Rich_ * Alex Fiori Thanks for providing a mirror site for a while. - _Rich_ * Federico Bianchi Thanks for sending me a *huge* amount of networking information. I hope I actually have enough time at some point to something useful with it ;) Thanks for the support and ideas! - _Rich_ * Alain Magloire Thanks for all the advice on sockets on Unix, POSIX, etc. Thanks for motivating me to add Unix domain socket support. I think libsocket will improve and prosper greatly with your support! - _Rich_ * Beej `http://www.ecst.csuchico.edu/~beej/' Thanks for letting me distribute your sockets programming guide with libsocket. - _Rich_ * Jason Winnebeck `http://skyscraper.fortunecity.com/solarcity/552/' Thanks for being patient, giving me copious debugging info and feedback generally! - _Rich_ * Eli Zaretskii For his continual advice and help with all things DJGPP - an inspiration. * DJ Delorie For the DJGPP phenomenom! Thanks to everyone else who has shown interest in libsocket, and has mailed me to say they are using it. Please continue to do this! Changelog ********* Version 0.8.1 ???? ================== These changes are in no particular order: * `recv()' and `send()' should not hang the DOS box anymore, when waiting for input/output with SOCK.VXD and Winsock 2. * Various texinfo documentation updates, to be consistent with DJGPP libc's documentation style. Version 0.8.0 2000-11-16 ======================== These changes are in no particular order: * Fixed bug in version string construction (*note __lsck_get_version::). * Documentation fixes: * Clarified `FIONBIO' versus `O_NONBLOCK' (*note ioctl_list::). * `gethostname()' page now describes how the host name is discovered (*note gethostname::). * Fixed the DSMs for installation with pakke. * Fixed a bug in the auto-configuration code, where some network cards were ignored due to a bug in the registry entry parsing. * Added `tags', `id' and `ID' targets to Makefile, for building Emacs tags and GNU id-utils files respectively. * Fixed a big in `gethostname()'; previously EINVAL was erroneously returned for buffers larger than `MAXHOSTNAME'. This broke the name resolving code for automatic configuration. * Documented how bash and libsocket's auto-configuration code interacts with regard to `$HOSTNAME' (*note libsocket and environment variables::). * Fixed the DNS server questions in netsetup (*note Introduction: (netsetup)Introduction.). The input routines also now perform more validation. * Fixed header files so that #include lines are before checks for C++ (extern "C", etc.). * Fixed header `netinet/in.h' to work around a compiler bug in g++ 2.95.x. The structure `struct ip_opts' is not defined, when using g++ 2.95.x. * "Beej's Guide to Network Programming" and the libsocket demos are now included in the binary distribution. Version 0.8.0 Pre 1 2000-09-11 ============================== These changes are in no particular order: * Texinfo documentation: corrected copyright message to include Alain Magloire in info version; now distributed under GNU FDL. * Fixed assembly code to work with binutils 2.9.5.1 beta and later. Hopefully libsocket will build with _all_ versions of binutils now. Thanks to Eli Zaretskii for his help & suggestions. * Problems using libsocket with firewall software were discovered and documented (*note Known Bugs::). Thanks to Robert, Tim van Holder. * The demo `solist' now builds on Linux. * The source distribution requires GNU shellutils to build; this is now documented. * The binary distribution had dependency generation for the demo and netsetup directories. This is no longer included - it was not very useful and it meant that GNU shellutils was required to build (only `echo' was actually required). * `all' target now fixed in source distribution, so that it doesn't run `netsetup' by default. This problem stopped cross-compilation from completing. * The error code `ELOOP' is now defined conditionally in `include/lsck/errno.h', so as not to conflict with DJGPP 2.04's symlink support (DJGPP 2.04 is currently in development). Thanks to Laurynas Biveinis. * Finished error messages for all libsocket-specific error messages in `src/newerror.c'. * Fixed the code for parsing the DHCP settings from the registry. Thanks to Tim van Holder. Version 0.7.4 Beta 4 2000-05-28 =============================== These changes are in no particular order: * Added a guide to configuration and usage of libsocket programs (a user guide), to be distributed with programs built using libsocket. This was added to the `redist' directory. * The auto-configuration from the registry was found to be buggy and was fixed. * Problems were found compiling with gcc 2.95.x: * The inline assembly used by several of the source files was buggy, but was compiled without error with previous versions of gcc. The assembly code was fixed. See the section in the gcc FAQ about spilled registers. * The resolver code used pragmas to generate weak symbols that could be overridden by Linux threading libraries. These generated warnings with gcc 2.95.2 (whose DJGPP port had no weak symbol support at the time) and errors with a cross-compiler (egcs-2.91.66 19990314 (egcs-1.1.2 release)) on Linux. The pragmas were removed. This involved implementing `readv()' and `writev()'. * A new demo was added, `solist', to list the available socket options for UDP and TCP options. * netsetup previously only configured one DNS server - now the user can specify multiple DNS servers. * The top-level source Makefile, `Makefile.src', used to create the directory `lib' when building the library. This was moved to `src/Makefile', since this is where the library is actually built. * The `uninstall' Makefile target previously failed to uninstall some files from `$DJDIR/include/arpa'. This has been fixed. * The `socketpair()' function has been implemented, but only for Unix domain sockets (see below). * The Unix domain socket support is now much better. It is still alpha-quality code, which means there are definitely some bugs/problems with it. * Added the POSIX function `sockatmark()', which always fails. * Changes were made to better conform with Unix98 description of the sockets interface: added `SHUT_*' definitions for `shutdown()'; use of `size_t', `ssize_t' instead of `int'. * Fixed `fcntl()' so that it accepts more than one option simultaneously. Previously passing more than one option OR'd together would have caused `fcntl()' to fail. * Fixed `accept()' to work when the peer address is NULL. This error was pointed out by Alain Magloire. * Many simplifications in socket functions due to removal of `__lsck_init()' calls and use of `isfdtype()', as suggested by Alain Magloire. * The library now overrides DJGPP's `gethostname()', `sethostname()', `perror()', `strerror()' and `uname()' functions. The old libsocket functions `__lsck_gethostname()', `__lsck_sethostname()', `lsck_perror()' and `lsck_strerror()' are now deprecated, but will still work. * Fixed `gethostname()', `sethostname()', `getdomainname()', `setdomainname()', so that they interact properly. * `send()', `sendto()' now raise SIGPIPE when sending data on a connection that has had its outbound channel shutdown. * The Winsock 2 interface (csock) now has basic read-only (i.e. `getsockopt()') support for the following socket options: * SO_REUSEADDR * SO_RCVBUF * SO_RCVLOWAT * SO_RCVTIMEO * SO_SNDBUF * SO_SNDLOWAT * SO_SNDTIMEO * Fixed many issues with datagrams with regard to `connect()', `sendto()'. Hopefully not too many bugs have been introduced here. * Many issues with WSOCK.VXD, used for Winsock 1 support, were sorted out. These included issues such as the size of `struct so_linger' passed to WSOCK.VXD, supported socket options, etc. * SOCK.VXD is no longer unloaded by the csock interface (Winsock 2 support). This caused General Protection Faults (GPFs) on occasion. * Removed VDHCP.VXD support code from libsocket, because it was unused and did not work. * DJGPP 2.02 now required - libsocket uses DJGPP 2.02's new File System Extension features. The code is tidier as a result. * The separation between the BSD layer and the interface layer was improved. This should allow other interfaces (e.g. DOS support) to be added much more easily. * Added the header file `lsck/copyrite.h', containing information about the version of libsocket (version numbers, etc.). * Switched from man pages to info documentation. The horrible long filename and short filename Makefile targets are no longer needed. * Project management: libsocket has been placed in CVS; all source files now have unique names, to ease debugging, editing, etc.; the libsocket web pages have been separated from sources; netsetup is now distributed under the GNU GPL. Version 0.7.4 Beta 3 1999-05-06 =============================== * Fixed some of the debugging messages in `src/inet/ghstnmad.c', `src/inet/r_init.c', `src/csock/c_initnt.c'. * Man pages now go in `man/' off the DJGPP directory, not in `share/man/' as previously. * Fixed bug in `sys/socket.h', which meant that `u_int' was undefined when using `SO_DONTLINGER'. `sys/socket.h' now includes `lsck/bsdtypes.h' too, to define `u_int'. * Fixed bug in `src/initnt.c' where csock interface was not uninitialised. * Fixed bug in `src/fcntl.c' that meant the logical NOT of the true value would be obtained doing e.g.: fcntl(sock, F_GETFL, O_NONBLOCK) * Added Unix domain socket support. THIS IS IN AN ALPHA TEST STATE. It's extremely buggy. * Removed nasty hack that sets protocol number when a protocol of 0 is used. Now a nice mapping table is used. * Fixed bug in `src/csock/c_recv.c' in `__csock_recvfrom()'. It should now return the address correctly. Also, it should work if the FROM parameter is `NULL'. * Fixed bug in `src/wsock/w_recv.c' which always returned the address, even if the FROM parameter were NULL. * Added support for `FIONREAD' with `ioctl()' for Winsock 1.x module (wsock). * Fixed `src/csock/c_select.c' functions `__csock_select()', `__csock_select_wait()' so they actually work properly. * Added POSIX function `isfdtype()'. However, necessary includes are in `sys/socket.h' rather than `sys/stat.h'. * Added `fcntl()' support for csock interface. * Fixed bugs in non-blocking ioctl `FIONBIO' for both wsock & csock. * Moved to an interface descriptor, so that the BSD calls now do not need to know the internals of each interface in *any* way. The interface descriptor also includes address and routing tables. The code was updated to build the address tables correctly for each IP address, including the loopback network. * Fixed problem with `select()' on socket that lead to select'ing for reading always succeeded if the socket was ready for writing. * Source code reorganisation: Old name(s) New name(s) src/wsock/win311 src/win3x src/wsock/win95 src/win9x src/wsock/win95/*.c src/win9x/w9x_*.c (& some names altered) * Discovered that the Linux ioctls added were actually BSD-ish, so renamed `demo/linioctl.c' to `demo/ioctl.c'. The refs in the man pages have also been changed. * `accept()' & `closesocket()' memory leaks fixed. * `connect()' fixed for non-blocking operation. * `getsockopt()' for wsock interface (`src/wsock/w_sckopt.c') now converts errors returned by `SO_ERROR' from Winsock to BSD errors. * Debugging output can now be enabled/disabled with a function call or the 'debug' key in the 'main' section of the configuration file. Version 0.7.4 Beta 2 1999-02-28 =============================== * Added Winsock 2 support. Yes, finally! However, the support isn't as complete as for Winsock 1.x. * The resolver code again looks in the Windows directory for its files, if their location has not been specified. This was the previous behaviour. * Fixed the `select()' for sockets bug (again). * 'linger'ing should now work correctly - added a wrapper, since Winsock uses short ints & DJGPP defaults to long int's. * Fixed `connect()' so it stores the local socket name. * Fixed the DHCP code to work with multiple addresses. * Added 'Enabled' key to all interface section. * Documentation: Updated install information. Added a new version of man2html, now called m2h, that can now generate HTML with short filenames, for easier & faster browsing of the library reference. Sorted out the supplementary information included. * Makefiles: Streamlined a couple of Makefiles. Version 0.7.4 Beta 1 1999-02-04 =============================== There are probably many more changes than this, as I've been working on this version for a while, trying to add DOS support. It still seems to work the same as version 0.7.3 though :( Still no support for DOS, Win98, etc. * Moved to standard header files. This means that winsock.h and ws.h do not exist anymore, as they have been incorporated into other header files. The problems with ioctls have been also been fixed in `sys/socket.h'. * ioctls.h _(New)_ * netdb.h * resolv.h * arpa/ftp.h _(New)_ * arpa/inet.h * arpa/nameser.h * arpa/telnet.h _(New)_ * arpa/tftp.h _(New)_ * net/if.h _(New)_ * netinet/in.h * sys/socket.h * Added more code to the layer between the BSD socket functions and the actual networking code, while trying to implement DOS networking. It should be easier to add other network transports now - only Winsock is currently supported. libsocket also stores networking information for each transport. * BSD functions can now distinguish between socket file descriptors and normal file desciptors and will return the `ENOTSOCK' error message as appropriate. * Modified the assembly code to use the proper size of the ES register. * Added support for some Linux ioctls: `SIOCGIFNAME', `SIOCGIFADDR', `SIOCGIFDSTADDR', `SIOCGIFNETMASK'. * Added some Win95 DHCP code that allows auto-configuration from the registry. * Switched from `LIBSOCKET' to `LSCK' environment variable. Also made the configuration more flexible by the use of a configuration file. * Added a patch for libc so that `perror()' and `strerror()' give proper error messages for BSD socket errors. * Compilation tested with DJGPP 2.02 beta - works fine. * The remote login code has been reinserted. Previously I thought this code was for Remote Procedure Calls (RPC) and I removed it because I didn't think it worked. This was short-sighted of me - sorry. * Added man pages for: * ioctl_list(2) * rcmd(3) * readv(3) * ruserok(3) * rresvport(3) * stdarg(3) * va_arg(3) * va_start(3) * va_end(3) * writev(3) * netrc(5) * Bugs: Fixed the bug in `resolv_conf_getdomainname()' in `src/config/domname.c'. Fixed the bug in the Windows 3.11 DNS IP address code. Fixed the dependency checking, so it works again (oops). The problems with ioctls have also been fixed (see above). Finally nailed the bizarre `select()' bugs (phew). * Makefiles: Created a shared Makefile for shared rules between the source and binary distributions - hopefully this will reduce errors. Added an 'uninstallation' target for man pages (uninstallman), plus 'sfnman' and 'lfnman' targets for using the man pages with short filenames and long filenames (after installation via installman), so they can be used under DOS too. The library is now compiled for 386s rather 486s, and the option `-Werror' is only used when compiling debug versions. Version 0.7.3 1998-8-18 ======================= * Rearranged include files so they have their own directory - lsck. These can be included using lines like: #include The include files have been heavily reorganised, but existing programs shouldn't have to be changed. * libsocket's internal functions were renamed so the prefix `ls_' was changed to `lsck_'. * Added support to netsetup for the networks file, which allows mapping of domain names to network IP addresses - see the man page networks(5). Also fixed a couple of typos in netsetup's messages. * Added support for auto-configuration with Windows for Workgroups 3.11. The DNS IP address is determined from a section in system.ini. * Restructured the library to allow addition of packet driver code. Added `lsck_perror()' and `lsck_strerror()' functions, which work as `perror()' and `strerror()', but print/return error messages for socket errors too, unlike the libc versions. * Bugs: Configuration files now opened in text mode rather than the default file mode; Winsock initialisation now uses the correct ID for WSOCK2.VXD rather than the old one, which was wrong; name server now defaults to using hosts file if host.conf is not present, rather than hanging; `resolv_conf_getdomainname()' in `src/config/domname.c' now looks for the various filename combinations possible (created long, read short, etc.); file extension handling of `__FSEXT_ready' in `src/fsext.c'; more checks are done on socket function parameters; fixed bugs in the RAS code and the DNS IP list code (`lsck_getdnsaddrs()'). * Demos: The demo program `demo/internal.c' was renamed to `demo/diag.c' and modified to give lots of diagnostic information about libsocket's auto-configuration, in addition to demonstrating the internal functions. The demo `demo/netnet.c' was added to demonstrate lookups from the networks file. httpget can now cope with URLs without a trailing slash, e.g. `http://myhost'. * Makefiles: Demos now don't have their debugging information stripped. Added an uninstall target that removes include files and libraries from the DJGPP directory tree. The source distribution Makefile now creates the lib/ directory if it does not already exist. Also fixed clean targets in top-level Makefiles. * Removals: `src/resolve/rcmd.c', `src/resolve/rexec.c' and `src/resolve/rusrpass.c' were removed because they are untested and probably won't work as they rely on functions DJGPP doesn't support (properly). They implement(ed) remote execution of commands. I will put these back if there is demand for them. The man pages for the `WS_*' functions were removed as the functions no longer exist. * Documentation: Added Indrek Mandre's kewl buttons; added questions to the FAQ; other updates. Version 0.7.2 1998-6-12 ======================= * The library by default comes ready for building short filename programs - use: make lfn to build long filename programs. * Fixed `read()' and `write()'. Previously they didn't return the correct values for non-blocking sockets when no data was present. winsock.h is now installed to support non-blocking sockets properly - please see question 3.6 of the FAQ for more details. * Added support for `F_GETFL' parameter on `fcntl()'. * Added some Winsock 2 constants to the include files. * Bugs: Fixed the memory problem I introduced with last version, that leads to junk being returned by `recv()' sometimes. Also fixed `send()', `recv()', `sendto()', `recvfrom()', `getpeername()', `getsockname()', `getsockopt()' and `setsockopt()' to avoid data loss / rubbish being returned. * Configuration: The configuration files should now be found and read, no matter what combination of short and long filenames they were created with and are being read with. libsocket now looks for several possible filenames. * Documentation: Indrek Mandre redesigned the pages. The documentation on the Web site should now be the same as that in the archive, or more up-to-date. The HTML pages all have short filenames, and therefore can be viewed on any version of Windows with a browser. The latest version of man2html (1.2) is also included. * Makefiles: Fixed demo/Makefile. Added some new targets to cope with short and long filename issues (`make lfn' and `make sfn'). Added debug and nodebug targets to binary distribution. * Man pages: Added man pages from Linux for `read()', `write()', `fcntl()', `ioctl()' and `select()'. Fixed mistakes in a couple of the libsocket man pages. Version 0.7.1 1998-5-12 ======================= * Fixed some ambiguities in conditions in the resolver code, so that the source could be compiled with gcc 2.8.0 (and later?). * Added code to query the DHCP VxD, to obtain more DNS addresses automatically. * Tidied up some of the code. * Fixed many memory leaks and reduced memory usage slightly. * Fixed some bugs in the DNS address obtaining code. * `gethostname()' will no longer return spaces in host names. * Fixed a bug in `callvxd.c' that lead to nearly *all* socket functions failing :( * Client demo now has name resolving. * Found a bug in Netsetup that created host.conf incorrectly when no DNS server was present, leading to the computer appearing to hang when resolving names. Also fixed some errors in the Netsetup Makefile. * Slight updates to the FAQ. * Added a man page for host.conf. * Added two new targets, debug and nodebug, to the top-level Makefile to create Makefile.cfg for debugging and non-debugging builds of the library. * Moved the library into the `contrib/' tree and added manifest files. Version 0.7.0 Work-in-progress 1998-5-3 ======================================= * Richard Dawe took over maintainance of the library. * The source files renamed to have short filenames. This lead to successful compilation after typing `SET LFN=N' at the DOS prompt. * The Regdos Group's registry code was incorporated, to allow automatic configuration using registry settings. * Added Winsock 2 detection. Creation of sockets fails, in order to prevent protection faults. * Rearranged the library, and created binary and source distributions. * Fixed a bug in the VxD calling code, pointed out by George Foot (Later: This was actually a mistake.). * Wrote some new documentation, including a FAQ, and updated the old documentation. * Fixed `getdomainname()' to look at the environment variable `LOCALDOMAIN', resolv.conf or the registry, so it's more likely to succeed. * Modified `WS_init()' to return errors. * Added support for the enviroment variable `LIBSOCKET', so that configuration files could be placed somewhere other than in the Windows directory. * Upgraded to the latest version of man2html, the program that converts man pages into HTML. * Modified resit to use command-line parameters as well as prompting for a name (e.g. the command form `resit jimbo' now works). * Fixed bug in Netsetup. * Added some defines: `FIONREAD', `FIONBIO'. * Fixed `socket()' and `accept()' calls. * Added `select()' demo, `demo/select.c'. * The library now works with C++. Version 0.6 1997-12-02 ====================== * Made workaround to DJGPP'S FSEXT bug, thanks to Heiko Jappe. * Fixed `close()', now `fopen()' after creating and closing sockets works. * Added a huge amount of documentation by Richard Dawe. * Added netsetup script by Richard Dawe. * Lots of minor bugs fixed. * Added `fcntl()' call and defined some new flags that I would like to see in future DJGPP versions: `O_NDELAY' and `O_FNDELAY'. Version 0.5 1997-10-11 ====================== * Fixed misfeatures in Makefiles pointed out by Laszlo Vecsey. Created one global Makefile.cfg. * Name resolving now works. * Wrote new demo resit that demonstrates name resolving. Version 0.4 1997-09-15 ====================== * Fixed the bugfix made in `recv()'. I discovered that programs crash after connect on many Windows '95 installations. Version 0.3 1997-08-28 ====================== * Fixed bug in `recv()'/`recvfrom()' (blocking and return value and EOF condition). * `connect()' now waits for Windows; this means `send()' just after `connect()' works now. * Wrote new demo httpget that gets http files from WWW servers. Version 0.2 1997-08-22 ====================== * Fixed Makefile bug when make all gave errors at demo directory. * Wrote client.c and server.c as demos at demo directory. License ******* Portions of libsocket are distributed under different terms; the table below lists the base directories for these sources: `src/sxbxinet' Copyright (C) 1985-1993 Regents of the University of California; `src' Copyright (C) 1991, 1992 Free Software Foundation Inc.; `src/win9x/regdos' Copyright (C) 1997, 1998 by the RegDos Group. `src/oldlibc' Copyright (C) 1994-1997 by DJ Delorie The remainder of libsocket is distributed under the GNU Library General Public License (GNU LGPL): GNU LIBRARY GENERAL PUBLIC LICENSE ********************************** Version 2, June 1991 Copyright (C) 1991 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.] Preamble ======== The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it. For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights. Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library. Also, for each distributor's protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don't assume that anything in it is the same as in the ordinary license. The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a utility program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such. Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better. However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries. The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, while the latter only works together with the library. Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one. TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Public License (also called "this License"). Each licensee is addressed as "you". A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a. The modified work must itself be a software library. b. You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. c. You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. d. If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. This option is useful when you wish to copy part of the code of the Library into a program that is not a library. 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. 6. As an exception to the Sections above, you may also compile or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: a. Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) b. Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. c. If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. d. Verify that the user has already received a copy of these materials or that you have already sent this user a copy. For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute. 7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things: a. Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. b. Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it. 10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 13. The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS GNU Free Documentation License ****************************** GNU Free Documentation License Version 1.1, March 2000 Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http:///www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. Concept Index ************* AtGuard firewall: See ``Known Bugs''. AtGuard firewall incompatibility: See ``Known Bugs''. Beej's Guide to Network Programming: See ``Introduction''. BSD sockets: See ``Introduction''. Coda Network File System helper driver: See ``Installation''. diag: See ``Introduction''. Diagnostic tool: See ``Introduction''. httpget: See ``Introduction''. Interprocess Communication: See ``Introduction''. IPC: See ``Introduction''. loopback: See ``lsck.cfg''. loopback device: See ``lsck.cfg''. loopback network: See ``lsck.cfg''. SOCK.VXD: See ``Installation''. sockets: See ``Introduction''. Winsock: See ``Introduction''. Winsock 2 support Virtual Device Driver: See ``Installation''. Winsock 2 support VxD: See ``Installation''. ZoneAlarm firewall: See ``Known Bugs''. ZoneAlarm firewall problems: See ``Known Bugs''. Function Index ************** __lsck_get_copyright: See ``__lsck_get_copyright''. __lsck_get_version: See ``__lsck_get_version''. accept: See ``accept''. bind: See ``bind''. connect: See ``connect''. dn_comp: See ``dn_comp''. dn_expand: See ``dn_expand''. endhostent: See ``endhostent''. endnetent: See ``endnetent''. endprotoent: See ``endprotoent''. endservent: See ``endservent''. getdomainname: See ``getdomainname''. gethostbyaddr: See ``gethostbyaddr''. gethostbyname: See ``gethostbyname''. gethostent: See ``gethostent''. gethostname: See ``gethostname''. getnetbyaddr: See ``getnetbyaddr''. getnetbyname: See ``getnetbyname''. getnetent: See ``getnetent''. getpeername: See ``getpeername''. getprotobyname: See ``getprotobyname''. getprotobynumber: See ``getprotobynumber''. getprotoent: See ``getprotoent''. getservbyname: See ``getservbyname''. getservbyport: See ``getservbyport''. getservent: See ``getservent''. getsockname: See ``getsockname''. getsockopt: See ``getsockopt''. herror: See ``herror''. if_freenameindex: See ``if_freenameindex''. if_indextoname: See ``if_indextoname''. if_nameindex: See ``if_nameindex''. if_nametoindex: See ``if_nametoindex''. inet_addr: See ``inet_addr''. inet_aton: See ``inet_aton''. inet_lnaof: See ``inet_lnaof''. inet_makeaddr: See ``inet_makeaddr''. inet_netof: See ``inet_netof''. inet_network: See ``inet_network''. inet_ntoa: See ``inet_ntoa''. inet_ntop: See ``inet_ntop''. inet_pton: See ``inet_pton''. isfdtype: See ``isfdtype''. listen: See ``listen''. rcmd: See ``rcmd''. readv: See ``readv''. recv: See ``recv''. recvfrom: See ``recvfrom''. res_init: See ``res_init''. res_mkquery: See ``res_mkquery''. res_query: See ``res_query''. res_querydomain: See ``res_querydomain''. res_search: See ``res_search''. res_send: See ``res_send''. rexec: See ``rexec''. rresvport: See ``rresvport''. ruserok: See ``ruserok''. send: See ``send''. sendto: See ``sendto''. setdomainname: See ``setdomainname''. sethostent: See ``sethostent''. sethostname: See ``sethostname''. setnetent: See ``setnetent''. setprotoent: See ``setprotoent''. setservent: See ``setservent''. setsockopt: See ``setsockopt''. shutdown: See ``shutdown''. sockatmark: See ``sockatmark''. socket: See ``socket''. socketpair: See ``socketpair''. writev: See ``writev''. Function Index ************** account: See ``netrc''. alert: See ``host.conf''. alias: See ``protocols''. alias-n: See ``services''. debug: See ``resolv.conf''. default: See ``netrc''. domain: See ``resolv.conf''. h_addr: See ``gethostbyname''. h_addr_list: See ``gethostbyname''. h_addrtype: See ``gethostbyname''. h_aliases: See ``gethostbyname''. h_length: See ``gethostbyname''. h_name: See ``gethostbyname''. login: See ``netrc''. LSCK_VERSION_MAJOR: See ``__lsck_get_version''. LSCK_VERSION_MINOR: See ``__lsck_get_version''. LSCK_VERSION_SUBMINOR: See ``__lsck_get_version''. macdef: See ``netrc''. machine: See ``netrc''. multi: See ``host.conf''. nameserver: See ``resolv.conf''. ndots: See ``resolv.conf''. nospoof: See ``host.conf''. options: See ``resolv.conf''. order: See ``host.conf''. port: See ``services''. protocol: See ``services''. protocol-name: See ``protocols''. protocol-number: See ``protocols''. reorder: See ``host.conf''. RES_AAONLY: See ``res_query''. RES_DEBUG: See ``res_query''. RES_DEFNAMES: See ``res_query''. RES_DNSRCH: See ``res_query''. RES_IGNTC: See ``res_query''. RES_INIT: See ``res_query''. RES_PRIMARY: See ``res_query''. RES_RECURSE: See ``res_query''. RES_STAYOPEN: See ``res_query''. RES_USEVC: See ``res_query''. search: See ``resolv.conf''. service-name: See ``services''. sortlist: See ``resolv.conf''. trim: See ``host.conf''. Table of Contents ***************** libsocket 0.8.0 Manual Introduction What is libsocket? How to get started What to do when things go wrong Contact Details Functional Categories io functions libsocket functions resolver functions rexec functions socket functions Alphabetical List accept bind connect dn_comp dn_expand endhostent endnetent endprotoent endservent getdomainname gethostbyaddr gethostbyname gethostent gethostname getnetbyaddr getnetbyname getnetent getpeername getprotobyname getprotobynumber getprotoent getservbyname getservbyport getservent getsockname getsockopt herror if_freenameindex if_indextoname if_nameindex if_nametoindex inet_addr inet_aton inet_lnaof inet_makeaddr inet_netof inet_network inet_ntoa inet_ntop inet_pton ioctl_list isfdtype listen __lsck_get_copyright __lsck_get_version rcmd readv recv recvfrom res_init res_mkquery res_query res_querydomain res_search res_send rexec rresvport ruserok send sendto setdomainname sethostent sethostname setnetent setprotoent setservent setsockopt shutdown sockatmark socket socketpair writev Unimplemented Installation Installing the Binary Distribution Installing the Documentation Distribution Installing the Source Distribution Required and Optional Packages Configuration and Compilation Installing the Winsock 2 Support Virtual Device Driver Getting Started Configuration libsocket and environment variables libsocket and bash lsck.cfg The main Section The wsock and csock Sections The unix Section host.conf Basic Configuration host.conf Options Files resolv.conf Files hostname hosts networks Files services protocols netrc Files Miscellaneous Information mailaddr Abbreviation Route-addrs. Postmaster Frequently Asked Questions Known Bugs Winsock 1.x Interface - wsock Winsock 2.x Interface - csock Common TCP/IP Bugs Unix Domain Sockets Interface - unix Windows NT Credits Changelog Version 0.8.1 ???? Version 0.8.0 2000-11-16 Version 0.8.0 Pre 1 2000-09-11 Version 0.7.4 Beta 4 2000-05-28 Version 0.7.4 Beta 3 1999-05-06 Version 0.7.4 Beta 2 1999-02-28 Version 0.7.4 Beta 1 1999-02-04 Version 0.7.3 1998-8-18 Version 0.7.2 1998-6-12 Version 0.7.1 1998-5-12 Version 0.7.0 Work-in-progress 1998-5-3 Version 0.6 1997-12-02 Version 0.5 1997-10-11 Version 0.4 1997-09-15 Version 0.3 1997-08-28 Version 0.2 1997-08-22 License GNU Free Documentation License Concept Index Function Index Function Index