mirror of https://github.com/mkerrisk/man-pages
153 lines
4.8 KiB
Plaintext
153 lines
4.8 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "SOCKETPAIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" socketpair
|
|
.SH NAME
|
|
socketpair \- create a pair of connected sockets
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <sys/socket.h>
|
|
.br
|
|
.sp
|
|
int socketpair(int\fP \fIdomain\fP\fB, int\fP \fItype\fP\fB, int\fP
|
|
\fIprotocol\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ int\fP \fIsocket_vector\fP\fB[2]);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIsocketpair\fP() function shall create an unbound pair of connected
|
|
sockets in a specified \fIdomain\fP, of a specified
|
|
\fItype\fP, under the protocol optionally specified by the \fIprotocol\fP
|
|
argument. The two sockets shall be identical. The file
|
|
descriptors used in referencing the created sockets shall be returned
|
|
in \fIsocket_vector\fP[0] and \fIsocket_vector\fP[1].
|
|
.LP
|
|
The \fIsocketpair\fP() function takes the following arguments:
|
|
.TP 7
|
|
\fIdomain\fP
|
|
Specifies the communications domain in which the sockets are to be
|
|
created.
|
|
.TP 7
|
|
\fItype\fP
|
|
Specifies the type of sockets to be created.
|
|
.TP 7
|
|
\fIprotocol\fP
|
|
Specifies a particular protocol to be used with the sockets. Specifying
|
|
a \fIprotocol\fP of 0 causes \fIsocketpair\fP() to
|
|
use an unspecified default protocol appropriate for the requested
|
|
socket type.
|
|
.TP 7
|
|
\fIsocket_vector\fP
|
|
Specifies a 2-integer array to hold the file descriptors of the created
|
|
socket pair.
|
|
.sp
|
|
.LP
|
|
The \fItype\fP 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:
|
|
.TP 7
|
|
SOCK_STREAM
|
|
Provides sequenced, reliable, bidirectional, connection-mode byte
|
|
streams, and may provide a transmission mechanism for
|
|
out-of-band data.
|
|
.TP 7
|
|
SOCK_DGRAM
|
|
Provides datagrams, which are connectionless-mode, unreliable messages
|
|
of fixed maximum length.
|
|
.TP 7
|
|
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.
|
|
.sp
|
|
.LP
|
|
If the \fIprotocol\fP argument is non-zero, it shall specify a protocol
|
|
that is supported by the address family. If the
|
|
\fIprotocol\fP argument is zero, the default protocol for this address
|
|
family and type shall be used. The protocols supported by
|
|
the system are implementation-defined.
|
|
.LP
|
|
The process may need to have appropriate privileges to use the \fIsocketpair\fP()
|
|
function or to create some sockets.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, this function shall return 0; otherwise,
|
|
-1 shall be returned and \fIerrno\fP set to indicate the
|
|
error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIsocketpair\fP() function shall fail if:
|
|
.TP 7
|
|
.B EAFNOSUPPORT
|
|
.sp
|
|
The implementation does not support the specified address family.
|
|
.TP 7
|
|
.B EMFILE
|
|
No more file descriptors are available for this process.
|
|
.TP 7
|
|
.B ENFILE
|
|
No more file descriptors are available for the system.
|
|
.TP 7
|
|
.B EOPNOTSUPP
|
|
The specified protocol does not permit creation of socket pairs.
|
|
.TP 7
|
|
.B EPROTONOSUPPORT
|
|
.sp
|
|
The protocol is not supported by the address family, or the protocol
|
|
is not supported by the implementation.
|
|
.TP 7
|
|
.B EPROTOTYPE
|
|
The socket type is not supported by the protocol.
|
|
.sp
|
|
.LP
|
|
The \fIsocketpair\fP() function may fail if:
|
|
.TP 7
|
|
.B EACCES
|
|
The process does not have appropriate privileges.
|
|
.TP 7
|
|
.B ENOBUFS
|
|
Insufficient resources were available in the system to perform the
|
|
operation.
|
|
.TP 7
|
|
.B ENOMEM
|
|
Insufficient memory was available to fulfill the request.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
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.
|
|
.LP
|
|
The \fIsocketpair\fP() function is used primarily with UNIX domain
|
|
sockets and need not be supported for other domains.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIsocket\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<sys/socket.h>\fP
|
|
.SH 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 .
|