NAME

       socketpair - create a pair of connected sockets

SYNOPSIS

       #include <sys/socket.h>

       int socketpair(int domain, int type, int protocol,
              int socket_vector[2]);

DESCRIPTION

       The socketpair() function shall create an unbound pair of connected sockets in a specified
       domain, of a specified type, under the  protocol  optionally  specified  by  the  protocol
       argument. The two sockets shall be identical. The file descriptors used in referencing the
       created sockets shall be returned in socket_vector[0] and socket_vector[1].

       The socketpair() function takes the following arguments:

       domain Specifies the communications domain in which the sockets are to be created.

       type   Specifies the type of sockets to be created.

       protocol
              Specifies a particular protocol to be used with the sockets. Specifying a  protocol
              of 0 causes socketpair() to use an unspecified default protocol appropriate for the
              requested socket type.

       socket_vector
              Specifies a 2-integer array to hold the file  descriptors  of  the  created  socket
              pair.

       The   type  argument  specifies  the  socket  type,  which  determines  the  semantics  of
       communications over the socket. The following socket types  are  defined;  implementations
       may specify additional socket types:

       SOCK_STREAM
              Provides  sequenced, reliable, bidirectional, connection-mode byte streams, and may
              provide a transmission mechanism for out-of-band data.

       SOCK_DGRAM
              Provides datagrams, which are connectionless-mode,  unreliable  messages  of  fixed
              maximum length.

       SOCK_SEQPACKET
              Provides sequenced, reliable, bidirectional, connection-mode transmission paths for
              records. A record can be sent using one or  more  output  operations  and  received
              using  one or more input operations, but a single operation never transfers part of
              more than one record. Record boundaries are visible to the receiver via the MSG_EOR
              flag.

       If the protocol argument is non-zero, it shall specify a protocol that is supported by the
       address family. If the protocol argument is zero, the default protocol  for  this  address
       family  and  type shall be used. The protocols supported by the system are implementation-
       defined.

       The process may need to have appropriate privileges to use the socketpair() function or to
       create some sockets.

RETURN VALUE

       Upon  successful completion, this function shall return 0; otherwise, -1 shall be returned
       and errno set to indicate the error.

ERRORS

       The socketpair() function shall fail if:

       EAFNOSUPPORT

              The implementation does not support the specified address family.

       EMFILE No more file descriptors are available for this process.

       ENFILE No more file descriptors are available for the system.

       EOPNOTSUPP
              The specified protocol does not permit creation of socket pairs.

       EPROTONOSUPPORT

              The protocol is not supported by  the  address  family,  or  the  protocol  is  not
              supported by the implementation.

       EPROTOTYPE
              The socket type is not supported by the protocol.

       The socketpair() function may fail if:

       EACCES The process does not have appropriate privileges.

       ENOBUFS
              Insufficient resources were available in the system to perform the operation.

       ENOMEM Insufficient memory was available to fulfill the request.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The  documentation  for  specific  address families specifies which protocols each address
       family supports. The documentation for specific protocols  specifies  which  socket  types
       each protocol supports.

       The  socketpair()  function  is  used  primarily  with UNIX domain sockets and need not be
       supported for other domains.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       socket() , the Base Definitions volume of IEEE Std 1003.1-2001, <sys/socket.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .