@database bsdsocket.guide @Master bsdsocket.texi @Width 72 This is the AmigaGuide® file bsdsocket.guide, produced by Makeinfo-1.55 from the input file bsdsocket.texi. This file is: Copyright © 1994 AmiTCP/IP Group, Network Solutions Development Inc. All rights reserved. @Node Main "bsdsocket.guide" AMITCP/IP API Function Reference ******************************** @{" Disclaimer & Copyright " Link "Disclaimer & Copyright"} @{" Function Reference " Link "Function Reference"} @EndNode @Node "Disclaimer & Copyright" "bsdsocket.guide/Disclaimer & Copyright" @Next "Function Reference" @Prev "Main" @Toc "Main" Disclaimer & Copyright ********************** This manual is based on original documents from BSD net/2 release, which is hereby acknowledged: Copyright © 1982, 1986, 1988, 1990 Regents of the University of California. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgment: This product includes software developed by the University of California, Berkeley and its contributors. 4. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This manual is: Copyright © 1994 AmiTCP/IP Group, Network Solutions Development Inc. All rights reserved. @EndNode @Node "accept()" "bsdsocket.guide/accept()" @Next "bind()" @Toc "Function Reference" @{b}accept()@{ub} ======== @{i}NAME@{ui} @{b}accept@{ub} -- accept a connection on a socket @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}#include @{ui} @{i}int accept(int s, struct sockaddr * addr, int * addrlen)@{ui} @{i}D0 D0 A0 A1@{ui} @{i}DESCRIPTION@{ui} The argument @{b}s@{ub} is a socket that has been created with @{"socket()" Link "socket()"}, bound to an address with @{"bind()" Link "bind()"}, and is listening for connections after a @{"listen()" Link "listen()"}. The @{b}accept()@{ub} argument extracts the first connection request on the queue of pending connections, creates a new socket with the same properties of @{b}s@{ub} and allocates a new file descriptor for the socket. If no pending connections are present on the queue, and the socket is not marked as non-blocking, @{b}accept()@{ub} blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, @{b}accept()@{ub} returns an error as described below. The accepted socket is used to read and write data to and from the socket which connected to this one; it is not used to accept more connections. The original socket @{b}s@{ub} remains open. The argument @{b}addr@{ub} is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the @{b}addr@{ub} parameter is determined by the domain in which the communication is occurring. The @{b}addrlen@{ub} is a value-result parameter; it should initially contain the amount of space pointed to by @{b}addr@{ub}; on return it will contain the actual length (in bytes) of the address returned. This call is used with connection-based socket types, currently with @{b}SOCK_STREAM@{ub}. It is possible to @{"select()" Link "select()"} a socket for the purposes of doing an @{b}accept()@{ub} by selecting it for read. One can obtain user connection request data without confirming the connection by issuing a @{"recv()" Link "recv()"} call with an @{b}msg_iovlen@{ub} of 0 and a non-zero @{b}msg_controllen@{ub}, or by issuing a @{"getsockopt()" Link "getsockopt()"} request. Similarly, one can provide user connection rejection information by issuing a @{"send()" Link "send()"} call with providing only the control information, or by calling @{"setsockopt()" Link "getsockopt()"}. @{i}RETURN VALUES@{ui} The call returns -1 on error. If it succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. @{i}ERRORS@{ui} The @{b}accept()@{ub} will fail if: @{b}[EBADF]@{ub} The descriptor is invalid. @{b}[EINTR]@{ub} The operation was interrupted by a break signal. @{b}[EOPNOTSUPP]@{ub} The referenced socket is not of type @{b}SOCK_STREAM@{ub}. @{b}[EWOULDBLOCK]@{ub} The socket is marked non-blocking and no connections are present to be accepted. @{i}SEE ALSO@{ui} @{"bind()" Link "bind()"}, @{"connect()" Link "connect()"}, @{"listen()" Link "listen()"}, @{"select()" Link "select()"}, @{"SetSocketSignals()" Link "SetSocketSignals()"}, @{"socket()" Link "socket()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"} @{i}NOTES@{ui} @{b}accept()@{ub} calls the @{b}fdCallback()@{ub} with action codes @{b}FDCB_CHECK@{ub} and @{b}FDCB_ALLOC@{ub} to check and mark the new descriptor as allocated if the callback is defined. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more information on @{b}fdCallback()@{ub}. @{i}HISTORY@{ui} The @{b}accept()@{ub} function appeared in 4.2BSD. @EndNode @Node "bind()" "bsdsocket.guide/bind()" @Next "CloseSocket()" @Prev "accept()" @Toc "Function Reference" @{b}bind()@{ub} ====== @{i}NAME@{ui} @{b}bind@{ub} -- bind a name to a socket @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}#include @{ui} @{i}int bind(int s, struct sockaddr * name, int namelen)@{ui} @{i}D0 D0 A0 D1@{ui} @{i}DESCRIPTION@{ui} @{b}Bind()@{ub} assigns a name to an unnamed socket. When a socket is created with @{"socket()" Link "socket()"} it exists in a name space (address family) but has no name assigned. @{b}Bind()@{ub} requests that @{b}name@{ub} be assigned to the socket. @{i}RETURN VALUES@{ui} If the bind is successful, a 0 value is returned. A return value of -1 indicates an error, which is further specified in the library variable errno (see @{"Errno()" Link "Errno()"}.) @{i}ERRORS@{ui} The @{b}bind()@{ub} call will fail if: @{b}[EBADF]@{ub} @{b}S@{ub} is not a valid descriptor. @{b}[EADDRNOTAVAIL]@{ub} The specified address is not available from the local machine. @{b}[EADDRINUSE]@{ub} The specified address is already in use. @{b}[EINVAL]@{ub} The socket is already bound to an address. @{b}[EACCES]@{ub} The requested address is protected, and the current user has inadequate permission to access it. @{i}SEE ALSO@{ui} @{"connect()" Link "connect()"}, @{"listen()" Link "listen()"}, @{"socket()" Link "socket()"}, @{"getsockname()" Link "getsockname()"} @{i}HISTORY@{ui} The @{b}bind()@{ub} function call appeared in 4.2BSD. @EndNode @Node "CloseSocket()" "bsdsocket.guide/CloseSocket()" @Next "connect()" @Prev "bind()" @Toc "Function Reference" @{b}CloseSocket()@{ub} ============= @{i}NAME@{ui} @{b}CloseSocket@{ub} -- delete a socket descriptor @{i}SYNOPSIS@{ui} @{i}int CloseSocket(int s)@{ui} @{i}D0 D0@{ui} @{i}DESCRIPTION@{ui} The @{b}CloseSocket()@{ub} call deletes a descriptor from the library base socket reference table. If this is the last reference to the underlying object, the object will be deactivated and @{"socket()" Link "socket()"} associated naming information and queued data are discarded. All sockets are automatically closed when the socket library is closed, but closing sockets as soon as possible is recommended to save system resources. @{i}RETURN VALUES@{ui} Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the library variable @{b}errno@{ub} (see @{"Errno()" Link "Errno()"}) is set to indicate the error. @{i}ERRORS@{ui} @{b}CloseSocket()@{ub} will fail if: @{b}[EBADF]@{ub} @{b}S@{ub} is not an active socket descriptor. @{b}[EINTR]@{ub} An interupt was received. @{i}SEE ALSO@{ui} @{"accept()" Link "accept()"}, @{"shutdown()" Link "shutdown()"}, @{"socket()" Link "socket()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"}, @{b}exec.library/CloseLibrary()@{ub} @{i}NOTES@{ui} @{b}CloseSocket()@{ub} calls the @{b}fdCallback()@{ub} with action code @{b}FDCB_FREE@{ub} if the callback is defined. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more information on @{b}fdCallback()@{ub}. @EndNode @Node "connect()" "bsdsocket.guide/connect()" @Next "Dup2Socket()" @Prev "CloseSocket()" @Toc "Function Reference" @{b}connect()@{ub} ========= @{i}NAME@{ui} @{b}connect@{ub} -- initiate a connection on a socket @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}#include @{ui} @{i}int connect(int s, struct sockaddr * name, int namelen)@{ui} @{i}D0 D0 A0 D1@{ui} @{i}DESCRIPTION@{ui} The parameter @{b}s@{ub} is a socket. If it is of type @{b}SOCK_DGRAM@{ub}, this call specifies the peer with which the socket is to be associated; this address is that to which datagrams are to be sent, and the only address from which datagrams are to be received. If the socket is of type @{b}SOCK_STREAM@{ub}, this call attempts to make a connection to another socket. The other socket is specified by @{b}name@{ub}, which is an address in the communications space of the socket. Each communications space interprets the @{b}name@{ub} parameter in its own way. Generally, stream sockets may successfully @{b}connect()@{ub} only once; datagram sockets may use @{b}connect()@{ub} multiple times to change their association. Datagram sockets may dissolve the association by connecting to an invalid address, such as a null address. @{i}RETURN VALUES@{ui} If the connection or binding succeeds, 0 is returned. Otherwise a -1 is returned, and a more specific error code is stored in @{b}errno@{ub}. @{i}ERRORS@{ui} The @{b}connect()@{ub} call fails if: @{b}[EBADF]@{ub} @{b}S@{ub} is not a valid descriptor. @{b}[EADDRNOTAVAIL]@{ub} The specified address is not available on this machine. @{b}[EAFNOSUPPORT]@{ub} Addresses in the specified address family cannot be used with this socket. @{b}[EISCONN]@{ub} The socket is already connected. @{b}[ETIMEDOUT]@{ub} Connection establishment timed out without establishing a connection. @{b}[ECONNREFUSED]@{ub} The attempt to connect was forcefully rejected. @{b}[ENETUNREACH]@{ub} The network isn't reachable from this host. @{b}[EADDRINUSE]@{ub} The address is already in use. @{b}[EINPROGRESS]@{ub} The socket is non-blocking and the connection cannot be completed immediately. It is possible to @{"select()" Link "select()"} for completion by selecting the socket for writing. @{b}[EALREADY]@{ub} The socket is non-blocking and a previous connection attempt has not yet been completed. @{i}SEE ALSO@{ui} @{"accept()" Link "accept()"}, @{"select()" Link "select()"}, @{"socket()" Link "socket()"}, @{"getsockname()" Link "getsockname()"} @{i}HISTORY@{ui} The @{b}connect()@{ub} function call appeared in 4.2BSD. @EndNode @Node "Dup2Socket()" "bsdsocket.guide/Dup2Socket()" @Next "Errno()" @Prev "connect()" @Toc "Function Reference" @{b}Dup2Socket()@{ub} ============ @{i}NAME@{ui} @{b}Dup2Socket@{ub} -- duplicate a socket descriptor @{i}SYNOPSIS@{ui} @{i}int Dup2Socket(int fd1, int fd2)@{ui} @{i}D0 D0 D1@{ui} @{i}DESCRIPTION@{ui} @{b}Dup2Socket()@{ub} duplicates an existing socket descriptor. The argument @{b}fd1@{ub} is small non-negative value that indexes the socket on library base socket descriptor table. The value must be less than the size of the table, which is returned by @{b}getdtablesize()@{ub}. @{b}fd2@{ub} specifies the desired value of the new descriptor. If socket pointed by @{b}fd2@{ub} is already in use, it is first deallocated as if it were closed by @{b}CloseSocket()@{ub}. If the value of @{b}fd2@{ub} is -1, the new descriptor used and returned is the lowest numbered descriptor that is not currently in use by the task's socket library base. Since AMITCP/IP 3.0 @{b}Dup2Socket()@{ub} has also an feature to mark a file descriptor as being used. If @{b}fd1@{ub} is given as -1, @{b}fd2@{ub} is marked as being used socket descriptor table and it won't be allocated for any socket. This mark can be removed using @{b}CloseSocket()@{ub} call. @{i}RETURN VALUES@{ui} The value -1 is returned if an error occurs in either call. The library variable @{b}errno@{ub} (see @{"Errno()" Link "Errno()"}) indicates the cause of the error. @{i}ERRORS@{ui} @{b}Dup2Socket()@{ub} fail if: @{b}[EBADF]@{ub} @{b}sd1@{ub} or @{b}sd2@{ub} is not a valid active descriptor @{b}[EMFILE]@{ub} Too many descriptors are active. @{i}SEE ALSO@{ui} @{"accept()" Link "accept()"}, @{"CloseSocket()" Link "CloseSocket()"}, @{"socket()" Link "socket()"}, @{"getdtablesize()" Link "getdtablesize()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"} @{i}NOTES@{ui} @{b}Dup2Socket()@{ub} calls the @{b}fdCallback()@{ub} with action codes @{b}FDCB_CHECK@{ub} and @{b}FDCB_ALLOC@{ub} to check and mark the new descriptor as allocated if the callback is defined. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more information on @{b}fdCallback()@{ub}. @EndNode @Node "Errno()" "bsdsocket.guide/Errno()" @Next "getdtablesize()" @Prev "Dup2Socket()" @Toc "Function Reference" @{b}Errno()@{ub} ======= @{i}NAME@{ui} @{b}Errno@{ub} -- get error value after unsuccessful function call @{i}SYNOPSIS@{ui} @{i}long Errno(void)@{ui} @{i}D0@{ui} @{i}FUNCTION@{ui} When some function in socket library return an error condition value, they also set a specific error value. This error value can be (among other things) extracted by this function. @{i}RESULT@{ui} Error value indicating the error on last failure of some bsdsocket library function call. @{i}NOTES@{ui} Return value of @{b}Errno()@{ub} is not changed after successful function so so it cannot be used to determine success of any function call of this library. Also, another function call to this library may change the return value of @{b}Errno()@{ub} so use it right after error occurred. @{i}SEE ALSO@{ui} @{"SetErrnoPtr()" Link "SetErrnoPtr()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"} @EndNode @Node "getdtablesize()" "bsdsocket.guide/getdtablesize()" @Next "gethostbyname()" @Prev "Errno()" @Toc "Function Reference" @{b}getdtablesize()@{ub} =============== @{i}NAME@{ui} @{b}getdtablesize@{ub} -- get descriptor table size @{i}SYNOPSIS@{ui} @{i}int getdtablesize(void)@{ui} @{i}D0@{ui} @{i}DESCRIPTION@{ui} Each socket library base has a socket descriptor table which initially has 64 slots. The entries in the descriptor table are numbered with small integers starting at 0. The call @{b}getdtablesize()@{ub} returns the size of this table. @{i}SEE ALSO@{ui} @{"CloseSocket()" Link "CloseSocket()"}, @{"Dup2Socket()" Link "Dup2Socket()"}, @{"select()" Link "select()"} @{"SocketBaseTagList()" Link "SocketBaseTagList()"} @{i}NOTES@{ui} AMITCP/IP versions below 3.0 used to have function @{b}SetDtableSize()@{ub} in place of this function. From now on, use @{"SocketBaseTagList()" Link "SocketBaseTagList()"} to set new size for socket descriptor table. @{i}HISTORY@{ui} The @{b}getdtablesize()@{ub} function call appeared in 4.2BSD. @EndNode @Node "gethostbyname()" "bsdsocket.guide/gethostbyname()" @Next "gethostid()" @Prev "getdtablesize()" @Toc "Function Reference" @{b}gethostbyname()@{ub}, @{b}gethostbyaddr()@{ub} ================================ @{i}NAME@{ui} @{b}gethostbyname@{ub}, @{b}gethostbyaddr@{ub} -- get network host entry @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}extern struct h_errno;@{ui} @{i}struct hostent * gethostbyname(char * name)@{ui} @{i}D0 A0@{ui} @{i}struct hostent * gethostbyaddr(char * addr, int len, int type)@{ui} @{i}D0 A0 D0 D1@{ui} @{i}DESCRIPTION@{ui} The @{b}gethostbyname()@{ub} and @{b}gethostbyaddr()@{ub} functions each return a pointer to an object with the following structure describing an internet host referenced by name or by address, respectively. This structure contains either the information obtained from the name server, @{b}named@{ub} or broken-out fields from a line in @{b}/etc/hosts@{ub}. If the local name server is not running these routines do a lookup in @{b}/etc/hosts@{ub}. @{i}struct hostent { char *h_name; /*@{i} official name of host @{ui}*/ char **h_aliases; /*@{i} alias list @{ui}*/ int h_addrtype; /*@{i} host address type @{ui}*/ int h_length; /*@{i} length of address @{ui}*/ char **h_addr_list; /*@{i} list of addresses from name server @{ui}*/ }; #define h_addr h_addr_list[0] /*@{i} address, for backward compatibility @{ui}*/@{ui} The members of this structure are: @{b}h_name@{ub} Official name of the host. @{b}h_aliases@{ub} A zero terminated array of alternate names for the host. @{b}h_addrtype@{ub} The type of address being returned; currently always @{b}AF_INET@{ub}. @{b}h_length@{ub} The length, in bytes, of the address. @{b}h_addr_list@{ub} A zero terminated array of network addresses for the host. Host addresses are returned in network byte order. @{b}h_addr@{ub} The first address in @{b}h_addr_list@{ub}; this is for backward (source) compatiblity. @{i}DIAGNOSTICS@{ui} Error return status from @{b}gethostbyname()@{ub} and @{b}gethostbyaddr()@{ub} is indicated by return of a null pointer. The library integer @{b}h_errno@{ub} (see @{"SocketBaseTagList()" Link "SocketBaseTagList()"}) may then be checked to see whether this is a temporary failure or an invalid or unknown host. If its argument @{b}string@{ub} is non@{b}-NULL@{ub}, it is printed, followed by a colon and a space. The error message is printed with a trailing newline. The library variable @{b}h_errno@{ub} can have the following values: @{b}HOST_NOT_FOUND@{ub} No such host is known. @{b}TRY_AGAIN@{ub} This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. @{b}NO_RECOVERY@{ub} Some unexpected server failure was encountered. This is a non-recoverable error. @{b}NO_DATA@{ub} The requested name is valid but does not have an IP address; this is not a temporary error. This means that the name is known to the name server but there is no address associated with this name. Another type of request to the name server using this domain name will result in an answer; for example, a mail-forwarder may be registered for this domain. @{i}SEE ALSO@{ui} AMITCP/IP configuration @{i}HISTORY@{ui} The @{b}herror()@{ub} function appeared in 4.3BSD. @{b}gethostbyaddr()@{ub} and @{b}gethostbyname()@{ub} functions appeared in 4.2BSD. @{i}BUGS@{ui} These functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Only the Internet address format is currently understood. @EndNode @Node "gethostid()" "bsdsocket.guide/gethostid()" @Next "gethostname()" @Prev "gethostbyname()" @Toc "Function Reference" @{b}gethostid()@{ub} =========== @{i}NAME@{ui} @{b}gethostid@{ub} -- get unique identifier of current host @{i}SYNOPSIS@{ui} @{i}long gethostid(void)@{ui} @{i}D0@{ui} @{i}DESCRIPTION@{ui} @{b}gethostid()@{ub} returns the 32-bit identifier for the current processor that is intended to be unique among all UNIX systems in existence. This is normally a DARPA Internet address for the local machine. @{i}SEE ALSO@{ui} @{"gethostname()" Link "gethostname()"} @{i}BUGS@{ui} 32 bits for the identifier is too small. @{i}HISTORY@{ui} The @{b}gethostid()@{ub} function call appeared in 4.2BSD. @EndNode @Node "gethostname()" "bsdsocket.guide/gethostname()" @Next "getnetbyname()" @Prev "gethostid()" @Toc "Function Reference" @{b}gethostname()@{ub} ============= @{i}NAME@{ui} @{b}gethostname@{ub} -- get name of current host @{i}SYNOPSIS@{ui} @{i}int gethostname(char * name, int namelen)@{ui} @{i}D0 A0 D0@{ui} @{i}DESCRIPTION@{ui} @{b}Gethostname()@{ub} returns the standard host name for the current processor. The parameter @{b}namelen@{ub} specifies the size of the @{b}name@{ub} array. The returned name is null-terminated unless insufficient space is provided. @{i}SEE ALSO@{ui} @{"gethostid()" Link "gethostid()"} @{i}HISTORY@{ui} The @{b}gethostname()@{ub} function call appeared in 4.2BSD. @EndNode @Node "getnetbyname()" "bsdsocket.guide/getnetbyname()" @Next "getpeername()" @Prev "gethostname()" @Toc "Function Reference" @{b}getnetbyname()@{ub}, @{b}getnetbyaddr()@{ub} ============================== @{i}NAME@{ui} @{b}getnetbyaddr@{ub}, @{b}getnetbyname@{ub} -- get network entry @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}struct netent * getnetbyname(char * name)@{ui} @{i}D0 A0@{ui} @{i}struct netent * getnetbyaddr(long net, int type)@{ui} @{i}D0 D0 D1@{ui} @{i}DESCRIPTION@{ui} The @{b}getnetbyname()@{ub} and @{b}getnetbyaddr()@{ub} functions each return a pointer to an object with the following structure containing the broken-out fields of a line in the network data base. @{i}struct netent { char *n_name; /*@{i} official name of net @{ui}*/ char **n_aliases; /*@{i} alias list @{ui}*/ int n_addrtype; /*@{i} net number type @{ui}*/ unsigned long n_net; /*@{i} net number @{ui}*/ };@{ui} The members of this structure are: @{b}n_name@{ub} The official name of the network. @{b}n_aliases@{ub} A zero terminated list of alternate names for the network. @{b}n_addrtype@{ub} The type of the network number returned; currently only AF_INET. @{b}n_net@{ub} The network number. Network numbers are returned in machine byte order. @{i}DIAGNOSTICS@{ui} Null pointer (0) returned on @{b}EOF@{ub} or error. @{i}SEE ALSO@{ui} AMITCP/IP configuration @{i}HISTORY@{ui} The @{b}getnetbyaddr()@{ub} and @{b}getnetbyname()@{ub} functions appeared in 4.2BSD. @{i}BUGS@{ui} The data space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls to these functions overwrite it. Only Internet network numbers are currently understood. Expecting network numbers to fit in no more than 32 bits is probably naive. @EndNode @Node "getpeername()" "bsdsocket.guide/getpeername()" @Next "getprotobyname()" @Prev "getnetbyname()" @Toc "Function Reference" @{b}getpeername()@{ub} ============= @{i}NAME@{ui} @{b}getpeername@{ub} -- get name of connected peer @{i}SYNOPSIS@{ui} @{i}int getpeername(int s, struct sockaddr * name, int * namelen)@{ui} @{i}D0 D0 A0 A1@{ui} @{i}DESCRIPTION@{ui} @{b}Getpeername()@{ub} returns the name of the peer connected to socket @{b}s@{ub}. The @{b}namelen@{ub} parameter should be initialized to indicate the amount of space pointed to by @{b}name@{ub}. On return it contains the actual size of the name returned (in bytes). The name is truncated if the buffer provided is too small. @{i}DIAGNOSTICS@{ui} A 0 is returned if the call succeeds, -1 if it fails. @{i}ERRORS@{ui} The call succeeds unless: @{b}[EBADF]@{ub} The argument @{b}s@{ub} is not a valid descriptor. @{b}[ENOTCONN]@{ub} The socket is not connected. @{b}[ENOBUFS]@{ub} Insufficient resources were available in the system to perform the operation. @{i}SEE ALSO@{ui} @{"accept()" Link "accept()"}, @{"bind()" Link "bind()"}, @{"socket()" Link "socket()"}, @{"getsockname()" Link "getsockname()"} @{i}HISTORY@{ui} The @{b}getpeername()@{ub} function call appeared in 4.2BSD. @EndNode @Node "getprotobyname()" "bsdsocket.guide/getprotobyname()" @Next "getservbyname()" @Prev "getpeername()" @Toc "Function Reference" @{b}getprotobyname()@{ub}, @{b}getprotobynumber()@{ub} ==================================== @{i}NAME@{ui} @{b}getprotobynumber@{ub}, @{b}getprotobyname@{ub} -- get protocol entry @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}struct protoent * getprotobyname(char * name)@{ui} @{i}D0 A0@{ui} @{i}struct protoent * getprotobynumber(int proto)@{ui} @{i}D0 D0@{ui} @{i}DESCRIPTION@{ui} The @{b}getprotobyname()@{ub} and @{b}getprotobynumber()@{ub} functions each return a pointer to an object with the following structure containing the broken-out fields of a line in the network protocol data base. @{i} struct protoent { char *p_name; /*@{i} official name of protocol @{ui}*/ char **p_aliases; /*@{i} alias list @{ui}*/ int p_proto; /*@{i} protocol number @{ui}*/ };@{ui} The members of this structure are: @{b}p_name@{ub} The official name of the protocol. @{b}p_aliases@{ub} A zero terminated list of alternate names for the protocol. @{b}p_proto@{ub} The protocol number. @{i}RETURN VALUES@{ui} Null pointer (0) returned on @{b}EOF@{ub} or error. @{i}SEE ALSO@{ui} AMITCP/IP configuration @{i}HISTORY@{ui} The @{b}getprotobynumber()@{ub} and @{b}getprotobyname()@{ub} 4.2BSD. @{i}BUGS@{ui} These functions use a static data space; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Only the Internet protocols are currently understood. @EndNode @Node "getservbyname()" "bsdsocket.guide/getservbyname()" @Next "GetSocketEvents()" @Prev "getprotobyname()" @Toc "Function Reference" @{b}getservbyname()@{ub}, @{b}getservbyport()@{ub} ================================ @{i}NAME@{ui} @{b}getservbyport@{ub}, @{b}getservbyname@{ub} -- get service entry @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}struct servent * getservbyname(char * name, char * proto)@{ui} @{i}D0 A0 A1@{ui} @{i}struct servent * getservbyport(int port, char * proto)@{ui} @{i}D0 D0 A0@{ui} @{i}DESCRIPTION@{ui} The @{b}getservbyname()@{ub} and @{b}getservbyport()@{ub} functions each return a pointer to an object with the following structure containing the broken-out fields of a line in the network services data base. @{i}struct servent { char *s_name; /*@{i} official name of service @{ui}*/ char **s_aliases; /*@{i} alias list @{ui}*/ int s_port; /*@{i} port service resides at @{ui}*/ char *s_proto; /*@{i} protocol to use @{ui}*/ };@{ui} The members of this structure are: @{b}s_name@{ub} The official name of the service. @{b}s_aliases@{ub} A zero terminated list of alternate names for the service. @{b}s_port@{ub} The port number at which the service resides. Port numbers are returned in network byte order. @{b}s_proto@{ub} The name of the protocol to use when contacting the service. @{i}DIAGNOSTICS@{ui} Null pointer (0) returned on @{b}EOF@{ub} or error. @{i}SEE ALSO@{ui} @{"getprotobyname()" Link "getprotobyname()"} and AMITCP/IP configuration @{i}HISTORY@{ui} The @{b}getservbyport()@{ub}and @{b}getservbyname()@{ub} functions appeared in 4.2BSD. @{i}BUGS@{ui} These functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Expecting port numbers to fit in a 32 bit quantity is probably naive. @EndNode @Node "GetSocketEvents()" "bsdsocket.guide/GetSocketEvents()" @Next "getsockname()" @Prev "getservbyname()" @Toc "Function Reference" @{b}GetSocketEvents()@{ub} ================= @{i}NAME@{ui} @{b}GetSocketEvents@{ub} -- get asynchronic socket events if any @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}LONG GetSocketEvents(ULONG *eventsp)@{ui} @{i} A0@{ui} @{i}FUNCTION@{ui} @{b}GetSocketEvents()@{ub} is used to retrieve asynchronous events of sockets. The socket descriptor for which events happened is returned as a return value. If the return value is @{b}-1@{ub}, then there are no sockets with asynchronous events. Note that the @{b}errno@{ub} variable is @{i}not@{ui} set in this case. The asynchronous socket events are notified with the event signal. The application must set this signal with the @{"SocketBaseTagList()" Link "SocketBaseTagList()"} tag code @{b}SBTC_SIGEVENTMASK@{ub}. In addiotion to that, the application must set the event filter masks for each socket with the @{"getsockopt()" Link "getsockopt()"} @{b}SO_EVENTMASK@{ub} option. The socket must also be in async mode (@{"IoctlSocket()" Link "IoctlSocket()"} @{b}FIOASYNC@{ub}), but this mode will be set on by the @{"getsockopt()" Link "getsockopt()"} for @{b}SO_EVENTMASK@{ub} automaticly. The socket must also have an owner task which to notify. The owner task is set to the creating task of the socket by default. A socket got from @{"ObtainSocket()" Link "ObtainSocket()"} retains the old owner, however. So, after @{"ObtainSocket()" Link "ObtainSocket()"}, the owner must be set explicitly with the @{"IoctlSocket()" Link "IoctlSocket()"} code @{b}FIOSETOWN@{ub}. The events are returned via @{b}eventsp@{ub} as a bit mask of event codes defined in @{b}@{ub}. The event codes should be tested in the order they are defined in the header file and described below, since it is possible to get @{b}FD_CONNECT@{ub}, @{b}FD_READ@{ub} and @{b}FD_CLOSE@{ub} at the same time, for example. (That would mean that the connection was established, data was received and the connection was closed). @{b}FD_ACCEPT@{ub} Indicates that there is a new connection waiting for acception. This event is @{i}level triggered@{ui}, meaning that the event is set again if there is yet another connection after the @{"accept()" Link "accept()"} call. Because of this it is enough to respond with one @{"accept()" Link "accept()"} call for each @{b}FD_ACCEPT@{ub} received. @{b}FD_CONNECT@{ub} Indicates that the pending connection has been established. This event should be waited for after a non-blocking @{"connect()" Link "connect()"}. Note that this event is generated even if the socket is not in non-blocking mode. @{b}FD_OOB@{ub} Indicates that the socket has received a notifiction of urgent (out-of-band) data. The urgent data might not yet be received, and it might be impossible to receive, if the socket receive buffer is full. This means that the application should read the normal data from the buffer so that the urgent data could be received and read by the application. @{b}FD_READ@{ub} This event is set whenever new data arrives on the socket receive buffer. Note that the application should read all the data it can from the socket, since there is no quarantee that @{i}new@{ui} data would arrive, and thus cause a new event to be generated. @{b}FD_WRITE@{ub} This indicates that the application can write to the @{i}non-blocking@{ui} socket again. This event is set only if the socket is in non-blocking mode. This event is generated @{i}only@{ui} after the application could not write all the data to the socket (i.e., the operation would have blocked if the socket was not in non-blocking mode). @{b}FD_ERROR@{ub} This indicates an asynchronous error that happened on the socket. When this event is returned the @{b}errno@{ub} is set to the socket error code. Note that the socket error code is not cleared, so that the forthcoming socket functions might notice the error, too. If the socket error code must be cleared, the @{"getsockopt()" Link "getsockopt()"} for @{b}SO_ERROR@{ub} should be called, since the internal socket error is cleared as a side effect of that function (and code). @{b}FD_CLOSE@{ub} This indicates that the connection was closed. Note that the socket receive buffer might still have some data which should be received before the socket is closed. If the connection was closed due to an error, the @{b}FD_ERROR@{ub} event is sent before this event. The @{b}FD_ERROR@{ub} could be either returned by an earlier @{b}GetSocketEvents()@{ub} for this socket or included in the same event mask with the @{b}FD_CLOSE@{ub}. The exact semantics for the @{b}FD_CLOSE@{ub} depend on the application protocol. If the other end uses @{"shutdown()" Link "shutdown()"} to close only the sending side of the connection, the receiver of the @{b}FD_CLOSE@{ub} might still be able to send data. @{i}EXAMPLE@{ui} @{i}NOTES@{ui} @{i}SEE ALSO@{ui} @{"IoctlSocket()" Link "IoctlSocket()"}, @{"recv()" Link "recv()"}, @{"send()" Link "send()"}, @{"setsockopt()" Link "getsockopt()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"} !! @EndNode @Node "getsockname()" "bsdsocket.guide/getsockname()" @Next "getsockopt()" @Prev "GetSocketEvents()" @Toc "Function Reference" @{b}getsockname()@{ub} ============= @{i}NAME@{ui} @{b}getsockname@{ub} -- get socket name @{i}SYNOPSIS@{ui} @{i}int getsockname(int s, struct sockaddr * name, int * namelen)@{ui} @{i}D0 D0 A0 A1@{ui} @{i}DESCRIPTION@{ui} @{b}Getsockname()@{ub} returns the current @{b}name@{ub} for the specified socket. The @{b}namelen@{ub} parameter should be initialized to indicate the amount of space pointed to by @{b}name@{ub}. On return it contains the actual size of the name returned (in bytes). @{i}DIAGNOSTICS@{ui} A 0 is returned if the call succeeds, -1 if it fails. @{i}ERRORS@{ui} The call succeeds unless: @{b}[EBADF]@{ub} The argument @{b}s@{ub} is not a valid descriptor. @{b}[ENOBUFS]@{ub} Insufficient resources were available in the system to perform the operation. @{i}SEE ALSO@{ui} @{"bind()" Link "bind()"}, @{"socket()" Link "socket()"}, @{"getpeername()" Link "getpeername()"} @{i}HISTORY@{ui} The @{b}getsockname()@{ub} function call appeared in 4.2BSD. @EndNode @Node "getsockopt()" "bsdsocket.guide/getsockopt()" @Next "htonl()" @Prev "getsockname()" @Toc "Function Reference" @{b}getsockopt()@{ub}, @{b}setsockopt()@{ub} ========================== @{i}NAME@{ui} @{b}getsockopt@{ub}, @{b}setsockopt@{ub} -- get and set options on sockets @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}#include @{ui} @{i}int getsockopt(int s, int level, D0 D0 D1 int optname, void * optval, int * optlen) D2 A0 A1 int setsockopt(int s, int level, D0 D0 D1 int optname, const void * optval, int optlen) D2 A0 D3@{ui} @{i}DESCRIPTION@{ui} @{b}getsockopt()@{ub} and @{b}setsockopt()@{ub} manipulate the @{i}options@{ui} 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, @{b}level@{ub} is specified as @{b}SOL_SOCKET@{ub}. 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, @{b}level@{ub} should be set to the protocol number of TCP; see @{"getprotobyname()" Link "getprotobyname()"}. The parameters @{b}optval@{ub} and @{b}optlen@{ub} are used to access option values for @{b}setsockopt()@{ub} For @{b}getsockopt()@{ub} they identify a buffer in which the value for the requested option(s) are to be returned. For @{b}getsockopt()@{ub} @{b}optlen@{ub} is a value-result parameter, initially containing the size of the buffer pointed to by @{b}optval@{ub}, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, @{b}optval@{ub} may be @{b}NULL@{ub}. @{b}optname@{ub} and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file @{b}@{ub} contains definitions for socket level options, described below. Options at other protocol levels vary in format and name. Most socket-level options utilize an @{b}int@{ub} parameter for @{b}optval@{ub}. For @{b}setsockopt()@{ub} the parameter should be non-zero to enable a boolean option, or zero if the option is to be disabled. @{b}SO_LINGER@{ub} uses a @{b}struct@{ub} linger parameter, defined in @{b}@{ub}, which specifies the desired state of the option and the linger interval (see below). @{b}SO_SNDTIMEO@{ub} and @{b}SO_RCVTIMEO@{ub} use a @{b}struct@{ub} timeval parameter, defined in @{b}@{ub}. The following options are recognized at the socket level. Except as noted, each may be examined with @{b}getsockopt()@{ub} and set with @{b}setsockopt()@{ub} @{b}SO_DEBUG@{ub} enables recording of debugging information @{b}SO_REUSEADDR@{ub} enables local address reuse @{b}SO_KEEPALIVE@{ub} enables keep connections alive @{b}SO_DONTROUTE@{ub} enables routing bypass for outgoing messages @{b}SO_LINGER@{ub} linger on close if data present @{b}SO_BROADCAST@{ub} enables permission to transmit broadcast messages @{b}SO_OOBINLINE@{ub} enables reception of out-of-band data in band @{b}SO_SNDBUF@{ub} set buffer size for output @{b}SO_RCVBUF@{ub} set buffer size for input @{b}SO_SNDLOWAT@{ub} set minimum count for output @{b}SO_RCVLOWAT@{ub} set minimum count for input @{b}SO_SNDTIMEO@{ub} set timeout value for output @{b}SO_RCVTIMEO@{ub} set timeout value for input @{b}SO_TYPE@{ub} get the type of the socket (get only) @{b}SO_ERROR@{ub} get and clear error on the socket (get only) @{b}SO_EVENTMASK@{ub} set event mask to specify which events should be notified to the application @{b}SO_DEBUG@{ub} enables debugging in the underlying protocol modules. @{b}SO_REUSEADDR@{ub} indicates that the rules used in validating addresses supplied in a @{"bind()" Link "bind()"} call should allow reuse of local addresses. @{b}SO_KEEPALIVE@{ub} 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 @{b}SIGPIPE@{ub} signal when attempting to send data. @{b}SO_DONTROUTE@{ub} 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. @{b}SO_LINGER@{ub} controls the action taken when unsent messags are queued on socket and a @{"CloseSocket()" Link "CloseSocket()"} is performed. If the socket promises reliable delivery of data and @{b}SO_LINGER@{ub} isset, the system will block the process on the @{"CloseSocket()" Link "CloseSocket()"} 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 @{b}setsockopt()@{ub} call when @{b}SO_LINGER@{ub} is requested). If @{b}SO_LINGER@{ub} is disabled and a @{"CloseSocket()" Link "CloseSocket()"} is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The option @{b}SO_BROADCAST@{ub} 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 @{b}SO_OOBINLINE@{ub} option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with @{"recv()" Link "recv()"} calls without the @{b}MSG_OOB@{ub} flag. Some protocols always behave as if this option is set. @{b}SO_SNDBUF@{ub} and @{b}SO_RCVBUF@{ub} 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. @{b}SO_SNDLOWAT@{ub} 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()" Link "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 @{b}SO_SNDLOWAT@{ub} is set to a convenient size for network efficiency, often 1024. @{b}SO_RCVLOWAT@{ub} 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 @{b}SO_SNDLOWAT@{ub} is 1. If @{b}SO_SNDLOWAT@{ub} 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. @{b}SO_SNDTIMEO@{ub} is an option to set a timeout value for output operations. It accepts a @{b}struct@{ub} 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 @{b}EWOULDBLOCK@{ub} 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. @{b}SO_RCVTIMEO@{ub} is an option to set a timeout value for input operations. It accepts a @{b}struct@{ub}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 @{b}EWOULDBLOCK@{ub} if no data were received. Finally, @{b}SO_TYPE@{ub} and @{b}SO_ERROR@{ub} are options used only with @{b}setsockopt()@{ub} @{b}SO_TYPE@{ub} returns the type of the socket, such as @{b}SOCK_STREAM@{ub}; it is useful for servers that inherit sockets on startup. @{b}SO_ERROR@{ub} 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. Additionally, @{b}SO_EVENTMASK@{ub} is used to specify which @{i}asynchronous events@{ui} are to be notified to the socket owner. See @{"GetSocketEvents()" Link "GetSocketEvents()"} for more info on this. @{b}SO_EVENTMASK@{ub} is AMITCP/IP addition. @{i}RETURN VALUES@{ui} A 0 is returned if the call succeeds, -1 if it fails. @{i}ERRORS@{ui} The call succeeds unless: @{b}[EBADF]@{ub} The argument @{b}s@{ub} is not a valid descriptor. @{b}[ENOPROTOOPT]@{ub} The option is unknown at the level indicated. @{i}SEE ALSO@{ui} @{"IoctlSocket()" Link "IoctlSocket()"}, @{"socket()" Link "socket()"}, @{"getprotobyname()" Link "getprotobyname()"}, @{"GetSocketEvents()" Link "GetSocketEvents()"} @{i}BUGS@{ui} Several of the socket options should be handled at lower levels of the system. @{i}HISTORY@{ui} The @{b}getsockopt()@{ub} system call appeared in 4.2BSD. @EndNode @Node "htonl()" "bsdsocket.guide/htonl()" @Next "inet_addr()" @Prev "getsockopt()" @Toc "Function Reference" @{b}htonl()@{ub}, @{b}htons()@{ub}, @{b}ntohl()@{ub}, @{b}ntohs()@{ub} ================================== @{i}NAME@{ui} @{b}htonl@{ub}, @{b}htons@{ub}, @{b}ntohl@{ub}, @{b}ntohs@{ub} -- convert values between host and network byte order @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}u_long htonl(u_long hostlong)@{ui} @{i}u_short htons(u_short hostshort)@{ui} @{i}u_long ntohl(u_long netlong)@{ui} @{i}u_short ntohs(u_short netshort)@{ui} @{i}DESCRIPTION@{ui} These routines convert 16 and 32 bit quantities between network byte order and host byte order. On machines which have a byte order which is the same as the network order, routines are defined as null macros. Commodore Amiga is such a machine. These routines are most often used in conjunction with Internet addresses and ports as returned by @{"gethostbyname()" Link "gethostbyname()"} and @{"getservbyname()" Link "getservbyname()"}. @{i}SEE ALSO@{ui} @{"gethostbyname()" Link "gethostbyname()"}, @{"getservbyname()" Link "getservbyname()"} @{i}HISTORY@{ui} The @{b}byteorder@{ub} -- functions appeared in 4.2BSD. @{i}BUGS@{ui} On the VAX bytes are handled backwards from most everyone else in the world. This is not expected to be fixed in the near future. @EndNode @Node "inet_addr()" "bsdsocket.guide/inet_addr()" @Next "IoctlSocket()" @Prev "htonl()" @Toc "Function Reference" @{b}inet_addr()@{ub}, @{b}inet_network()@{ub}, @{b}inet_ntoa()@{ub}, @{b}inet_makeaddr()@{ub}, @{b}inet_lnaof()@{ub}, @{b}inet_netof()@{ub} ===================================================================================== @{i}NAME@{ui} @{b}inet_addr@{ub}, @{b}inet_network@{ub}, @{b}Inet_NtoA@{ub}, @{b}Inet_MakeAddr@{ub}, @{b}Inet_LnaOf@{ub}, @{b}Inet_NetOf@{ub} -- Internet address manipulation routines @{b}inet_ntoa@{ub}, @{b}inet_makeaddr@{ub}, @{b}inet_lnaof@{ub}, @{b}inet_netof@{ub} -- inline/stub functios of above to handle structure args @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}#include @{ui} @{i}#include @{ui} @{i}unsigned long inet_addr(const char * cp)@{ui} @{i}D0 A0@{ui} @{i}unsigned long inet_network(const char * cp)@{ui} @{i}D0 A0@{ui} @{i}char * Inet_NtoA(unsigned long in)@{ui} @{i}D0 D0@{ui} @{i}unsigned long Inet_MakeAddr(int net, int lna)@{ui} @{i}D0 D0 D1@{ui} @{i}unsigned long Inet_LnaOf(unsigned long in)@{ui} @{i}D0 D0@{ui} @{i}unsigned long Inet_NetOf(unsigned long in)@{ui} @{i}D0 D0@{ui} @{i}char * inet_ntoa(struct in_addr in)@{ui} @{i}struct in_addr inet_makeaddr(int net, int lna)@{ui} @{i}unsigned long inet_lnaof(struct in_addr in)@{ui} @{i}unsigned long inet_netof(struct in_addr in)@{ui} @{i}IMPLEMENTATION NOTE@{ui} Return value of @{b}Inet_MakeAddr()@{ub} and argument types of @{b}Inet_LnaOf()@{ub}, @{b}Inet_NetOf()@{ub} and @{b}Inet_NtoA()@{ub} are longs instead of struct in_addr. The original behaviour is achieved by using included stub functions (lower case function names) which handle structure arguments. @{i}DESCRIPTION@{ui} The routines @{b}inet_addr()@{ub} and @{b}inet_network()@{ub} interpret character strings representing numbers expressed in the Internet standard `.' notation, returning numbers suitable for use as Internet addresses and Internet network numbers, respectively. The routine @{b}inet_ntoa()@{ub} takes an Internet address and returns an ASCII string representing the address in base 256 notation "d.d.d.d" described below .The routine @{b}inet_makeaddr()@{ub} takes an Internet network number and a local network address and constructs an Internet address from it. The routines @{b}inet_netof()@{ub} and @{b}inet_lnaof()@{ub} break apart Internet host addresses, returning the network number and local network address part, respectively. All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. @{i}INTERNET ADDRESSES@{ui} Values specified using the `.' notation take one of the following forms: @{i}a.b.c.d a.b.c a.b a@{ui} When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. Note that when an Internet address is viewed as a 32-bit integer quantity on the VAX the bytes referred to above appear as "d.c.b.a ." That is, VAX bytes are ordered from right to left. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as "128.net.host ." When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as "net.host ." When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as "parts" in a `.' notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). @{i}DIAGNOSTICS@{ui} The constant @{b}INADDR_NONE@{ub} is returned by @{b}inet_addr()@{ub} and @{b}inet_network()@{ub} for malformed requests. @{i}SEE ALSO@{ui} @{"gethostbyname()" Link "gethostbyname()"} @{i}HISTORY@{ui} These functions appeared in 4.2BSD. @{i}BUGS@{ui} The value @{b}INADDR_NONE@{ub} (0xffffffff) is a valid broadcast address, but @{b}inet_addr()@{ub} cannot return that value without indicating failure. The problem of host byte ordering versus network byte ordering is confusing. A simple way to specify Class C network addresses in a manner similar to that for Class B and Class A is needed. The string returned by @{b}inet_ntoa()@{ub} resides in a static memory area. Inet_addr should return a @{b}struct@{ub} in_addr. @EndNode @Node "IoctlSocket()" "bsdsocket.guide/IoctlSocket()" @Next "listen()" @Prev "inet_addr()" @Toc "Function Reference" @{b}IoctlSocket()@{ub} ============= @{i}NAME@{ui} @{b}IoctlSocket@{ub} -- control sockets @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}int IoctlSocket(int s, unsigned long request, char * argp)@{ui} @{i}D0 D0 D1 A0@{ui} @{i}DESCRIPTION@{ui} @{b}IoctlSocket()@{ub} performs a special function on the object referred to by the open socket descriptor s. Note: the @{"getsockopt()" Link "getsockopt()"} call is the primary method for operating on sockets as such, rather than on the underlying protocol or network interface. For most @{b}IoctlSocket()@{ub} functions, argp is a pointer to data to be used by the function or to be filled in by the function. Other functions may ignore arg or may treat it directly as a data item; they may, for example, be passed an int value. An ioctl @{b}request@{ub} has encoded in it whether the argument is an "in" parameter or "out" parameter, and the size of the argument @{b}argp@{ub} in bytes. Macros and defines used in specifying an ioctl @{b}request@{ub} are located in the file @{b}@{ub}. The following requests are supported: @{b}FIOASYNC@{ub} The argument is a pointer to a long. Set or clear asynchronous I/O. If the value of that long is a 1 (one) the descriptor is set for asynchronous I/O. If the value of that long is a 0 (zero) the descriptor is cleared for asynchro- nous I/O. @{b}FIOCLEX@{ub} @{b}FIONCLEX@{ub} Ignored, no use for close-on-exec flag in Amiga. @{b}FIOGETOWN@{ub} @{b}SIOCGPGRP@{ub} The argument is pointer to struct Task*. Set the value of that pointer to the Task that is receiving SIGIO or SIGURG signals for the socket referred to by the descriptor passed to IoctlSocket(). @{b}FIONBIO@{ub} The argument is a pointer to a long. Set or clear non-blocking I/O. If the value of that long is a 1 (one) the descriptor is set for non-blocking I/O. If the value of that long is a 0 (zero) the descriptor is cleared for non- blocking I/O. @{b}FIONREAD@{ub} The argument is a pointer to a long. Set the value of that long to the number of immediately readable characters from the socket fd. @{b}FIOSETOWN@{ub} @{b}SIOCSPGRP@{ub} The argument is pointer to struct Task*, pointer to the task that will subseq- uently receive SIGIO or SIGURG signals for the socket referred to by the descriptor passed. @{b}SIOCCATMARK@{ub} The argument is a pointer to a long. Set the value of that long to 1 if the read pointer for the socket referred to by the descriptor passed to IoctlSocket() points to a mark in the data stream for an out-of-band message, and to 0 if it does not point to a mark. @{i}RETURN VALUES@{ui} @{b}IoctlSocket()@{ub} returns 0 on success for most requests. Some specialized requests may return non-zero values on success; On failure, @{b}IoctlSocket()@{ub} returns -1 and sets @{b}errno@{ub} to indicate the error. @{i}ERRORS@{ui} @{b}Ioctl()@{ub} will fail: @{b}[EBADF]@{ub} @{b}s@{ub} is not a valid descriptor. @{b}[EINVAL]@{ub} @{b}Request@{ub} or @{b}argp@{ub} is not valid. @{b}IoctlSocket()@{ub} will also fail if the object on which the function is being performed detects an error. In this case, an error code specific to the object and the function will be returned. @{i}SEE ALSO@{ui} @{"setsockopt()" Link "getsockopt()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"} @{i}HISTORY@{ui} An @{b}ioctl()@{ub} function call appeared in Version 7 AT&T UNIX. @EndNode @Node "listen()" "bsdsocket.guide/listen()" @Next "ObtainSocket()" @Prev "IoctlSocket()" @Toc "Function Reference" @{b}listen()@{ub} ======== @{i}NAME@{ui} @{b}listen@{ub} -- listen for connections on a socket @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}int listen(int s, int backlog)@{ui} @{i}D0 D0 D1@{ui} @{i}DESCRIPTION@{ui} To accept connections, a socket is first created with @{"socket()" Link "socket()"}, a willingness to accept incoming connections and a queue limit for incoming connections are specified with @{b}listen()@{ub} and then the connections are accepted with @{"accept()" Link "accept()"}. The @{b}listen()@{ub} call applies only to sockets of type @{b}SOCK_STREAM@{ub} or @{b}SOCK_SEQPACKET@{ub}. The @{b}backlog@{ub} parameter defines the maximum length the queue of pending connections may grow to. If a connection request arrives with the queue full the client may receive an error with an indication of @{b}ECONNREFUSED@{ub}, or, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed. @{i}RETURN VALUES@{ui} A 0 return value indicates success; -1 indicates an error. @{i}ERRORS@{ui} @{b}Listen()@{ub} will fail if: @{b}[EBADF]@{ub} The argument @{b}s@{ub} is not a valid descriptor. @{b}[EOPNOTSUPP]@{ub} The socket is not of a type that supports the operation @{b}listen()@{ub} @{i}SEE ALSO@{ui} @{"accept()" Link "accept()"}, @{"connect()" Link "connect()"}, @{"socket()" Link "socket()"} @{i}BUGS@{ui} The @{b}backlog@{ub} is currently limited (silently) to 5. @{i}HISTORY@{ui} The @{b}listen()@{ub} function call appeared in 4.2BSD. @EndNode @Node "ObtainSocket()" "bsdsocket.guide/ObtainSocket()" @Next "recv()" @Prev "listen()" @Toc "Function Reference" @{b}ObtainSocket()@{ub} ============== @{i}NAME@{ui} @{b}ObtainSocket@{ub} -- get a previously released socket @{i}SYNOPSIS@{ui} @{i}LONG ObtainSocket(LONG id, LONG domain, LONG type, LONG protocol)@{ui} @{i}D0 D0 D1 D2 D3@{ui} @{i}FUNCTION@{ui} When one task wants to give a socket to an another one, it releases it (with a key value) to a special socket list held by AmiTCP/IP. This function requests that socket and receives it if id and other parameters match. After release 3.0 of AMITCP/IP @{b}ObtainSocket()@{ub} can be called with an unique id and @{b}domain@{ub} as ZERO to request any kind of socket that is available with that @{b}id@{ub}. @{i}INPUTS@{ui} @{b}id@{ub} a key value for finding the correct available socket. @{b}domain@{ub} see documentation of @{"socket()" Link "socket()"}. @{b}type@{ub} see documentation of @{"socket()" Link "socket()"}. @{b}protocol@{ub} see documentation of @{"socket()" Link "socket()"}. @{i}RESULT@{ui} Non negative socket descriptor on success. On failure, -1 is returned and the errno is set to indicate the error. @{i}ERRORS@{ui} @{b}EMFILE@{ub} The per-process descriptor table is full. @{b}EPROTONOSUPPORT@{ub} The protocol type or the specified protocol is not supported within this domain. @{b}EPROTOTYPE@{ub} The protocol is the wrong type for the socket. @{b}EWOULDBLOCK@{ub} Matching socket is not found. @{i}SEE ALSO@{ui} @{"ReleaseSocket()" Link "ReleaseSocket()"}, @{"socket()" Link "socket()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"} @{i}NOTES@{ui} @{b}ObtainSocket()@{ub} calls the @{b}fdCallback()@{ub} with action codes @{b}FDCB_CHECK@{ub} and @{b}FDCB_ALLOC@{ub} to check and mark the new descriptor as allocated if the callback is defined. It may also call the callback again with @{b}FDCB_FREE@{ub}, if an error condition occurs. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more information on @{b}fdCallback()@{ub}. @EndNode @Node "recv()" "bsdsocket.guide/recv()" @Next "ReleaseSocket()" @Prev "ObtainSocket()" @Toc "Function Reference" @{b}recv()@{ub}, @{b}recvfrom()@{ub}, @{b}recvmsg()@{ub} ============================= @{i}NAME@{ui} @{b}recv@{ub}, @{b}recvfrom@{ub}, @{b}recvmsg@{ub} -- receive a message from a socket @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}#include @{ui} @{i}int recv(int s, void * buf, int len, int flags)@{ui} @{i}D0 D0 A0 D1 D2@{ui} @{i}int recvfrom(int s, void * buf, int len, int flags,@{ui} @{i}D0 D0 A0 D1 D2 @{ui} @{i} struct sockaddr * from, int * fromlen)@{ui} @{i} A1 A2@{ui} @{i}int recvmsg(int s, struct msghdr * msg, int flags)@{ui} @{i}D0 D0 A0 D1@{ui} @{i}DESCRIPTION@{ui} @{b}Recv()@{ub}, @{b}recvfrom()@{ub} and @{b}recvmsg()@{ub} are used to receive messages from a socket. @{b}Recv()@{ub} may be used only on a connected socket (see @{"connect()" Link "connect()"}), while @{b}recvfrom()@{ub} and @{b}recvmsg()@{ub} and may be used to receive data on a socket whether or not it is connection-oriented. If @{b}from@{ub} is non-nil, and the socket is not connection-oriented, the source address of the message is filled in. @{b}Fromlen@{ub} is a value-result parameter, initialized to the size of the buffer associated with @{b}from@{ub}, and modified on return to indicate the actual size of the address stored there. All three routines return the length of the message on successful completion. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see @{"socket()" Link "socket()"}). If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is nonblocking (see @{"IoctlSocket()" Link "IoctlSocket()"}) in which case the value -1 is returned and the library variable @{b}errno@{ub} (see @{"Errno()" Link "Errno()"}) set to @{b}EWOULDBLOCK@{ub}. The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested; this behavior is affected by the socket-level options @{b}SO_RCVLOWAT@{ub} and @{b}SO_RCVTIMEO@{ub} described in @{"getsockopt()" Link "getsockopt()"}. The @{"select()" Link "select()"} call may be used to determine when more data arrive. The @{b}flags@{ub} argument to a recv call is formed by @{i}or@{ui}'ing one or more of the values: @{b}MSG_OOB@{ub} process out-of-band data @{b}MSG_PEEK@{ub} peek at incoming message @{b}MSG_WAITALL@{ub} wait for full request or error The @{b}MSG_OOB@{ub} flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols. The @{b}MSG_PEEK@{ub} flag causes the receive operation to return 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. The @{b}MSG_WAITALL@{ub} flag 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. The @{b}recvmsg()@{ub} call uses a @{b}msghdr@{ub} structure to minimize the number of directly supplied parameters. This structure has the following form, as defined in @{b}@{ub}: @{i}struct msghdr { caddr_t msg_name; /*@{i} optional address @{ui}*/ u_int msg_namelen; /*@{i} size of address @{ui}*/ struct iovec *msg_iov; /*@{i} scatter/gather array @{ui}*/ u_int msg_iovlen; /*@{i} # elements in msg_iov @{ui}*/ caddr_t msg_control; /*@{i} ancillary data, see below @{ui}*/ u_int msg_controllen; /*@{i} ancillary data buffer len @{ui}*/ int msg_flags; /*@{i} flags on received message @{ui}*/ };@{ui} Here @{b}msg_name@{ub} and @{b}msg_namelen@{ub} specify the destination address if the socket is unconnected; @{b}msg_name@{ub} may be given as a null pointer if no names are desired or required. @{b}Msg_iov@{ub} and @{b}msg_iovlen@{ub} describe scatter gather locations, the input data is scattered into @{b}msg_iovlen@{ub} buffers spesified by the members of the @{b}msg_iov@{ub} array: @{b}msg_iov[0]@{ub}, @{b}msg_iov[0]@{ub}, ..., @{b}msg_iov[@{b}msg_iovlen@{ub} - 1]@{ub}. The @{b}iovec@{ub} structure is defined as @{i}struct iovec { caddr_t iov_base; int iov_len; }; @{ui} Each @{b}iovec@{ub} entry specifies the base address and length of an area in memory where data should be placed. @{b}Recvmsg()@{ub} will always fill an area completely before proceeding to the next. The fields @{b}msg_control@{ub} and @{b}msg_controllen@{ub} are not currently used in this implementation, set them as 0 before use. The @{b}msg_flags@{ub} field is set on return according to the message received. @{b}MSG_EOR@{ub} indicates end-of-record; the data returned completed a record (generally used with sockets of type @{b}SOCK_SEQPACKET@{ub}). @{b}MSG_TRUNC@{ub} indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied. @{b}MSG_CTRUNC@{ub} indicates that some control data were discarded due to lack of space in the buffer for ancillary data. @{b}MSG_OOB@{ub} is returned to indicate that expedited or out-of-band data were received. @{i}RETURN VALUES@{ui} These calls return the number of bytes received, or -1 if an error occurred. @{i}ERRORS@{ui} The calls fail if: @{b}[EBADF]@{ub} The argument @{b}s@{ub} is an invalid descriptor. @{b}[ENOTCONN]@{ub} The socket is assoicated with a connection-oriented protocol and has not been connected (see @{"connect()" Link "connect()"} and @{"accept()" Link "accept()"}). @{b}[EWOULDBLOCK]@{ub} The socket is marked non-blocking, and the receive operation would block, or a receive timeout had been set, and the timeout expired before data were received. @{b}[EINTR]@{ub} The receive was interrupted by delivery of a signal before any data were available. @{i}SEE ALSO@{ui} @{"getsockopt()" Link "getsockopt()"}, @{"IoctlSocket()" Link "IoctlSocket()"}, @{"select()" Link "select()"}, @{"send()" Link "send()"}, @{"socket()" Link "socket()"} @{i}HISTORY@{ui} The @{b}recv()@{ub} function call appeared in 4.2BSD. @EndNode @Node "ReleaseSocket()" "bsdsocket.guide/ReleaseSocket()" @Next "select()" @Prev "recv()" @Toc "Function Reference" @{b}ReleaseSocket()@{ub}, @{b}ReleaseCopyOfSocket()@{ub} ====================================== @{i}NAME@{ui} @{b}ReleaseSocket@{ub}, @{b}ReleaseCopyOfSocket@{ub} -- make a socket be available with ObtainSocket() call. @{i}SYNOPSIS@{ui} @{i}LONG ReleaseSocket(LONG sd, LONG id)@{ui} @{i}D0 D0 D1@{ui} @{i}LONG ReleaseCopyOfSocket(LONG sd, LONG id)@{ui} @{i}D0 D0 D1@{ui} @{i}FUNCTION@{ui} The @{b}ReleaseSocket()@{ub} removes the socket pointed by descriptor @{b}sd@{ub} from it's descriptor table and puts it available via next @{"ObtainSocket()" Link "ObtainSocket()"} call. The @{b}ReleaseCopyOfSocket()@{ub} makes a new reference to given socket and that is made available to another caller. @{i}INPUTS@{ui} @{b}sd@{ub} descriptor of the socket to be released. @{b}id@{ub} the key value to identify use of this socket. It can be unique or not, depending on its value. If @{b}id@{ub} value is between 0 and 65535, inclusively, it is considered nonunique and it can be used as a port number, for example. If @{b}id@{ub} is greater than 65535 and less than 2^31) it must be unique in currently held sockets in AMITCP/IP socket list, Otherwise an error will be returned and socket is not released. If @{b}id@{ub} == UNIQUE_ID (defined in @{b}@{ub}) an unique id will be generated. @{i}RESULT@{ui} -1 in case of error, otherwise the key value of the socket put in the list. Most useful when an unique id is generated by this routine. @{i}ERRORS@{ui} @{b}EINVAL@{ub} Requested unique id is already used. @{b}ENOMEM@{ub} The memory needed could not be allocated. @{i}NOTE@{ui} In case of @{b}ReleaseCopyOfSocket()@{ub}. The socket descriptor is not deallocated from the descriptor table of the calling task. @{i}SEE ALSO@{ui} @{"ObtainSocket()" Link "ObtainSocket()"}. @{"SocketBaseTagList()" Link "SocketBaseTagList()"} @{i}NOTES@{ui} @{b}ReleaseSocket()@{ub} (but not @{b}ReleaseCopyOfSocket()@{ub}) calls the @{b}fdCallback()@{ub} with action code @{b}FDCB_FREE@{ub} if the callback is defined. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more information on @{b}fdCallback()@{ub}. @EndNode @Node "select()" "bsdsocket.guide/select()" @Next "send()" @Prev "ReleaseSocket()" @Toc "Function Reference" @{b}select()@{ub}, @{b}WaitSelect()@{ub} ====================== @{i}NAME@{ui} @{b}select@{ub} -- synchronous I/O multiplexing (stub/inline function) @{b}WaitSelect@{ub} -- select() with Exec @{b}Wait()@{ub} function. @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}#include @{ui} @{i} int select(int nfds, fd_set * readfds, fd_set * writefds, fd_set * exceptfds, struct timeval * timeout) int WaitSelect(int nfds, fd_set * readfds, fd_set * writefds, D0 D0 A0 A1 fd_set * exceptfds, struct timeval * timeout, A2 A3 ULONG * sigmask) D1 FD_SET(fd, &fdset) FD_CLR(fd, &fdset) FD_ISSET(fd, &fdset) FD_ZERO(&fdset)@{ui} @{i}DESCRIPTION@{ui} @{b}Select()@{ub} examines the I/O descriptor sets whose addresses are passed in @{b}readfds@{ub}, @{b}writefds@{ub}, and @{b}exceptfds@{ub} to see if some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively. The first @{b}nfds@{ub} descriptors are checked in each set; i.e., the descriptors from 0 through @{b}nfds@{ub}-1 in the descriptor sets are examined. On return, @{b}select()@{ub} replaces the given descriptor sets with subsets consisting of those descriptors that are ready for the requested operation. @{b}Select()@{ub} returns the total number of ready descriptors in all the sets. @{b}WaitSelect()@{ub} also takes a signal mask which is waited during normal @{b}select()@{ub} operation. If one of these singals is received, @{b}WaitSelect()@{ub} returns and has re-set the signal mask to return those signals that have arrived and value 0 is returned (total number of ready descriptors in all the sets, which is currently zero for efficiency reasons). The descriptor sets are stored as bit fields in arrays of integers. The following macros are provided for manipulating such descriptor sets: @{b}FD_ZERO(&fdset)@{ub} initializes a descriptor set @{b}fdset@{ub} to the null set. @{b}FD_SET(fd, &fdset)@{ub} includes a particular descriptor @{b}fd@{ub} in @{b}fdset@{ub}. @{b}FD_CLR(fd, &fdset)@{ub} removes @{b}fd@{ub} from @{b}fdset@{ub}. @{b}FD_ISSET(fd, &fdset)@{ub} is non-zero if @{b}fd@{ub} is a member of @{b}fdset@{ub}, zero otherwise. The behavior of these macros is undefined if a descriptor value is less than zero or greater than or equal to @{b}FD_SETSIZE@{ub}, which is normally at least equal to the maximum number of descriptors supported by the system. If @{b}timeout@{ub} is a non-nil pointer, it specifies a maximum interval to wait for the selection to complete. If @{b}timeout@{ub} is a nil pointer, the select blocks indefinitely. To affect a poll, the @{b}timeout@{ub} argument should be non-nil, pointing to a zero-valued timeval structure. Any of @{b}readfds@{ub}, @{b}writefds@{ub}, and @{b}exceptfds@{ub} may be given as NULL pointers if no descriptors are of interest. Selecting true for reading on a socket descriptor upon which a @{b}listen()@{ub} call has been performed indicates that a subsequent @{b}accept()@{ub} call on that descriptor will not block. @{i}RETURN VALUES@{ui} @{b}Select()@{ub} returns the number of ready descriptors that are contained in the descriptor sets, or -1 if an error occurred. If the time limit expires (or signal in mask arrives), the functions returns 0. If error is returned, including one due to an interrupted call, the descriptor sets will be unmodified. @{i}ERRORS@{ui} An error return from @{b}select()@{ub} indicates: @{b}[EBADF]@{ub} One of the descriptor sets specified an invalid descriptor. @{b}[EINTR]@{ub} A signal was delivered before the time limit expired and before any of the selected events occurred. @{b}[EINVAL]@{ub} The specified time limit is invalid. One of its components is negative or too large. @{i}SEE ALSO@{ui} @{"accept()" Link "accept()"}, @{"connect()" Link "connect()"}, @{"recv()" Link "recv()"}, @{"send()" Link "send()"}, @{"getdtablesize()" Link "getdtablesize()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"} @{i}NOTES@{ui} @{b}Select()@{ub} is actually a stub/inline function that calls @{b}WaitSelect()@{ub} with a signal mask set as NULL pointer. @{i}BUGS@{ui} @{b}WaitSelect()@{ub} should probably return the time remaining from the original timeout, if any, by modifying the time value in place. This may be implemented in future versions of the system. Thus, it is unwise to assume that the timeout value will be unmodified by the @{b}WaitSelect()@{ub} call. @{i}HISTORY@{ui} The @{b}select()@{ub} function call appeared in 4.2BSD. @EndNode @Node "send()" "bsdsocket.guide/send()" @Next "SetErrnoPtr()" @Prev "select()" @Toc "Function Reference" @{b}send()@{ub}, @{b}sendto()@{ub}, @{b}sendmsg()@{ub} =========================== @{i}NAME@{ui} @{b}send@{ub}, @{b}sendto@{ub}, @{b}sendmsg@{ub} -- send a message from a socket @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}#include @{ui} @{i}int send(int s, const void * msg, int len, int flags)@{ui} @{i}D0 D0 A0 D1 D2@{ui} @{i}int sendto(int s, const void * msg, int len, int flags,@{ui} @{i}D0 D0 A0 D1 D2@{ui} @{i} const struct sockaddr * to, int tolen)@{ui} @{i} A1 D3@{ui} @{i}int sendmsg(int s, const struct msghdr * msg, int flags)@{ui} @{i}D0 D0 A0 D1@{ui} @{i}DESCRIPTION@{ui} @{b}Send()@{ub} @{b}sendto()@{ub} and @{b}sendmsg()@{ub} are used to transmit a message to another socket. @{b}Send()@{ub} may be used only when the socket is in a @{i}connected@{ui} state, while @{b}sendto()@{ub} and @{b}sendmsg()@{ub} may be used at any time. The address of the target is given by @{b}to@{ub} with @{b}tolen@{ub} specifying its size. The length of the message is given by @{b}len@{ub}. If the message is too long to pass atomically through the underlying protocol, the error @{b}EMSGSIZE@{ub} is returned, and the message is not transmitted. No indication of failure to deliver is implicit in a @{b}send()@{ub} Locally detected errors are indicated by a return value of -1. If no messages space is available at the socket to hold the message to be transmitted, then @{b}send()@{ub} normally blocks, unless the socket has been placed in non-blocking I/O mode. The @{"select()" Link "select()"} call may be used to determine when it is possible to send more data. The @{b}flags@{ub} parameter may include one or more of the following: @{i}#define MSG_OOB 0x1 /*@{i} process out-of-band data @{ui}*/ #define MSG_DONTROUTE 0x4 /*@{i} bypass routing, use direct interface @{ui}*/ @{ui} The flag @{b}MSG_OOB@{ub} is used to send "out-of-band" data on sockets that support this notion (e.g. @{b}SOCK_STREAM@{ub}); the underlying protocol must also support "out-of-band" data. @{b}MSG_DONTROUTE@{ub} is usually used only by diagnostic or routing programs. See @{"recv()" Link "recv()"} for a description of the @{b}msghdr@{ub} structure. @{i}RETURN VALUES@{ui} The call returns the number of characters sent, or -1 if an error occurred. @{i}ERRORS@{ui} @{b}Send()@{ub} @{b}sendto()@{ub} and @{b}sendmsg()@{ub} fail if: @{b}[EBADF]@{ub} An invalid descriptor was specified. @{b}[EMSGSIZE]@{ub} The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. @{b}[EWOULDBLOCK]@{ub} The socket is marked non-blocking and the requested operation would block. @{b}[ENOBUFS]@{ub} The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. @{b}[ENOBUFS]@{ub} The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. @{i}SEE ALSO@{ui} @{"IoctlSocket()" Link "IoctlSocket()"}, @{"recv()" Link "recv()"}, @{"select()" Link "select()"}, @{"getsockopt()" Link "getsockopt()"}, @{"socket()" Link "socket()"} @{i}HISTORY@{ui} The @{b}send()@{ub} function call appeared in 4.2BSD. @EndNode @Node "SetErrnoPtr()" "bsdsocket.guide/SetErrnoPtr()" @Next "SetSocketSignals()" @Prev "send()" @Toc "Function Reference" @{b}SetErrnoPtr()@{ub} ============= @{i}NAME@{ui} @{b}SetErrnoPtr@{ub} -- set the "global" errno pointer (OBSOLETE) @{i}SYNOPSIS@{ui} @{i}void SetErrnoPtr(void * ptr, int size)@{ui} @{i} A0 D0@{ui} @{i}FUNCTION@{ui} This functions allows caller to redirect error variable inside scope of caller task. Usually this is used to make task's global variable errno as error variable. Since AMITCP/IP version 3.0 you can use function @{"SocketBaseTagList()" Link "SocketBaseTagList()"} to set error value pointer. @{i}INPUTS@{ui} @{b}ptr@{ub} pointer to error variable that is to be modified on every error condition on this library function. @{b}size@{ub} size of the error variable. It can be 1, 2 or 4 bytes long. @{i}EXAMPLE@{ui} @{i} #include struct Library; struct Library * SocketBase = NULL; int main(void) { ... if ((SocketBase = OpenLibrary("bsdsocket.library", 2)) != NULL) { SetErrnoPtr(&errno, sizeof errno); ... } }@{ui} @{i}NOTES@{ui} Be sure that this new error variable exists until library base is finally closed or @{b}SetErrnoPtr()@{ub} is called again for another variable. @{i}SEE ALSO@{ui} @{"Errno()" Link "Errno()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"} @EndNode @Node "SetSocketSignals()" "bsdsocket.guide/SetSocketSignals()" @Next "shutdown()" @Prev "SetErrnoPtr()" @Toc "Function Reference" @{b}SetSocketSignals()@{ub} ================== @{i}NAME@{ui} @{b}SetSocketSignals@{ub} -- set SIGINTR, SIGIO and SIGURG signals (OBSOLETE). @{i}SYNOPSIS@{ui} @{i}void SetSocketSignals(ULONG intrmask, ULONG iomask, ULONG urgmask)@{ui} @{i} D0 D1 D2@{ui} @{i}FUNCTION@{ui} @{b}SetSocketSignals()@{ub} tells the AMITCP/IP which signal masks corresponds unix SIGINT, SIGIO and SIGURG signals to be used in current amiga software. The @{b}intrmask@{ub} mask is used to determine which Amiga signals interrupt blocking library calls. The @{b}iomask@{ub} is sent when asynchronous notification of socket events is done and the urgmask is sent when out-of-band data arrives. The signals are sent only to the owning task of particular socket. The task that creates the socket is set to the owner of the socket by default. If the socket is inherited with the @{"ObtainSocket()" Link "ObtainSocket()"} function, the owner must be set explicitly with the @{b}FIOSETOWN@{ub} (@{b}SIOCSPGRP@{ub}) @{"IoctlSocket()" Link "IoctlSocket()"} call. Note that the supplied values write over old ones. If this function is used and CTRL-C is still wanted to interrupt the calls (the default behaviour), the value SIGBREAKF_CTRL_C must be explicitly @{i}or@{ui}'ed to the @{b}intrmask@{ub}. @{i}NOTES@{ui} The function @{b}SetSocketSignals()@{ub} is obsoleted by the function @{"SocketBaseTagList()" Link "SocketBaseTagList()"}. @{i}SEE ALSO@{ui} @{"IoctlSocket()" Link "IoctlSocket()"}, @{"recv()" Link "recv()"}, @{"send()" Link "send()"}, @{"select()" Link "select()"}, @{"SetSocketSignals()" Link "SetSocketSignals()"} @EndNode @Node "shutdown()" "bsdsocket.guide/shutdown()" @Next "socket()" @Prev "SetSocketSignals()" @Toc "Function Reference" @{b}shutdown()@{ub} ========== @{i}NAME@{ui} @{b}shutdown@{ub} -- shut down part of a full-duplex connection @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}int shutdown(int s, int how)@{ui} @{i}D0 D0 D1@{ui} @{i}DESCRIPTION@{ui} The @{b}shutdown()@{ub} call causes all or part of a full-duplex connection on the socket associated with @{b}s@{ub} to be shut down. If @{b}how@{ub} is 0, further receives will be disallowed. If @{b}how@{ub} is 1, further sends will be disallowed. If @{b}how@{ub} is 2, further sends and receives will be disallowed. @{i}DIAGNOSTICS@{ui} A 0 is returned if the call succeeds, -1 if it fails. @{i}ERRORS@{ui} The call succeeds unless: @{b}[EBADF]@{ub} @{b}S@{ub} is not a valid descriptor. @{b}[ENOTCONN]@{ub} The specified socket is not connected. @{i}SEE ALSO@{ui} @{"connect()" Link "connect()"}, @{"socket()" Link "socket()"} @{i}HISTORY@{ui} The @{b}shutdown()@{ub} function call appeared in 4.2BSD. @EndNode @Node "socket()" "bsdsocket.guide/socket()" @Next "SocketBaseTagList()" @Prev "shutdown()" @Toc "Function Reference" @{b}socket()@{ub} ======== @{i}NAME@{ui} @{b}socket@{ub} -- create an endpoint for communication @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}#include @{ui} @{i}int socket(int domain, int type, int protocol)@{ui} @{i}D0 D0 D1 D2@{ui} @{i}DESCRIPTION@{ui} @{b}Socket()@{ub} creates an endpoint for communication and returns a descriptor. The @{b}domain@{ub} parameter specifies a communications domain within which communication will take place; this selects the protocol family which should be used. These families are defined in the include file @{b}@{ub}. The currently understood formats are @{i}AF_UNIX (UNIX internal protocols), AF_INET (ARPA Internet protocols), AF_ISO (ISO protocols), AF_NS (Xerox Network Systems protocols), and AF_IMPLINK (IMP ``host at IMP'' link layer).@{ui} AMITCP/IP currently supports only @{i}AF_INET@{ui} protocol family. The socket has the indicated @{b}type@{ub}, which specifies the semantics of communication. Currently defined types are: @{i}SOCK_STREAM SOCK_DGRAM SOCK_RAW SOCK_SEQPACKET SOCK_RDM@{ui} A @{b}SOCK_STREAM@{ub} type provides sequenced, reliable, two-way connection based byte streams. An out-of-band data transmission mechanism may be supported. A @{b}SOCK_DGRAM@{ub} socket supports datagrams (connectionless, unreliable messages of a fixed (typically small) maximum length). A @{b}SOCK_SEQPACKET@{ub} socket may provide a sequenced, reliable, two-way connection-based data transmission path for datagrams of fixed maximum length; a consumer may be required to read an entire packet with each read system call. This facility is protocol specific, and presently implemented only for @{b}PF_NS@{ub}. @{b}SOCK_RAW@{ub} sockets provide access to internal network protocols and interfaces. The types @{b}SOCK_RAW@{ub}, which is available only to the super-user, and @{b}SOCK_RDM@{ub}, which is planned, but not yet implemented, are not described here. The @{b}protocol@{ub} specifies a particular protocol to be used with the socket. Normally only a single protocol exists to support a particular socket type within a given protocol family. However, it is possible that many protocols may exist, in which case a particular protocol must be specified in this manner. The protocol number to use is particular to the "communication domain" in which communication is to take place. Sockets of type @{b}SOCK_STREAM@{ub} are full-duplex byte streams, similar to pipes. A stream socket must be in a @{i}connected@{ui} state before any data may be sent or received on it. A connection to another socket is created with a @{"connect()" Link "connect()"} call. Once connected, data may be transferred using @{"recv()" Link "recv()"} and @{"send()" Link "send()"} or their variant calls. When a session has been completed a @{"CloseSocket()" Link "CloseSocket()"} may be performed. Out-of-band data may also be transmitted as described in @{"send()" Link "send()"} and received as described in @{"recv()" Link "recv()"}. The communications protocols used to implement a @{b}SOCK_STREAM@{ub} insure that data is not lost or duplicated. If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, then the connection is considered broken and calls will indicate an error with -1 returns and with @{b}ETIMEDOUT@{ub} as the specific error code (see @{"Errno()" Link "Errno()"}). The protocols optionally keep sockets "warm" by forcing transmissions roughly every minute in the absence of other activity. An error is then indicated if no response can be elicited on an otherwise idle connection for a extended period (e.g. 5 minutes). @{b}SOCK_SEQPACKET@{ub} sockets employ the same system calls as @{b}SOCK_STREAM@{ub} sockets. The only difference is that @{"recv()" Link "recv()"} calls will return only the amount of data requested, and any remaining in the arriving packet will be discarded. @{b}SOCK_DGRAM@{ub} and @{b}SOCK_RAW@{ub} sockets allow sending of datagrams to correspondents named in @{"send()" Link "send()"} calls. Datagrams are generally received with @{"recvfrom()" Link "recv()"}, which returns the next datagram with its return address. An @{"IoctlSocket()" Link "IoctlSocket()"} call can be used to specify a task to receive a @{b}SIGURG@{ub} signal when the out-of-band data arrives. It may also enable non-blocking I/O and asynchronous notification of I/O events via @{b}SIGIO@{ub}. The operation of sockets is controlled by socket level @{i}options@{ui}. These options are defined in the file @{b}@{ub}. @{b}setsockopt()@{ub} and @{"getsockopt()" Link "getsockopt()"} are used to set and get options, respectively. @{i}RETURN VALUES@{ui} A -1 is returned if an error occurs, otherwise the return value is a descriptor referencing the socket. @{i}ERRORS@{ui} The @{b}socket()@{ub} call fails if: @{b}[EPROTONOSUPPORT]@{ub} The protocol type or the specified protocol is not supported within this domain. @{b}[EMFILE]@{ub} The per-process descriptor table is full. @{b}[EACCESS]@{ub} Permission to create a socket of the specified type and/or protocol is denied. @{b}[ENOBUFS]@{ub} Insufficient buffer space is available. The socket cannot be created until sufficient resources are freed. @{i}SEE ALSO@{ui} @{"accept()" Link "accept()"}, @{"bind()" Link "bind()"}, @{"connect()" Link "connect()"}, @{"CloseSocket()" Link "CloseSocket()"}, @{"getprotobyname()" Link "getprotobyname()"}, @{"getsockname()" Link "getsockname()"}, @{"getsockopt()" Link "getsockopt()"}, @{"IoctlSocket()" Link "IoctlSocket()"}, @{"listen()" Link "listen()"}, @{"recv()" Link "recv()"}, @{"select()" Link "select()"}, @{"send()" Link "send()"}, @{"shutdown()" Link "shutdown()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"} `An Introductory 4.3 BSD Interprocess Communication Tutorial', reprinted in UNIX Programmer's Supplementary Documents Volume 1. `BSD Interprocess Communication Tutorial', reprinted in UNIX Programmer's Supplementary Documents Volume 1. @{i}NOTES@{ui} @{b}socket()@{ub} calls the @{b}fdCallback()@{ub} with action codes @{b}FDCB_CHECK@{ub} and @{b}FDCB_ALLOC@{ub} to check and mark the new descriptor as allocated if the callback is defined. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more information on @{b}fdCallback()@{ub}. @{i}HISTORY@{ui} The @{b}socket()@{ub} function call appeared in 4.2BSD. @EndNode @Node "SocketBaseTagList()" "bsdsocket.guide/SocketBaseTagList()" @Next "syslog()" @Prev "socket()" @Toc "Function Reference" @{b}SocketBaseTagList()@{ub} =================== @{i}NAME@{ui} @{b}SocketBaseTagList@{ub} -- Set/Get SocketBase attributes. @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}ULONG SocketBaseTagList(struct TagItem * taglist);@{ui} @{i}D0 A0@{ui} @{i}ULONG SocketBaseTags(ULONG tag, ...);@{ui} @{i}FUNCTION@{ui} Set or get a list of (mostly) SocketBase instance dependent attributes from the AMITCP/IP. @{i}INPUTS@{ui} These functions expect as their argument a standard tag list, one or several array of struct TagItem as defined in the header file @{b}@{ub}. The structure contains two fields: @{b}ti_Tag@{ub} and @{b}ti_Data@{ub}. The @{b}ti_Tag@{ub} field contains tag code, which determines what the @{b}SocketBaseTagList()@{ub} should do with its argument, the @{b}ti_Data@{ub} field. The include file @{b}@{ub} defines macros for base tag code values. Base tag code macros begin with `SBTC_' (as Socket Base Tag Code). The base tag value defines what data item the tag item refers. The tag code contains other information besides the referred data item. It controls, whether the @{b}SocketBaseTagList()@{ub} should set or get the appropriate parameter, and whether the argument of the tag in question is passed by value or by reference. The include file @{b}@{ub} defines the following macros, which are used to construct the @{b}ti_Tag@{ub} values from the base tag codes: SBTM_GETREF(code) - get by reference SBTM_GETVAL(code) - get by value SBTM_SETREF(code) - set by reference SBTM_SETVAL(code) - set by value If the actual data is stored directly into the @{b}ti_Data@{ub} field, you should use the 'by value' macros, @{b}SBTM_GETVAL()@{ub} or @{b}SBTM_SETVAL()@{ub}. However, if the @{b}ti_Data@{ub} field contains a pointer to actual data, you should use the 'by reference' macros, @{b}SBTM_GETREF()@{ub} or @{b}SBTM_SETREF()@{ub}. In either case the actual data should always be a LONG aligned to even address. According the used tag naming scheme a tag which has "PTR" suffix takes an pointer as its argument. Don't mix the pointer arguments with 'by reference' argument passing. It is possible to pass a pointer by reference (in which case the @{b}ti_Data@{ub} is a pointer to the actual pointer). The list of all defined base tag codes is as follows: @{b}SBTC_BREAKMASK@{ub} Tag data contains the INTR signal mask. If the calling task receives a signal in the INTR mask, the AMITCP/IP interrupts current function calls and returns with the error code EINTR. The INTR mask defaults to the CTRL-C signal (SIGBREAKF_C, bit 12). @{b}SBTC_DTABLESIZE@{ub} Socket Descriptor Table size. This defaults to 64. @{b}SBTC_ERRNO@{ub} The errno value. The values are defined in @{"" Link ""}. @{b}SBTC_ERRNOBYTEPTR@{ub} @{b}SBTC_ERRNOWORDPTR@{ub} @{b}SBTC_ERRNOLONGPTR@{ub} @{b}SBTC_ERRNOPTR(size)@{ub} Set (only) the pointer to the errno variable defined by the program. AMITCP/IP defines a value for this by default, but the application must set the pointer (and the size of the @{b}errno@{ub}) with one of these tags, if it wishes to access the errno variable directly. The SBTC_ERRNOPTR(size) is a macro, which expands to one of the other (@{b}BYTE@{ub}, @{b}WORD@{ub} or @{b}LONG@{ub}) tag codes, meaning that only 1, 2 and 4 are legal size values. The @{b}NetLib:autoinit.c@{ub} sets the errno pointer for the application, if the application is linked with it. @{b}SBTC_ERRNOSTRPTR@{ub} Returns an error string pointer describing the errno value given on input. You can not set the error message, only get is allowed. On call the @{b}ti_Data@{ub} must contain the error code number. On return the @{b}ti_Data@{ub} is assigned to the string pointer. (@{b}*ti_Data@{ub}, if passed by reference). See the file @{"" Link ""} for symbolic definitions for the errno codes. @{b}SBTC_FDCALLBACK@{ub} A callback function pointer for coordination of file descriptor usage between AMITCP/IP and link-library. By default no callback is called and the value of this pointer is NULL. The prototype for the callback function is: @{i}int error = fdCallback(int fd, int action);@{ui} @{i}D0 D0 D1@{ui} where @{b}error@{ub} - 0 for success or one of the error codes in @{"" Link ""} in case of error. The AMITCP/IP API function that calls the callback usually returns the @{b}error@{ub} back to the caller without any further modification. @{b}fd@{ub} - file descriptor number to take @{b}action@{ub} on. @{b}action@{ub} - one of the action codes, which are defined in the header file @{"" Link ""}) as follows: @{b}FDCB_FREE@{ub} - mark the @{b}fd@{ub} as unused on the link library structure. If @{b}fd@{ub} represents a file handled by the link library, the error @{b}ENOTSOCK@{ub} should be returned. @{b}FDCB_ALLOC@{ub} - mark the @{b}fd@{ub} allocated as a socket. @{b}FDCB_CHECK@{ub} -check if the @{b}fd@{ub} is free. If an error is returned, the @{b}fd@{ub} is marked as used in the AMITCP/IP structures. The AMITCP/IP calls the callback every time a socket descriptor is allocated or freed. AMITCP/IP uses the @{b}FDCB_CHECK@{ub} before actual allocation to check that it agrees with the link library on the next free descriptor number. Thus the link library doesn't need to tell the AMITCP/IP if it creates a new file handle in @{b}open()@{ub}, for example. See file @{b}_chkufb.c@{ub} on the @{i}net.lib@{ui} sources for an example implementation of the callback function for the SAS/C. @{b}SBTC_HERRNO@{ub} The name resolver error code value. Get this to find out why the @{b}gethostbyname()@{ub} or @{b}gethostbyaddr()@{ub} failed. The values are defined in @{"" Link ""}. @{b}SBTC_HERRNOSTRPTR@{ub} Returns host error string for error number in tag data. Host error is set on unsuccesful @{"gethostbyname()" Link "gethostbyname()"} and @{"gethostbyaddr()" Link "gethostbyaddr()"} calls. See the file @{"" Link ""} for the symbolic definitions for the @{b}herrno@{ub} valus. Notes for the @{b}SBTC_ERRNOSTRPTR@{ub} apply also to this tag code. @{b}SBTC_IOERRNOSTRPTR@{ub} Returns an error string for standard AmigaOS I/O error number as defined in the header file @{"" Link ""}. Note that the error number taken by this tag code is positive, so the error codes must be negated (to be positive). The positive error codes depend on the particular IO device, the standard Sana-II error codes can be retrieved by the tag code @{b}SBTC_S2ERRNOSTRPTR@{ub}. Notes for the @{b}SBTC_ERRNOSTRPTR@{ub} apply also to this tag code. @{b}SBTC_LOGFACILITY@{ub} Facility code for the syslog messages as defined in @{b}@{ub}. Defaults to @{b}LOG_USER@{ub}. @{b}SBTC_LOGMASK@{ub} Sets the filter mask of the syslog messages. By default the mask is @{b}0xff@{ub}, meaning that all messages are passed to the log system. @{b}SBTC_LOGSTAT@{ub} Syslog options defined in @{b}@{ub}. @{b}SBTC_LOGTAGPTR@{ub} A pointer to a string which is used by @{b}Syslog()@{ub} to mark individual syslog messages. This defaults to @{b}NULL@{ub}, but is set to the name of the calling program by the autoinit code in @{b}netlib:autoinit.c@{ub}. This is for compatibility with pre-3.0 programs. @{b}SBTC_S2ERRNOSTRPTR@{ub} Returns an error string for a Sana-II specific I/O error code as defined in the header file @{"" Link ""}. Notes for the @{b}SBTC_ERRNOSTRPTR@{ub} apply also to this tag code. @{b}SBTC_S2WERRNOSTRPTR@{ub} Returns an error string for a Sana-II Wire Error code as defined in the header file @{"" Link ""}. Notes for the SBTC_ERRNOSTRPTR apply also to this tag code. @{b}SBTC_SIGEVENTMASK@{ub} Tag data contains the signal mask to be sent to the application whenever notification about socket events is in order. The default value for this is zero, inhibiting any event notifications. The application must set this mask if it desires to be notified about asynchronous socket events. When the application receives the signal specified in the mask, it can use the function @{"GetSocketEvents()" Link "GetSocketEvents()"} to find out what happened. @{b}SBTC_SIGIOMASK@{ub} The signals specified in the mask in the tag data are sent to the calling task when asynhronous I/O is to be notified. The default value is zero, i.e., no signals are sent. The signals in the mask are sent whenever something happens on the socket. This mechanism is compatible with the Unix SIGIO signal. Since AmigaOS signals may get combined, one signal may include notification for originally distinct events on the socket. One example of this is the reception of data and connection closure. Usage of the socket events (see @{"GetSocketEvents()" Link "GetSocketEvents()"}) is recommended over this because of the problem described above. @{b}SBTC_SIGURGMASK@{ub} The signals specified in the mask in the tag data are sent to the calling task when notification about urgent data arrives. The default value is zero, ie. no signals are sent. This mechanism is compatible with the Unix SIGURG signal. Note that this signal does not indicate the arrival of the actual out-of-band data. If the receive buffer of the socket is full, the urgent data can't even be received. Because of this the application may need to read some normal data off the socket before it can read the urgent data. @{i}RESULT@{ui} Returns 0 on success, and a (positive) index of the failing tag on error. Note that the value 1 means @{i}first@{ui} TagItem, 2 the second one, and so on. The return value is NOT a C-language index, which are 0 based. @{i}EXAMPLES@{ui} To be written, see @{b}net.lib@{ub} sources for various examples. @{i}SEE ALSO@{ui} @{"" Link ""}, @{"" Link ""} @EndNode @Node "syslog()" "bsdsocket.guide/syslog()" @Prev "SocketBaseTagList()" @Toc "Function Reference" @{b}syslog()@{ub}, @{b}vsyslog()@{ub} =================== @{i}NAME@{ui} @{b}syslog@{ub}, @{b}vsyslog@{ub} -- write message to AMITCP/IP log @{i}SYNOPSIS@{ui} @{i}#include @{ui} @{i}void syslog(int priority, const char * message, ...)@{ui} @{i}void vsyslog(int level, const char * format, LONG * args)@{ui} @{i} D0 A0 A1@{ui} @{i}DESCRIPTION@{ui} Writes the message given as format string and arguments (printf-style) both to the log file and to the console. The message is prepended with the name of the calling application, if the name is known by AMITCP/IP (the standard autoinitiazer module in the net.lib passes the name of the application to AMITCP/IP). The message is identical to a @{b}printf()@{ub} format string, except that @{b}%m@{ub} is replaced by the current error message. (As denoted by the library variable @{b}errno@{ub} (see @{"Errno()" Link "Errno()"}).) A trailing newline is added if none is present. The level is selected from an ordered list: @{b}LOG_EMERG@{ub} A panic condition. @{b}LOG_ALERT@{ub} A condition that should be corrected immediately, such as a corrupted system database. @{b}LOG_CRIT@{ub} Critical conditions, e.g., hard device errors. @{b}LOG_ERR@{ub} Errors. @{b}LOG_WARNING@{ub} Warning messages. @{b}LOG_NOTICE@{ub} Conditions that are not error conditions, but should possibly be handled specially. @{b}LOG_INFO@{ub} Informational messages. @{b}LOG_DEBUG@{ub} Messages that contain information normally of use only when debugging a program. @{i}INPUTS@{ui} @{b}Level@{ub} indicates the type of the message. The levels are defined in sys/syslog.h and listed above. @{b}format@{ub} This is a printf-style format string. In addition @{b}%m@{ub} is expanded to current error message. @{b}...@{ub} arguments as in printf(). @{b}args@{ub} pointer to an array of arguments. @{i}RESULT@{ui} Returns no value. @{i}EXAMPLES@{ui} To log a message at priority LOG_INFO, it would make the following call to syslog: @{i}syslog(LOG_ALERT, "who: internal error 23"); syslog(LOG_INFO, "Connection from host %s", CallingHost);@{ui} @{i}NOTES@{ui} In contrast to the previous releases of the AMITCP/IP, the integer arguments are expected to be 32 bits wide, thus eliminating the need to specify the 'l' size modifier for the number formatters. This function is callable from interrupts. @{i}BUGS@{ui} Because there is a limited number of internal messages used by the logging system, some log messages may get lost if a high priority task or interrupt handler sends many messages in succession. If this happens, the next log message tells the fact. @{i}SEE ALSO@{ui} @{b}src/netlib/syslog.c@{ub} for syslog utility functions (@{b}openlog()@{ub}, @{b}closelog()@{ub} and @{b}setlogmask()@{ub}), C-library @{b}printf()@{ub} documentation @{i}HISTORY@{ui} These functions appeared in 4.2BSD. @EndNode @Node "Function Reference" "bsdsocket.guide/Function Reference" @Prev "Disclaimer & Copyright" @Toc "Main" Function Index ************** @{" accept " Link "accept()"} accept() @{" bind " Link "bind()"} bind() @{" CloseSocket " Link "CloseSocket()"} CloseSocket() @{" connect " Link "connect()"} connect() @{" Dup2Socket " Link "Dup2Socket()"} Dup2Socket() @{" Errno " Link "Errno()"} Errno() @{" getdtablesize " Link "getdtablesize()"} getdtablesize() @{" gethostbyaddr " Link "gethostbyname()"} gethostbyname() @{" gethostbyname " Link "gethostbyname()"} gethostbyname() @{" gethostid " Link "gethostid()"} gethostid() @{" gethostname " Link "gethostname()"} gethostname() @{" getnetbyaddr " Link "getnetbyname()"} getnetbyname() @{" getnetbyname " Link "getnetbyname()"} getnetbyname() @{" getpeername " Link "getpeername()"} getpeername() @{" getprotobyname " Link "getprotobyname()"} getprotobyname() @{" getprotobynumber " Link "getprotobyname()"} getprotobyname() @{" getservbyname " Link "getservbyname()"} getservbyname() @{" getservbyport " Link "getservbyname()"} getservbyname() @{" GetSocketEvents " Link "GetSocketEvents()"} GetSocketEvents() @{" getsockname " Link "getsockname()"} getsockname() @{" getsockopt " Link "getsockopt()"} getsockopt() @{" htonl " Link "htonl()"} htonl() @{" htons " Link "htonl()"} htonl() @{" inet_addr " Link "inet_addr()"} inet_addr() @{" inet_lnaof " Link "inet_addr()"} inet_addr() @{" Inet_LnaOf " Link "inet_addr()"} inet_addr() @{" inet_makeaddr " Link "inet_addr()"} inet_addr() @{" Inet_MakeAddr " Link "inet_addr()"} inet_addr() @{" inet_netof " Link "inet_addr()"} inet_addr() @{" Inet_NetOf " Link "inet_addr()"} inet_addr() @{" inet_network " Link "inet_addr()"} inet_addr() @{" inet_ntoa " Link "inet_addr()"} inet_addr() @{" Inet_NtoA " Link "inet_addr()"} inet_addr() @{" IoctlSocket " Link "IoctlSocket()"} IoctlSocket() @{" listen " Link "listen()"} listen() @{" ntohl " Link "htonl()"} htonl() @{" ntohs " Link "htonl()"} htonl() @{" ObtainSocket " Link "ObtainSocket()"} ObtainSocket() @{" recv " Link "recv()"} recv() @{" recvfrom " Link "recv()"} recv() @{" recvmsg " Link "recv()"} recv() @{" ReleaseCopyOfSocket " Link "ReleaseSocket()"} ReleaseSocket() @{" ReleaseSocket " Link "ReleaseSocket()"} ReleaseSocket() @{" select " Link "select()"} select() @{" send " Link "send()"} send() @{" sendmsg " Link "send()"} send() @{" sendto " Link "send()"} send() @{" SetErrnoPtr " Link "SetErrnoPtr()"} SetErrnoPtr() @{" SetSocketSignals " Link "SetSocketSignals()"} SetSocketSignals() @{" setsockopt " Link "getsockopt()"} getsockopt() @{" shutdown " Link "shutdown()"} shutdown() @{" socket " Link "socket()"} socket() @{" SocketBaseTagList " Link "SocketBaseTagList()"} SocketBaseTagList() @{" syslog " Link "syslog()"} syslog() @{" vsyslog " Link "syslog()"} syslog() @{" WaitSelect " Link "select()"} select() @EndNode