NAME

socket − create an end point for communication

SYNOPSIS

#include <sys/socket.h> s = socket(type, pf, addr, options);
int s, type;
struct sockproto *pf;
struct sockaddr *addr;
int options;

DESCRIPTION

socket creates a communication end point and returns a descriptor, much like a file descriptor.  The socket has a type that defines the semantics for communication.  Currently defined types are SOCK_STREAM, for sequenced, reliable, two-way, connection-based streams with an out-of-band mechanism; SOCK_DGRAM, for datagrams, connectionless, unreliable messages of a fixed (typically small) maximum length; and SOCK_RAW, for access to internal network interfaces.  SOCK_RAW is only accessible by the super user and is not described here. 

pf causes a specific protocol to be used with the socket.  Currently only one protocol supports each socket type.  pf should be set equal to NULL. 

The addr parameter specifies the socket address.  A socket address is a discriminated union 16 bytes long.  The first two bytes indicate the format of remaining bytes. 

The only variant to this rule is an Internet address (sockaddr_in).  The first field of this variable type is AF_INET (this address is part of the Internet address family), which is defined in <sys/socket.h>. 

The second and third fields are a 16-bit socket number (see <netinet/in.h> for a list of common sockets) and a 32-bit Internet host address, respectively.  The socket number and host address are in network byte order. 

If no socket address is specified, the system assigns one.  It does this at connection time to simplify the routing decisions required of the connected socket.  If the socket number is omitted, a unique socket number is supplied.  The socket numbers 0 through IPPORT_RESERVED−1 are reserved for the super user. 

The procedure rhost(3N) can be used to convert host names to Internet addresses, and raddr(3N) to convert addresses to standard host names. 

Sockets of type SOCK_STREAM are full-duplex byte streams, similar to two-way pipes.  Typically, a stream is created via socket and connected to another socket via a call to connect(3N) or accept(3N).  Then a sequence of read and write calls exchanges data.  Finally, close(2) terminates the connection. 

A typical sequence is

CLIENTSERVER
socket()socket()
connect()accept()
write()read()
read()   write()
   ..
   ..
close()

Out-of-band data may also be transmitted, as described below. 

Sockets of the type SOCK_STREAM ensure that data are 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 (one minute), the connection is considered broken and calls indicate an error with −1 returns.  ETIMEDOUT is 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 flagged if no response can be elicited on an otherwise idle connection for an extended period (five minutes).  A SIGPIPE signal is raised if a process writes on a broken stream.  This causes naive processes, which do not handle the signal, to exit. 

SOCK_DGRAM sockets send datagrams to correspondents named in send(3N) calls.  It is also possible to receive datagrams at such a socket with receive(3N). 

A typical sequence is

SENDERRECEIVER
s=socket()s=socket()
    ..
    ..
send(s)receive(s)
    ..
    ..
receive(s)send(s)

connect can be used with datagram sockets to fix the recipient/sender for future communication.  Once a datagram has been connected, read can be used in place of send, and write can be used in place of receive. 

The subroutine socketaddr(3N) can be used to determine the address of a socket. 

The socket options are OR-ed together in options:

SO_ACCEPTCONN
must be used with SOCK_STREAM sockets that accept connections.  Only sockets that indicate SO_ACCEPTCONN as a creation parameter can accept(3N); such sockets cannot connect(3N). 

SO_DEBUG
enables TCP debugging code, which sends printf messages to the host console that detail protocol events and state transitions. 

SO_DONTLINGER
allows close(2) operations on a socket to finish immediately.  Otherwise, the system blocks a process waiting for data to drain (or return EWOULDBLOCK if the socket is marked NONBLOCKING) when a close is attempted.  See also the SIOCSLINGER ioctl below. 

SO_KEEPALIVE
causes "keep alive" to be used to time-out dead connections. If this option is not specified, timing out dead connections is the responsibility of the user process.

SO_SMALL
causes TCP to use 512-kbyte windows. This option is typically used for low-throughput utilities such as rlogin. 

The following ioctl requests are supported.  Parameter sizes are shown in parentheses. 

FIONREAD (long) returns a byte count of data in a socket’s receive buffer.  The host can use this to determine whether it can read data from the socket without blocking indefinitely. 

FIONBIO (int) enables or disables nonblocking I/O, depending on the value of the parameter.  If 1, then nonblocking I/O is enabled on the socket.  If 0, then it is disabled. 

SIOCDONE (int) shuts down input, output, or both on the designated socket, depending on the value of the parameter. 
 

ValueEffect
 0Shutdown input
1Shutdown output
2Shutdown input and output

An SIOCDONE on input throws away any buffered receive data and causes subsequent read requests to return EOF.  An SIOCDONE on output causes subsequent write requests to return an EPIPE error. 

SIOCSKEEP (int) enables or disables keep-alives on a TCP connection, depending on the value of the parameter.  If 1, keep-alives are enabled on the socket.  If 0, keep-alives are disabled.  SIOCGKEEP returns 1 if keep-alives are enabled, 0 otherwise. 

SIOCSLINGER (int) enables or disables lingering on SOCK_STREAM sockets and establishes how many seconds a connection lingers during closing.  If the parameter is 0xFFFF, a close request blocks indefinitely until all send data are acknowledged.  If 0, then lingering is disabled and a close request resets the connection.  A value between 0 and 32767 establishes a limit (in seconds) on the close request.  If this time expires before the connection closes normally, the connection is reset.  Do not use other values.  SIOCGLINGER returns the effective lingering value, which is interpreted in the same way.  See also the SO_DONTLINGER option, documented above. 

SIOCSENDOOB (char) sends one byte of data on a SOCK_STREAM socket connection.  SIOCRCVOOB returns one byte of out-of-band data. 

SIOCATMARK (int) returns 1 if the host can obtain out-of-band data on the SOCK_STREAM socket with an SIOCRCVOOB request and nonurgent data with a read request.  If it returns 0, the host must issue further read requests to drain urgent data. 

SIOCSPGRP (int) associates a process group ID with a socket.  Subsequent to this request, when out-of-band date arrives on the socket, processes in this group receive a SIGURG signal. 

SEE ALSO

accept(3N), connect(3N), receive(3N), send(3N), socketaddr(3N), inet(7P)

Version 2.4  —  September 29, 2021