SYS_SOCKETPAIR


Creates an unnamed pair of connected sockets.

Arguments:

1st Socket domain. Currently the only supported domain for this call is AF_UNIX (or synonymously, AF_LOCAL).
2nd Communication semantics. Currently defined types are:
SOCK_STREAM Provides sequenced, reliable, two-way, connection-based byte streams. An out-of-band data transmission mechanism may be supported.

Such sockets types are full-duplex byte streams, similar to pipes. They do not preserve record boundaries. 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 SYS_CONNECT call. Once connected, data may be transferred using sys_read and sys_write calls or some variant of the SYS_SEND and SYS_RECV calls. When a session has been completed a sys_close may be performed.

The communications protocols which implement a SOCK_STREAM ensure 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 to be dead. When SO_KEEPALIVE is enabled on the socket the protocol checks in a protocol-specific manner if the other end is still alive. A SIGPIPE signal is raised if a process sends or receives on a broken stream; this causes naive processes, which do not handle the signal, to exit.
SOCK_DGRAM Supports datagrams (connectionless, unreliable messages of a fixed maximum length).
Datagrams are sent to correspondents named in SYS_SENDTO calls. Datagrams are generally received with SYS_RECVFROM, which returns the next datagram along with the address of its sender.
SOCK_RAW Provides raw network protocol access and allows sending of datagrams to correspondents named in SYS_SENDTO calls. Datagrams are generally received with SYS_RECVFROM, which returns the next datagram along with the address of its sender.
SOCK_RDM Provides a reliable datagram layer that does not guarantee ordering.
SOCK_SEQPACKET Provides a sequenced, reliable, two-way connection-based data transmission path for datagrams of fixed maximum length; a consumer is required to read an entire packet with each read system call.

SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM sockets. The only difference is that sys_read calls will return only the amount of data requested, and any data remaining in the arriving packet will be discarded. Also all message boundaries in incoming datagrams are preserved.
SOCK_DCCP *to be documented*
SOCK_PACKET Obsolete and should not be used in new programs; see man 7 packet.
SCOK_PACKET allowed to receive raw packets directly from the device driver.
3rd Protocol to be used with the socket.
Normally only a single protocol exists to support a particular socket type within a given protocol family, in which case this argument can be specified as 0. 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 specific to the "communication domain" in which communication is to take place. See /etc/protocols for a list of available protocols.
4th Pointer to 8 byte long buffer which will receive the two socket descriptors. The two sockets are indistinguishable.

Return values

If the system call succeeds the return value is 0.
If the system call fails the return value is one of the following errno values:

-EAFNOSUPPORT The specified address family is not supported on this machine.
-EFAULT The address pointed by 4th argument does not specify a valid part of the process address space.
-EMFILE Too many descriptors are in use by this process.
-ENFILE The system limit on the total number of open files has been reached.
-EOPNOTSUPP The specified protocol does not support creation of socket pairs.
-EPROTONOSUPPORT The specified protocol is not supported on this machine.

Remarks

n/a

Compatibility

n/a