socketpair()--Create a Pair of Sockets

BSD 4.3 Syntax

  #include <sys/types.h>
  #include <sys/socket.h>

  int socketpair(int address_family,
                 int type,
                 int protocol,
                 int *socket_vector)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

UNIX^® 98 Compatible Syntax

  #define _XOPEN_SOURCE 520
  #include <sys/socket.h>

  int socketpair(int address_family,
                 int type,
                 int protocol,
                 int socket_vector[2])

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

The socketpair() function is used to create a pair of unnamed, connected sockets in the AF_UNIX or AF_UNIX_CCSID address_family.

There are two versions of the API, as shown above. The base IBM^® i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

Parameters

address_family

(Input) The address family to be used with the sockets. Supported values are:

AF_UNIX or AF_UNIX_CCSID

For interprocess communications between processes on the same system in the UNIX domain.

type

(Input) The type of communications desired. Supported values are:

`SOCK_DGRAM`	Indicates a datagram socket is desired.
`SOCK_STREAM`	Indicates a full-duplex stream socket is desired.

protocol: (Input) The protocol to be used on the sockets. Supported values are:

0	Indicates the default protocol for the type selected is to be used.

socket_vector: (Output) An integer array of size two that will contain the socket descriptors.

Authorities

No authorization is required.

Return Value

socketpair() returns an integer. Possible values are:

-1 (unsuccessful)
0 (successful)

Error Conditions

When socketpair() fails, errno can be set to one of the following:

[EAFNOSUPPORT]	The type of socket is not supported in this protocol family.
[EFAULT]	Bad address.
[EINVAL]	Parameter not valid.
[EIO]	Input/output error.
[EMFILE]	Too many descriptions for this process.
[ENFILE]	Too many descriptions in system.
[ENOBUFS]	There is not enough buffer space for the requested operation.
[EOPNOTSUPP]	Operation not supported.
[EPROTONOSUPPORT]	No protocol of the specified type and domain exists.
[ESOCKTNOSUPPORT]	The specified socket type is not supported.
[EUNKNOWN]	Unknown system state.

Error Messages

Message ID	Error Message Text
CPE3418 E	Possible APAR condition or hardware failure.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFA081 E	Unable to set return value or error code.

Usage Notes

The socket address families and types supported by sockets are defined in <sys/socket.h>.
When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the socketpair() API is mapped to qso_socketpair98().
If this function is called by a thread executing one of the scan-related exit programs (or any of its created threads), it will fail with error code [ENOTSUP]. See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for more information.

Related Information

_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
socket()--Create Socket

API introduced: V3R1

[ Back to top | UNIX-Type APIs | APIs by category ]