socket(SSC) 6 January 1993 socket(SSC) Name socket - create an endpoint for communication Syntax #include <sys/types.h> #include <sys/socket.h> s = socket(domain, type, protocol) int s, domain, type, protocol; Description socket creates an endpoint for communication and returns a descriptor. s is a file descriptor returned by the socket system call. The domain parameter specifies a communications domain within which com- munication will take place; this selects the protocol family which should be used. The protocol family generally is the same as the address family for the addresses supplied in later operations on the socket. These fam- ilies are defined in the include file <sys/socket.h>. The only currently supported format is AFINET (Internet protocols). The socket has the indicated type, which specifies the semantics of com- munication. Currently defined types include: SOCKSTREAM SOCKDGRAM SOCKRAW Note that not all types are supported by all protocol families. A SOCKSTREAM type provides sequenced, reliable, two-way connection-based byte streams with an out-of-band data transmission mechanism. A SOCKDGRAM socket supports datagrams (connectionless, unreliable messages of a fixed maximum length). SOCKRAW sockets provide access to internal network protocols and inter- faces. This type is available only to the super-user. The protocol 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 speci- fied in this manner. The protocol number to use is particular to the ``communication domain'' in which communication is to take place; see protocols(SFF). Sockets of type SOCKSTREAM 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(SSC) call. Once connected, data may be transferred using read(S) and write(S) calls or some variant of the send(SSC) and recv(SSC) calls. When a session has been completed, a close(S) may be performed. Out-of-band data may also be transmitted as described in send(SSC) and received as described in recv(SSC). The communications protocols used to implement a SOCKSTREAM 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, the connection is considered broken and calls will indicate 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 eli- cited on an otherwise idle connection for a extended period (for example, 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. SOCKDGRAM and SOCKRAW sockets allow sending of datagrams to corre- spondents named in send(SSC) calls. Datagrams are generally received with recv(SSC), which returns the next datagram with its return address. An ioctl(S) call can be used to specify a process group to receive a SIGURG (SIGUSR1) signal when the out-of-band data arrives. It may also enable non-blocking I/O and asynchronous notification of I/IO events with SIGIO (SIGPOLL) signals. The operation of sockets is controlled by socket level options. These options are defined in the file <sys/socket.h>. setsockopt and get- sockopt are used to set and get options, respectively. See getsockopt(SSC) for more information. The following options are recog- nized at the socket level: SODEBUG toggle recording of debugging information SOREUSEADDR toggle local address reuse SOKEEPALIVE toggle keep connections alive SODONTROUTE toggle routing bypass for outgoing messages SOLINGER linger on close if data present SOBROADCAST toggle permission to transmit broadcast messages SOOOBINLINE toggle reception of out-of-band data in band SOSNDBUF set buffer size for output - not currently supported SORCVBUF set buffer size for input - not currently supported SOTYPE get the type of the socket (get only) SOERROR get and clear error on the socket (get only) SOPROTOTYPE get/set the protocol number associated with the stream SODEBUG enables debugging in the underlying protocol modules. SOREUSEADDR indicates that the rules used in validating addresses sup- plied in a bind(SSC) call should allow reuse of local addresses. SOKEEPALIVE enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified via a SIGPIPE signal. SODONTROUTE 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. SOLINGER controls the action taken when unsent messages are queued on socket and a close(S) is performed. If the socket promises reliable delivery of data and SOLINGER is set, the system will block the process on the close attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in the setsockopt call when SOLINGER is requested). If SOLINGER is disabled and a close is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. SOBROADCAST 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, SOOOBINLINE requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with recv or read calls without the MSGOOB flag. SOSNDBUF and SORCVBUF 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 abso- lute limit on these values. SOTYPE and SOERROR are options used only with setsockopt. SOTYPE returns the type of the socket, such as SOCKSTREAM; it is useful for servers that inherit sockets on startup. SOERROR 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 asyn- chronous errors. SOPROTOTYPE binds a protocol number to the socket. This option is necessary to support raw IP sockets (for example) and, as such, is used primarily by the BSD compatibility module. 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: [EPROTONOSUPPORT] The protocol type or the specified protocol is not supported within this communication domain. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. [EACCESS] Permission to create a socket of the specified type and/or protocol is denied. [ENOSR] Insufficient buffer space is available. The socket cannot be created until sufficient resources are freed. See also Intro(SSC), accept(SSC), bind(SSC), connect(SSC), getsockname(SSC), getsockopt(SSC), ioctl(S), listen(SSC), read(S), recv(SSC), select(S), send(SSC), shutdown(SSC), write(S), inet(ADMP) and intro(ADMP).