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.