AmigActive 20

home *** CD-ROM | disk | FTP | other *** search

/ AmigActive 20 / AACD20.BIN / AACD / Programming / TTCP_SDK / tsocket.doc < prev next >

Wrap

Text File | 1996-07-28 | 47.9 KB | 1,504 lines

API Function Reference ********************** tsocket.library Version 1.00 ©1996 Oregon Research All rights reserved. ********************** Portions of this manual are based on original documents from BSD, which is hereby acknowledged: ***************************************************************************** Copyright © 1982, 1986, 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 acknowledgement: 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. ***************************************************************************** tsocket.library Version 1.00 tsocket.library/accept tsocket.library/bind tsocket.library/CloseSocket tsocket.library/connect tsocket.library/FD_SET, FD_CLR, FD_ISSET, FD_ZERO tsocket.library/gethostbyaddr tsocket.library/gethostbyname tsocket.library/gethostid tsocket.library/gethostname tsocket.library/getprotobyname tsocket.library/getprotobynumber tsocket.library/getservbyname tsocket.library/getsockname tsocket.library/inet_addr tsocket.library/inet_ntoa tsocket.library/IoctlSocket tsocket.library/listen tsocket.library/recv tsocket.library/recvfrom tsocket.library/send tsocket.library/sendto tsocket.library/SetErrnoPtr tsocket.library/SetSocketSignals tsocket.library/setsockopt tsocket.library/shutdown tsocket.library/socket tsocket.library/SocketBaseTagList tsocket.library/WaitSelect ****************************************************************************** What is tsocket.library? The primary programmer's interface to Internet network protocols is the Berkley Software Distribution socket abstraction. tsocket.library is a link library providing you access to network programming. We recommend that you acquire the books "Unix Network Programming" by W. Richard Stephens (Prentice-Hall, 1990) and "Internetworking with TCP/IP, Volume II" by Douglas Comer and David Stephens (Prentice-Hall, 1991). Writing programs using TCP/IP and sockets can be difficult and these books provide invaluable information. Providing the network sfunctions as shared library provides many benefits. The most important benefit is that it is easily upgradable. New libraries with bug fixes, speed improvements, or additional functions can be utilized by existing code without recompilation of client programs. This easy extendability is especially important for this first release. This function reference is under construction. Termite TCP contains many more functions than are currently documented. In an effort to get this information out as quickly as possible, this first version of the SDK only documents the basic functions necessary to write network applications. Compliation Notes: TermiteTCP and all client programs must compile with the symbol TERMITE_TCP defined. Otherwise, you will get errors from the BSD include files which have been modified for conditional compliation. The majority of tsocket.library calls follow the convention that a zero or positive return indicates success, and a -1 return indicates an error, with extended error code written to errno(see SetErrorPtr()). All integers are assumed to be 32-bit. None are specified as long in order to maintain Un*x compatibility. If you are using a compiler which doesn't use 32-bit ints, you must make sure that all ints are converted to longs by your code. The shared socket library returns a different library base for each OpenLib() and uses these different library bases to keep track of some global data for each opener. If you start a new process with a new context, the new process must open and initialize socket.library such as shown below. Example: /* the next three lines must always be here */ #include <pragmas/tsocket_pragmas.h> #include <proto/tsocket.h> struct Library *TSocketBase; /* your includes here */ main() { if((TSocketBase = OpenLibrary( "tsocket.library", 1L )) == NULL) { printf("Error opening tsocket.library\n"); Exit(10); } ... your code here ... CloseLibrary( TSocketBase ) ; } ****************************************************************************** tsocket.library API Function Reference ****************************************************************************** ****************************************************************************** accept ****************************************************************************** NAME accept -- accept a connection on a socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int accept(int s, struct sockaddr *addr, int *addrlen) D0 D0 A0 A1 DESCRIPTION The connections are accept()ed on a socket which on which bind() and listen() have been executed. Unless there is an error, accept() will return a new socket which is connected. accept() looks for a pending connection and creates a new socket with the same properties of s. If ther are no pending connections and the socket is non-blocking accept() blocks the caller andf waits for a connection. If the socket is non-blocking and there are no pending connections, accept() 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(using send and recv). It is not used to accept more connections. The original socket s remains open. INPUTS s is a socket created with socket() addr is is filled in with the address of the connecting entity. The exact format of the addr parameter is determined by the domain in which the communication is occurring. addrlen should initially contain the amount of space pointed to by addr, 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 SOCK_STREAM. RETURNS The call returns -1 on error. If it succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. ERRORS EBADF The descriptor is invalid. EINTR The operation was interrupted by a break signal. EOPNOTSUPP The referenced socket is not of type SOCK_STREAM. EWOULDBLOCK The socket is non-blocking and no connections are present to be accepted. SEE ALSO bind(), connect(), listen(), select(), SetSocketSignals(), socket() ****************************************************************************** bind ****************************************************************************** NAME bind -- bind a name to a socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int bind(int s, struct sockaddr *name, int namelen) D0 D0 A0 D1 DESCRIPTION Bind() assigns a name to an unnamed socket. When a socket is created with socket() it exists in a name space (address family) but has no name assigned. Bind() requests that name be assigned to the socket. INPUTS s socket descriptor. name address to bind to socket 's.' namelen length (in bytes) of 'name.' RETURNS If the bind is successful, a 0 value is returned. A return value of -1 indicates an error. ERRORS EBADF S is not a valid descriptor. EADDRNOTAVAIL The specified address is not available from the local machine. EADDRINUSE The specified address is already in use. EINVAL The socket is already bound to an address. EACCES The requested address is protected, and the current user has inadequate permission to access it. SEE ALSO connect(), listen(), socket(), getsockname() ****************************************************************************** CloseSocket ****************************************************************************** NAME CloseSocket -- delete a socket descriptor SYNOPSIS int CloseSocket(int s) D0 D0 DESCRIPTION The CloseSocket() call deletes a descriptor from the socket reference table. If this is the last reference to the socket, it will be deleted and associated naming information and queued data are discarded. All sockets are closed when the socket library is closed, but closing sockets as soon as possible is recommended to save system resources. INPUTS s socket descriptor RETURNS 0 on success -1 on error ERRORS EBADF S is not an active socket descriptor. EINTR An interupt was received. SEE ALSO accept(), shutdown(), socket(), ****************************************************************************** connect ****************************************************************************** NAME connect -- initiate a connection on a socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int connect(int s, struct sockaddr *name, int namelen) D0 D0 A0 D1 DESCRIPTION To communicate with a server using TCP, the client must connect() a socket obtained by the client (from socket()) to the server's well-known address. (The server will receive (from accept()) a new socket which is connected to the socket which the client is connect()ing to the server.) Most clients should build 'name' from a well-known port obtained from getservbyname(). If s is of type SOCK_DGRAM, this call specifies the peer with which the socket is to be associated. If the socket is of type SOCK_STREAM, this call attempts to make a connection to the named socket. Generally, stream sockets may successfully connect() only once; datagram sockets may use connect() multiple times to change their association. Datagram sockets may dissolve the association by connecting to an invalid address, such as a null address. INPUTS s socket descriptor. name address of socket to connect 's' to. namelen length of 'name.' RETURNS 0 on success -1 on error ERRORS EBADF S is not a valid descriptor. EADDRNOTAVAIL The specified address is not available on this machine. EAFNOSUPPORT Addresses in the specified family cannot be used with this socket. EISCONN The socket is already connected. ETIMEDOUT Connection establishment timed out without establishing a connection. ECONNREFUSED The attempt to connect was rejected EUNREACH The network isn't reachable from this host. EADDRINUSE The address is already in use. EINPROGRESS The socket is non-blocking and the connection cannot be completed immediately. It is possible to select() for completion by selecting the socket for writing. EALREADY The socket is non-blocking and a previous connection attempt has not yet been completed. SEE ALSO accept(), select(), socket(), getsockname() **************************************************************************** FD_SET, FD_CLR, FD_ISSET, FD_ZERO **************************************************************************** NAME FD_SET, FD_CLR, FD_ISSET, FD_ZERO - Macros to manipulate socket masks. SYNOPSIS #include <sys/types.h> FD_SET(socket, mask) FD_CLR(socket, mask) result = FD_ISSET(socket, mask) FD_ZERO(mask) DESCRIPTION Type fd_set contains masks for use with sockets and WaitSelect(). To manipulate socket masks you must use the FD_*() macros. FD_SET() sets the "bit" for 'socket' in 'mask.' FD_CLR() clears the "bit" for 'socket' in 'mask.' FD_ISSET() returns non-zero if the "bit" for 'socket' in 'mask' is set, else zero. FD_ZERO() clears all "bits" in 'mask.' FD_ZERO should be used to initialize an fd_set variable before it is used. SEE ALSO WaitSelect() ****************************************************************************** gethostbyname, gethostbyaddr ****************************************************************************** NAME gethostbyname, gethostbyaddr -- get network host entry SYNOPSIS #include <netdb.h> extern struct h_errno; struct hostent * gethostbyname(char *name) D0 A0 struct hostent * gethostbyaddr(char *addr, int len, int type) D0 A0 D0 D1 DESCRIPTION/RETURNS These functions 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. struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* host address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ }; The members of this structure are: h_name Official name of the host. h_aliases A zero terminated array of alternate names for the host. h_addrtype The type of address being returned; currently always AF_INET. h_length The length, in bytes, of the address. h_addr_list A zero terminated array of network addresses for the host. Host addresses are returned in network byte order. ERRORS Error return status from gethostbyname() and gethostbyaddr() is indicated by return of a null pointer. The library integer h_errno may be checked for more information about the failure. The library variable h_errno can have the following values: HOST_NOT_FOUND No such host is known. TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from the name server. A retry at some later time may succeed. NO_RECOVERY Some unexpected non-recoverable error. NO_DATA 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. ***************************************************************************** gethostid ***************************************************************************** NAME gethostid -- get unique IP address of current host SYNOPSIS long gethostid(void) D0 DESCRIPTION gethostid() returns the 32-bit identifier for the current processor that is intended to be unique among all UNIX systems in existence. This is normally the IP address for the local machine. SEE ALSO gethostname() ***************************************************************************** gethostname ***************************************************************************** NAME gethostname -- get name of current host SYNOPSIS int gethostname(char *name, int namelen) D0 A0 D0 DESCRIPTION Gethostname() returns the standard host name for the current processor. The null-terminated hostname is copied into 'name'. The hostname will be truncated if insufficient space is available in 'name'. INPUTS name pointer to character array. length size of character array. ***************************************************************************** getprotobyname(), getprotobynumber() ***************************************************************************** NAME getprotobynumber, getprotobyname -- get protocol entry SYNOPSIS #include <netdb.h> struct protoent * getprotobyname(char *name) D0 A0 struct protoent * getprotobynumber(int proto) D0 D0 DESCRIPTION Thesefunctions each return a pointer to an object with the following structure containing the fields of a line in the network protocol data base. struct protoent { char *p_name; /* official name of protocol */ char **p_aliases; /* alias list */ int p_proto; /* protocol number */ }; The members of this structure are: p_name The official name of the protocol. p_aliases A zero terminated list of alternate names for the protocol. p_proto The protocol number. RETURNS A null pointer (0) returned on EOF or error. ****************************************************************************** getservbyname() ****************************************************************************** NAME getservbyname -- get service entry SYNOPSIS #include <netdb.h> struct servent * getservbyname(char *name, char *proto) D0 A0 A1 DESCRIPTION This function returns a pointer to an object with the following structure containing the fields of a line in the network services data base. struct servent { char *s_name; /* official name of service */ char **s_aliases; /* alias list */ int s_port; /* port service resides at */ char *s_proto; /* protocol to use */ }; The members of this structure are: s_name The official name of the service. s_aliases A zero terminated list of alternate names for the service. s_port The port number at which the service resides. Port numbers are returned in network byte order. s_proto The name of the protocol to use when contacting the service. INPUTS name name of service to look up. proto protocol of service to look up. ERRORS A null pointer (0) returned on EOF or error. SEE ALSO getprotobyname() *************************************************************************** getsockname *************************************************************************** NAME getsockname -- get socket name SYNOPSIS int getsockname(int s, struct sockaddr *name, int *namelen) D0 D0 A0 A1 DESCRIPTION Getsockname() returns the current name for the specified socket. The namelen parameter should be initialized to indicate the amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes). INPUTS s socket descriptor. name socket name. namelen size of 'name' (in bytes). RETURNS 0 on success -1 on failure ERRORS EBADF The argument s is not a valid descriptor. ENOBUFS Insufficient resources were available to perform the operation. SEE ALSO bind(), socket() ***************************************************************************** inet_addr, inet_ntoa ***************************************************************************** NAME inet_addr - Internet address manipulation routines inet_ntoa SYNOPSIS #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> unsigned long inet_addr(const char * cp) D0 A0 char *inet_ntoa(struct in_addr in) DESCRIPTION inet_addr() converts a character string containing a Internet standard `.' address notation and returns the actual 32 bit Internet address inet_ntoa() is the reverse and takes an Internet address and returns an string representing the address in standard Internet '.' format. All Internet addresses are returned in network order(from left to right). SEE ALSO gethostbyname() ***************************************************************************** IoctlSocket ***************************************************************************** NAME IoctlSocket -- control sockets SYNOPSIS #include <sys/ioctl.h> int IoctlSocket(int s, unsigned long request, char * argp) D0 D0 D1 A0 DESCRIPTION IoctlSocket() performs a special function on the socket descriptor s. For most IoctlSocket() 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 request includes whether the argument is an input parameter or an output parameter, and the size of the argument argp in bytes. Macros and defines used in specifying an ioctl request are located in the file <sys/ioctl.h>. The following requests are supported: FIOASYNC 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 asynchronous I/O. FIOCLEX FIONCLEX Ignored, no use for close-on-exec flag in Amiga. FIOGETOWN SIOCGPGRP 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(). FIONBIO 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. FIONREAD 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. FIOSETOWN SIOCSPGRP The argument is pointer to struct Task*, pointer to the task that will subsequently receive SIGIO or SIGURG signals for the socket referred to by the descriptor passed. SIOCCATMARK 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. RETURNS 0 on success for most requests. Some specialized requests may return a positive non-zero values on success -1 on failure and sets errno to indicate the error. ERRORS EBADF s is not a valid descriptor. EINVAL Request or argp is not valid. ****************************************************************************** listen ****************************************************************************** NAME listen -- listen for connections on a socket SYNOPSIS #include <sys/socket.h> int listen(int s, int backlog) D0 D0 D1 DESCRIPTION This function is used to indicate that a socket it is waiting to receive connections. It is usually executed after socket() and bind(), and before accept(). To accept connections, a socket is first created with socket(), a willingness to accept incoming connections and a queue limit are then specified with listen() and then the connections are accepted with accept(). The listen() call applies only to sockets of type SOCK_STREAM or SOCK_SEQPACKET. The backlog parameter defines the maximum length the queue of pending connections may grow to. If a connection request arrive with the queue full the client may receive an error with an indication of ECONNREFUSED, or, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed. NPUTS s socket descriptor. backlog max number of connection requests to queue (usually 5). RETURNS 0 on success -1 on an error. ERRORS EBADF The argument s is not a valid descriptor. EOPNOTSUPP The socket is not of a type that supports the operation listen() SEE ALSO accept(), connect(), socket() *************************************************************************** recv, recvfrom *************************************************************************** NAME recv, recvfrom -- receive a message from a socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int recv(int s, void *buf, int len, int flags) D0 D0 A0 D1 D2 int recvfrom(int s, void *buf, int len, int flags, D0 D0 A0 D1 D2 struct sockaddr *from, int *fromlen) A1 A2 DESCRIPTION recv() is used to receive messages on an already connect()ed socket. recvfrom() receives data from a socket whether it is in a connected state or not. If no data is available at the socket, the receive call waits for data to arrive, unless the socket is nonblocking (see IoctlSocket()) in which case the value -1 is returned and variable errno is set to EWOULDBLOCK. 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 SO_RCVLOWAT and SO_RCVTIMEO described in setsockopt(). The WaitSelect() call may be used to determine when more data arrive. The flags argument to a recv call is formed by or'ing one or more of the values: MSG_OOB process out-of-band data MSG_PEEK peek at incoming message MSG_WAITALL wait for full request or error The MSG_OOB flag requests receipt of out-of-band data that would not be received in the normal data stream. The MSG_PEEK flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. The MSG_WAITALL flag requests that the operation block until the full request is satisfied. 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. INPUTS s a socket descriptor. buf the buffer into which the incoming data will be placed. len the size of the buffer. flags select options (MSG_OOB, MSG_PEEK). from a pointer to a sockaddr structure. fromlen Length of the 'from' buffer. msg pointer to a struct msghdr, defined in "sys/socket.h." RETURNS These calls return the number of bytes received, or -1 if an error occurred. ERRORS EBADF The argument s is an invalid descriptor. ENOTCONN The socket is assoicated with a connection-oriented protocol and has not been connected (see connect() and accept()). EWOULDBLOCK 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. EINTR The receive was interrupted by delivery of a signal before any data were available. SEE ALSO IoctlSocket(), select(), send(), setsockopt(), socket() ****************************************************************************** send(), sendto() ****************************************************************************** NAME send, sendto -- send a message from a socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int send(int s, const void *buf, int len, int flags) D0 D0 A0 D1 D2 int sendto(int s, const void *buf, int len, int flags, D0 D0 A0 D1 D2 const struct sockaddr * to, int to_len) A1 D3 DESCRIPTION send(), sendto() are used to transmit data to another socket. send() may be used only when the socket is in a connected state, while sendto() and may be used at any time. If no data space is available at the socket to hold the message to be transmitted, then send() normally blocks, unless the socket has been placed in non-blocking I/O mode. Then WaitSelect() may be used to determine when it is possible to send more data. The flags parameter may include one or more of the following: #define MSG_OOB 0x1 /* process out-of-band data */ #define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ The flag MSG_OOB is used to send "out-of-band" data on sockets that support this notion (e.g. SOCK_STREAM); the underlying protocol must also support "out-of-band" data. MSG_DONTROUTE is usually used only by diagnostic or routing programs. INPUTS s socket descriptor. buf pointer to data buffer. len length of data to transmit. flags 0 or MSG_OOB to send out-of-band data. to pointer to a sockaddr containing the destination. to_len sizeof(struct sockaddr). RETURNS The call returns the number of characters sent, or -1 if an error occurred. ERRORS EBADF An invalid descriptor was specified. EMSGSIZE The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. EWOULDBLOCK The socket is marked non-blocking and the requested operation would block. ENOBUFS The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. ENOBUFS 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. SEE ALSO IoctlSocket(), recv(), select(), setsockopt(), socket() ***************************************************************************** SetErrnoPtr() ***************************************************************************** NAME SetErrnoPtr -- set the "global" errno pointer SYNOPSIS void SetErrnoPtr(void * ptr, int size) A0 D0 DESCRIPTION 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. INPUTS ptr pointer to error variable that is to be modified on every error condition on this library function. size size of the error variable. It can be 1, 2 or 4 bytes long. EXAMPLE #include <sys/errno.h> struct Library; struct Library *TSocketBase = NULL; int main(void) { ... if ((TSocketBase = OpenLibrary("tsocket.library", 2)) != NULL) { SetErrnoPtr(&errno, sizeof errno); ... } } **************************************************************************** SetSocketSignals **************************************************************************** NAME SetSocketSignals -- set SIGINTR, SIGIO and SIGURG signals SYNOPSIS void SetSocketSignals(ULONG intrmask, ULONG iomask, ULONG urgmask) D0 D1 D2 DESCRIPTION SetSocketSignals() tells the TermiteTCP which signal masks correspond to the standard UNIX signals SIGINT, SIGIO and SIGURG. 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. 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 or'ed to the intrmask. INPUTS intrmask Used to determine which Amiga signals interrupt blocking library calls. iomask is sent when asynchronous notification of socket event is done 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() function, the owner must be set explicitly with the FIOSETOWN (SIOCSPGRP) 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 or'ed to the intrmask. **************************************************************************** setsockopt **************************************************************************** NAME setsockopt -- set options on sockets SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int setsockopt(int s, int level, D0 D0 D1 int optname, const void *optval, int optlen) D2 A0 D3 DESCRIPTION setsockopt() manipulate the options associated with a socket. To manipulate options at the socket level, level is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP; see getprotobyname(). The include file <sys/socket.h> contains definitions for socket level options, described below. Options at other protocol levels vary in format and name. The following options are recognized at the socket level. SO_DEBUG enables recording of debugging information SO_REUSEADDR enables local address reuse SO_KEEPALIVE enables keep connections alive SO_DONTROUTE enables routing bypass for outgoing messages SO_LINGER linger on close if data present SO_BROADCAST enables permission to transmit broadcast messages SO_OOBINLINE enables reception of out-of-band data in band SO_SNDBUF set buffer size for output SO_RCVBUF set buffer size for input SO_SNDLOWAT set minimum count for output SO_RCVLOWAT set minimum count for input SO_SNDTIMEO set timeout value for output SO_RCVTIMEO set timeout value for input SO_EVENTMASK set event mask to specify which events should be notified to the application INPUTS s socket descriptor. level protocol level. Valid levels are: IPPROTO_IP IP options IPPROTO_TCP TCP options SOL_SOCKET socket options optname option name. optval pointer to the buffer with the new value. optlen size of 'optval' (in bytes). RETURNS 0 on success -1 if it fails. ERRORS EBADF The argument s is not a valid descriptor. ENOPROTOOPT The option is unknown at the level indicated. SEE ALSO IoctlSocket(), socket(), getprotobyname() *************************************************************************** shutdown *************************************************************************** NAME shutdown -- shut down part of a full-duplex connection SYNOPSIS #include <sys/socket.h> int shutdown(int s, int how) D0 D0 D1 DESCRIPTION Sockets are normally terminated by using just CloseSocket. However, this will attempt to deliver any data that is still pending. shutdown() provides more control over how a connection is terminated. You should still eventually use CloseSocket on all sockets you own, regardless of what shutdown() is done on those sockets. INPUTS s socket descriptor. how 'how' can be one of the following: 0 disallow further receives 1 disallow further sends 2 disallow further sends and receives RETURNS 0 if successful -1 on failure (errno will contain the specific error). SEE ALSO CloseSocket(), connect(), socket() **************************************************************************** socket() **************************************************************************** NAME socket - create an endpoint for communication SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int socket(int family, int type, int protocol) D0 D0 D1 D2 DESCRIPTION Socket() creates an endpoint for communication and returns a socket descriptor. Sockets of type SOCK_STREAM are full-duplex byte streams, similar to pipes. A stream socket must be in a connected state before any data may be sent or received on it. A connection to another socket is created with a connect() call. Once connected, data may be transferred using recv() and send() or their variant calls. When a session has been completed a CloseSocket() may be performed. Out-of-band data may also be transmitted as described in send() and received as described in recv(). INPUTS family This specifies an address format with which addresses specified in later operations using socket should be interpreted. TermiteTCP currently supports only AF_INET protocol family. type Specifies the semantics of communication. Currently available types are: SOCK_STREAM provides sequenced, reliable, two-way connection based byte streams. An out-of-band data transmission mechanism may be supported. SOCK_DGRAM supports datagrams(connectionless, unreliable messages of a fixed (typically small) maximum length. SOCK_RAW provide access to internal network protocols and interfaces. Available only to the super-user, protocol Specifies a particular protocol to be used with the socket. RETURN VALUES On success, the return value is a socket descriptor. A -1 is returned if an error occurs, ERRORS EPROTONOSUPPORT The protocol type or the specified protocol is not supported within this domain. EMFILE The per-process descriptor table is full. EACCESS Permission to create a socket of the specified type and/or protocol is denied. ENOBUFS Insufficient buffer space is available. The socket cannot be created until sufficient resources are freed. SEE ALSO accept(), bind(), connect(), CloseSocket(), getprotobyname(), getsockname(), getsockopt(), IoctlSocket(), listen(), recv(), select(), send(), shutdown() "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. **************************************************************************** SocketBaseTagList **************************************************************************** NAME SocketBaseTagList -- Set/Get SocketBase attributes. SYNOPSIS #include <sys/socketbasetags.h> ULONG SocketBaseTagList(struct TagItem * taglist); D0 A0 DESCRIPTION Set or get a list of SocketBase instance dependent attributes INPUTS These functions expect as their argument a standard tag list, one or several arrays of struct TagItem as defined in the standard Amiga header file <utility/tagitem.h>. The structure contains two fields: ti_Tag and ti_Data. The ti_Tag field contains tag code, which determines what the SocketBaseTagList() should do with its argument, the ti_Data field. The include file <sys/socketbasetags.h> 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 SocketBaseTagList() 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 <sys/socketbasetags.h> defines the following macros, which are used to construct the ti_Tag 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 ti_Data field, you should use the 'by value' macros, SBTM_GETVAL() or SBTM_SETVAL(). However, if the ti_Data field contains a pointer to actual data, you should use the 'by reference' macros, SBTM_GETREF() or SBTM_SETREF(). 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. Do not mix the pointer arguments with 'by reference' argument passing. It is possible to pass a pointer by reference (in which case the ti_Data is a pointer to the actual pointer). The list of the currently defined base tag codes is as follows: SBTC_BREAKMASK Tag data contains the INTR signal mask. If the calling task receives a signal in the INTR mask, the TermiteTCP interrupts current function calls and returns with the error code EINTR. The INTR mask defaults to the CTRL-C signal (SIGBREAKF_C,bit 12). SBTC_ERRNO The errno value. The values are defined in <sys/errno.h>. SBTC_ERRNOLONGPTR Set (only) the pointer to the errno variable defined by the program. TermiteTCP defines a value for this by default, but the application must set the pointer with one of these tags, if it wishes to access the errno variable directly. SBTC_ERRNOSTRPTR Returns an error string pointer describing the errno value given on input. This gives extended information about the last error. On call the ti_Data must contain the error code number. On return the ti_Data is assigned to the string pointer. (*ti_Data, if by reference). See the file <sys/errno.h> for symbolic definitions for the errno codes. SBTC_HERRNO The name resolver error code value. Get this to find out why the gethostbyname() or gethostbyaddr() failed. The values are defined in <netdb.h>. SBTC_SIGIOMASK 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. SBTC_SIGURGMASK 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. RESULT Returns 0 on success, and a (positive) index of the failing tag on error. Note that the value 1 means first TagItem, 2 the second one, etc.. **************************************************************************** WaitSelect **************************************************************************** NAME WaitSelect -- Examines specified sockets' read, write or exception with Exec Wait() function. SYNOPSIS #include <sys/types.h> #include <sys/time.h> 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 DESCRIPTION WaitSelect() examines the I/O descriptor sets whose addresses are passed in readfds, writefds, and exceptfds to see if some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending. On return, the given descriptor sets with subsets consisting of those descriptors that are ready for the requested operation. Additionally, WaitSelect() takes a signal mask which is waited during normal select() operation. If one of these singals is received, WaitSelect() returns and has re-set the signal mask to return those signals that have arrived and value 0 is returned. If timeout is a non-nil pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a nil pointer, the select blocks indefinitely. To affect a poll, the timeout argument should be non-nil, pointing to a zero-valued timeval structure. Any of readfds, writefds, and exceptfds may be given as NULL pointers if no descriptors are of interest. Selecting true for reading on a socket descriptor upon which a listen() call has been performed indicates that a subsequent accept() call on that descriptor will not block. If a process is blocked on a select() waiting for input from a socket and the sending process closes the socket, the select notes this as an exception rather than as data. Hence, if the select is not currently looking for exceptions, it will wait forever. The descriptor masks are always modified on return, even if the call returns as the result of the timeout. A common error is to use the socket number in which you are interested as the first argument. Use socket+1. INPUTS numfds Maximum number of bits in the masks that represent valid file descriptors. readfds 32 bit mask representing read file descriptors writefds 32 bit mask representing write file descriptors exceptfds 32 bit mask representing except file descriptors timeout Pointer to a timeval structure which holds the maximum amount of time to wait for the selection to complete. RETURNS The number of ready sockets, zero if a timeout occurred, -1 on error. readfds A mask of the ready socket descriptors writefds A mask of the ready socket descriptors exceptfds A mask of the ready socket descriptors ERRORS An error return from select() indicates: EBADF One of the descriptor sets specified an invalid descriptor. EINTR A signal was delivered before the time limit expired and before any of the selected events occurred. EINVAL The specified time limit is invalid. One of its components is negative or too large. SEE ALSO accept(), connect(), recv(), send()