| .\" Copyright (c) 1983, 1991 The Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)socketpair.2 6.4 (Berkeley) 3/10/91 |
| .\" |
| .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified 2002-07-22 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" 2008-10-11, mtk: Add description of SOCK_NONBLOCK and SOCK_CLOEXEC |
| .\" |
| .TH SOCKETPAIR 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| socketpair \- create a pair of connected sockets |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/socket.h> |
| .PP |
| .BI "int socketpair(int " domain ", int " type ", int " protocol \ |
| ", int " sv [2]); |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR socketpair () |
| call creates an unnamed pair of connected sockets in the specified |
| .IR domain , |
| of the specified |
| .IR type , |
| and using the optionally specified |
| .IR protocol . |
| For further details of these arguments, see |
| .BR socket (2). |
| .PP |
| The file descriptors used in referencing the new sockets are returned in |
| .I sv[0] |
| and |
| .IR sv[1] . |
| The two sockets are indistinguishable. |
| .SH RETURN VALUE |
| On success, zero is returned. |
| On error, \-1 is returned, |
| .I errno |
| is set to indicate the error, and |
| .I sv |
| is left unchanged |
| .PP |
| On Linux (and other systems), |
| .BR socketpair () |
| does not modify |
| .I sv |
| on failure. |
| A requirement standardizing this behavior was added in POSIX.1-2008 TC2. |
| .\" http://austingroupbugs.net/view.php?id=483 |
| .SH ERRORS |
| .TP |
| .B EAFNOSUPPORT |
| The specified address family is not supported on this machine. |
| .TP |
| .B EFAULT |
| The address |
| .I sv |
| does not specify a valid part of the process address space. |
| .TP |
| .B EMFILE |
| The per-process limit on the number of open file descriptors has been reached. |
| .TP |
| .B ENFILE |
| The system-wide limit on the total number of open files has been reached. |
| .TP |
| .B EOPNOTSUPP |
| The specified protocol does not support creation of socket pairs. |
| .TP |
| .B EPROTONOSUPPORT |
| The specified protocol is not supported on this machine. |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, 4.4BSD. |
| .BR socketpair () |
| first appeared in 4.2BSD. |
| It is generally portable to/from |
| non-BSD systems supporting clones of the BSD socket layer (including |
| System\ V variants). |
| .SH NOTES |
| On Linux, the only supported domains for this call are |
| .B AF_UNIX |
| (or synonymously, |
| .BR AF_LOCAL ) |
| and |
| .B AF_TIPC |
| .\" commit: 70b03759e9ecfae400605fa34f3d7154cccbbba3 |
| (since Linux 4.12). |
| .PP |
| Since Linux 2.6.27, |
| .BR socketpair () |
| supports the |
| .BR SOCK_NONBLOCK |
| and |
| .BR SOCK_CLOEXEC |
| flags in the |
| .I type |
| argument, as described in |
| .BR socket (2). |
| .SH SEE ALSO |
| .BR pipe (2), |
| .BR read (2), |
| .BR socket (2), |
| .BR write (2), |
| .BR socket (7), |
| .BR unix (7) |