socketpair Subroutine

Purpose

Creates a pair of connected sockets.

Library

Standard C Library (libc.a)

Syntax

#include <sys/socket.h>
int socketpair (Domain, Type, Protocol, SocketVector[0])
int  Domain,  Type,  Protocol;
int  SocketVector[2];

Description

The socketpair subroutine creates an unnamed pair of connected sockets in a specified domain, of a specified type, and using the optionally specified protocol. The two sockets are identical.

Note: Create sockets with this subroutine only in the AF_UNIX protocol family.

The descriptors used in referencing the new sockets are returned in the SocketVector[0] and SocketVector[1] parameters.

The /usr/include/sys/socket.h file contains the definitions for socket domains, types, and protocols.

All applications containing the socketpair subroutine must be compiled with the _BSD macro set to a value of 43 or 44. Socket applications must include the BSD libbsd.a library.

Parameters

Item Description
Domain Specifies the communications domain within which the sockets are created. This subroutine does not create sockets in the Internet domain.
Type Specifies the communications method, whether SOCK_DGRAM or SOCK_STREAM, that the socket uses.
Protocol Points to an optional identifier used to specify which standard set of rules (such as UDP/IP and TCP/IP) governs the transfer of data.
SocketVector Points to a two-element vector that contains the integer descriptors of a pair of created sockets.

Return Values

Upon successful completion, the socketpair subroutine returns a value of 0.

If the socketpair subroutine is unsuccessful, the subroutine handler performs the following functions:

  • Returns a value of -1 to the calling program.
  • Moves an error code, indicating the specific error, into the errno global variable.

Error Codes

If the socketpair subroutine is unsuccessful, it returns one of the following errors codes:

Error Description
EAFNOSUPPORT The addresses in the specified address family cannot be used with this socket.
EFAULT The SocketVector parameter is not in a writable part of the user address space.
EMFILE This process has too many descriptors in use.
ENFILE The maximum number of files allowed are currently open.
ENOBUFS Insufficient resources were available in the system to perform the operation.
EOPNOTSUPP The specified protocol does not allow the creation of socket pairs.
EPROTONOSUPPORT The specified protocol cannot be used on this system.
EPROTOTYPE The socket type is not supported by the protocol.