|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH SOCKETPAIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
socketpair
|
|
Packit |
7cfc04 |
\(em create a pair of connected sockets
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
#include <sys/socket.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
int socketpair(int \fIdomain\fP, int \fItype\fP, int \fIprotocol\fP,
|
|
Packit |
7cfc04 |
int \fIsocket_vector\fP[2]);
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIsocketpair\fR()
|
|
Packit |
7cfc04 |
function shall create an unbound pair of connected sockets in a
|
|
Packit |
7cfc04 |
specified
|
|
Packit |
7cfc04 |
.IR domain ,
|
|
Packit |
7cfc04 |
of a specified
|
|
Packit |
7cfc04 |
.IR type ,
|
|
Packit |
7cfc04 |
under the protocol optionally specified by the
|
|
Packit |
7cfc04 |
.IR protocol
|
|
Packit |
7cfc04 |
argument. The two sockets shall be identical. The file descriptors
|
|
Packit |
7cfc04 |
used in referencing the created sockets shall be returned in
|
|
Packit |
7cfc04 |
.IR socket_vector [0]
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.IR socket_vector [1].
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIsocketpair\fR()
|
|
Packit |
7cfc04 |
function takes the following arguments:
|
|
Packit |
7cfc04 |
.IP "\fIdomain\fR" 12
|
|
Packit |
7cfc04 |
Specifies the communications domain in which the sockets are to be
|
|
Packit |
7cfc04 |
created.
|
|
Packit |
7cfc04 |
.IP "\fItype\fR" 12
|
|
Packit |
7cfc04 |
Specifies the type of sockets to be created.
|
|
Packit |
7cfc04 |
.IP "\fIprotocol\fR" 12
|
|
Packit |
7cfc04 |
Specifies a particular protocol to be used with the sockets.
|
|
Packit |
7cfc04 |
Specifying a
|
|
Packit |
7cfc04 |
.IR protocol
|
|
Packit |
7cfc04 |
of 0 causes
|
|
Packit |
7cfc04 |
\fIsocketpair\fR()
|
|
Packit |
7cfc04 |
to use an unspecified default protocol appropriate for the requested
|
|
Packit |
7cfc04 |
socket type.
|
|
Packit |
7cfc04 |
.IP "\fIsocket_vector\fR" 12
|
|
Packit |
7cfc04 |
Specifies a 2-integer array to hold the file descriptors of the created
|
|
Packit |
7cfc04 |
socket pair.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR type
|
|
Packit |
7cfc04 |
argument specifies the socket type, which determines the semantics of
|
|
Packit |
7cfc04 |
communications over the socket. The following socket types are defined;
|
|
Packit |
7cfc04 |
implementations may specify additional socket types:
|
|
Packit |
7cfc04 |
.IP SOCK_STREAM 14
|
|
Packit |
7cfc04 |
Provides sequenced, reliable, bidirectional, connection-mode byte
|
|
Packit |
7cfc04 |
streams, and may provide a transmission mechanism for out-of-band
|
|
Packit |
7cfc04 |
data.
|
|
Packit |
7cfc04 |
.IP SOCK_DGRAM 14
|
|
Packit |
7cfc04 |
Provides datagrams, which are connectionless-mode, unreliable messages
|
|
Packit |
7cfc04 |
of fixed maximum length.
|
|
Packit |
7cfc04 |
.IP SOCK_SEQPACKET 14
|
|
Packit |
7cfc04 |
Provides sequenced, reliable, bidirectional, connection-mode
|
|
Packit |
7cfc04 |
transmission paths for records. A record can be sent using one or more
|
|
Packit |
7cfc04 |
output operations and received using one or more input operations, but
|
|
Packit |
7cfc04 |
a single operation never transfers part of more than one record. Record
|
|
Packit |
7cfc04 |
boundaries are visible to the receiver via the MSG_EOR flag.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the
|
|
Packit |
7cfc04 |
.IR protocol
|
|
Packit |
7cfc04 |
argument is non-zero, it shall specify a protocol that is supported by
|
|
Packit |
7cfc04 |
the address family. If the
|
|
Packit |
7cfc04 |
.IR protocol
|
|
Packit |
7cfc04 |
argument is zero, the default protocol for this address family and type
|
|
Packit |
7cfc04 |
shall be used. The protocols supported by the system are
|
|
Packit |
7cfc04 |
implementation-defined.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The process may need to have appropriate privileges to use the
|
|
Packit |
7cfc04 |
\fIsocketpair\fR()
|
|
Packit |
7cfc04 |
function or to create some sockets.
|
|
Packit |
7cfc04 |
.SH "RETURN VALUE"
|
|
Packit |
7cfc04 |
Upon successful completion, this function shall return 0; otherwise,
|
|
Packit |
7cfc04 |
\(mi1 shall be returned and
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
set to indicate the error.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIsocketpair\fR()
|
|
Packit |
7cfc04 |
function shall fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EAFNOSUPPORT
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
The implementation does not support the specified address family.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EMFILE
|
|
Packit |
7cfc04 |
All, or all but one, of the file descriptors available to the
|
|
Packit |
7cfc04 |
process are currently open.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENFILE
|
|
Packit |
7cfc04 |
No more file descriptors are available for the system.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EOPNOTSUPP
|
|
Packit |
7cfc04 |
The specified protocol does not permit creation of socket pairs.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EPROTONOSUPPORT
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
The protocol is not supported by the address family, or the protocol is
|
|
Packit |
7cfc04 |
not supported by the implementation.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EPROTOTYPE
|
|
Packit |
7cfc04 |
The socket type is not supported by the protocol.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIsocketpair\fR()
|
|
Packit |
7cfc04 |
function may fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EACCES
|
|
Packit |
7cfc04 |
The process does not have appropriate privileges.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENOBUFS
|
|
Packit |
7cfc04 |
Insufficient resources were available in the system to perform the
|
|
Packit |
7cfc04 |
operation.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENOMEM
|
|
Packit |
7cfc04 |
Insufficient memory was available to fulfill the request.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH "EXAMPLES"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
The documentation for specific address families specifies which
|
|
Packit |
7cfc04 |
protocols each address family supports. The documentation for specific
|
|
Packit |
7cfc04 |
protocols specifies which socket types each protocol supports.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIsocketpair\fR()
|
|
Packit |
7cfc04 |
function is used primarily with UNIX domain sockets and need not be
|
|
Packit |
7cfc04 |
supported for other domains.
|
|
Packit |
7cfc04 |
.SH "RATIONALE"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "\fIsocket\fR\^(\|)"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "\fB<sys_socket.h>\fP"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|