Technical Reference: Communications, Volume 2

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.

Parameters

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:

EMFILE	This process has too many descriptors in use.
EAFNOSUPPORT	The addresses in the specified address family cannot be used with this socket.
EPROTONOSUPPORT	The specified protocol cannot be used on this system.
EOPNOTSUPP	The specified protocol does not allow the creation of socket pairs.
EFAULT	The SocketVector parameter is not in a writable part of the user address space.

Implementation Specifics

The socketpair subroutine is part of Base Operating System (BOS) Runtime.

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

Related Information

The socket subroutine.

Socketpair Communication Example Program, Sockets Overview, and Understanding Socket Creation in AIX 5L Version 5.1 Communications Programming Concepts.