socket(2N) socket(2N)NAME socket - create an endpoint for communication SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int socket(af, type, protocol) int af, type, protocol; DESCRIPTION socket creates an endpoint for communication and returns a descriptor. The af parameter specifies an address format with which ad- dresses specified in later operations using the socket should be interpreted. These formats are defined in the in- clude file <sys/socket.h>. The currently understood formats are: AF_UNIX (UNIX path names) AF_INET (ARPA Internet addresses) AF_PUP (Xerox PUP-I Internet addresses) AF_IMPLINK (IMP ``host at IMP'' addresses) Note: The only address format currently supported on this implementation is AF_INET. The socket has the indicated type which specifies the seman- tics of communication. Currently defined types are: SOCK_STREAM SOCK_DGRAM SOCK_RAW SOCK_SEQPACKET SOCK_RDM A SOCK_STREAM type provides sequenced, reliable, two-way connection based byte streams with an out-of-band data transmission mechanism. A SOCK_DGRAM socket supports da- tagrams (connectionless, unreliable messages of a fixed (typically small) maximum length). SOCK_RAW sockets provide access to internal network interfaces. The types SOCK_RAW, which is available only to the superuser, and SOCK_SEQPACKET and SOCK_RDM, which are planned, but not yet implemented, are not described here. The protocol specifies a particular protocol to be used with the socket. Normally only a single protocol exists to sup- port a particular socket type using a given address format. However, it is possible that many protocols may exist in April, 1990 1
socket(2N) socket(2N)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; see services(4N) and protocols(4N). 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 con- nection to another socket is created with a connect(2N) call. Once connected, data may be transferred using read(2) and write(2) calls or some variant of the send(2N) and recv(2N) calls. When a session has been completed a close(2) may be performed. Out-of-band data may also be transmitted as described in send(2N) and received as described in recv(2N). The communications protocols used to implement a SOCK_STREAM 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 in- dicate an error with -1 returns and with ETIMEDOUT as the specific code in the global variable 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). A SIGPIPE signal is raised if a process sends on a broken stream; this causes naive processes, which do not handle the signal, to exit. SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to correspondents named in send(2N) calls. It is also pos- sible to receive datagrams at such a socket with recv(2N). An fcntl(2) call can be used to specify a process group to receive a SIGURG signal when the out-of-band data arrives. The operation of sockets is controlled by socket level op- tions. These options are defined in the file <sys/socket.h> and explained below. setsockopt and getsockopt(2N) are used to set and get options, respectively. SO_DEBUG turn on recording of debugging information SO_REUSEADDR allow local address reuse SO_KEEPALIVE keep connections alive SO_DONTROUTE do no apply routing on outgoing messages SO_LINGER 2 April, 1990
socket(2N) socket(2N)linger on close if data present SO_DONTLINGER do not linger on close SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind(2N) call should al- low reuse of local addresses. SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these mes- sages, the connection is considered broken and processes us- ing the socket are notified via a SIGPIPE signal. SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. SO_LINGER and SO_DONTLINGER control the actions taken when unsent mes- sages are queued on socket and a close(2) is performed. If the socket promises reliable delivery of data and SO_LINGER is set, the system will block the process on the close at- tempt until it is able to transmit the data or until it de- cides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in the set- sockopt call when SO_LINGER is requested). If SO_DONTLINGER is specified and a close is issued, the system will process the close in a manner which allows the process to continue as quickly as possible. RETURN VALUE A -1 is returned if an error occurs, otherwise the return value is a descriptor referencing the socket. ERRORS The socket call fails if: [EAFNOSUPPORT] The specified address family is not supported in this version of the system. [ESOCKTNOSUPPORT] The specified socket type is not supported in this address family. [EPROTONOSUPPORT] The specified protocol is not sup- ported. [EMFILE] The per-process descriptor table is full. [ENOBUFS] No buffer space is available. The socket cannot be created. April, 1990 3
socket(2N) socket(2N)SEE ALSO accept(2N), bind(2N), connect(2N), getsockname(2N), getsockopt(2N), ioctl(2), listen(2N), recv(2N), select(2N), send(2N), shutdown(2N). BUGS The use of keepalives is a questionable feature for this layer. 4 April, 1990