Debian Codegraph @

upstream/debian-trixie/man2/socketpair.2

raw
1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
2 .\" All rights reserved.
3 .\"
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
5 .\"
6 .\" @(#)socketpair.2 6.4 (Berkeley) 3/10/91
7 .\"
8 .\" Modified 1993-07-24 by Rik Faith <[email protected]>
9 .\" Modified 1996-10-22 by Eric S. Raymond <[email protected]>
10 .\" Modified 2002-07-22 by Michael Kerrisk <[email protected]>
11 .\" Modified 2004-06-17 by Michael Kerrisk <[email protected]>
12 .\" 2008-10-11, mtk: Add description of SOCK_NONBLOCK and SOCK_CLOEXEC
13 .\"
14 .TH socketpair 2 2024-05-02 "Linux man-pages 6.9.1"
15 .SH NAME
16 socketpair \- create a pair of connected sockets
17 .SH LIBRARY
18 Standard C library
19 .RI ( libc ", " \-lc )
20 .SH SYNOPSIS
21 .nf
22 .B #include <sys/socket.h>
23 .P
24 .BI "int socketpair(int " domain ", int " type ", int " protocol \
25 ", int " sv [2]);
26 .fi
27 .SH DESCRIPTION
28 The
29 .BR socketpair ()
30 call creates an unnamed pair of connected sockets in the specified
31 .IR domain ,
32 of the specified
33 .IR type ,
34 and using the optionally specified
35 .IR protocol .
36 For further details of these arguments, see
37 .BR socket (2).
38 .P
39 The file descriptors used in referencing the new sockets are returned in
40 .I sv[0]
41 and
42 .IR sv[1] .
43 The two sockets are indistinguishable.
44 .SH RETURN VALUE
45 On success, zero is returned.
46 On error, \-1 is returned,
47 .I errno
48 is set to indicate the error, and
49 .I sv
50 is left unchanged
51 .P
52 On Linux (and other systems),
53 .BR socketpair ()
54 does not modify
55 .I sv
56 on failure.
57 A requirement standardizing this behavior was added in POSIX.1-2008 TC2.
58 .\" http://austingroupbugs.net/view.php?id=483
59 .SH ERRORS
60 .TP
61 .B EAFNOSUPPORT
62 The specified address family is not supported on this machine.
63 .TP
64 .B EFAULT
65 The address
66 .I sv
67 does not specify a valid part of the process address space.
68 .TP
69 .B EMFILE
70 The per-process limit on the number of open file descriptors has been reached.
71 .TP
72 .B ENFILE
73 The system-wide limit on the total number of open files has been reached.
74 .TP
75 .B EOPNOTSUPP
76 The specified protocol does not support creation of socket pairs.
77 .TP
78 .B EPROTONOSUPPORT
79 The specified protocol is not supported on this machine.
80 .SH VERSIONS
81 On Linux, the only supported domains for this call are
82 .B AF_UNIX
83 (or synonymously,
84 .BR AF_LOCAL )
85 and
86 .B AF_TIPC
87 .\" commit: 70b03759e9ecfae400605fa34f3d7154cccbbba3
88 (since Linux 4.12).
89 .SH STANDARDS
90 POSIX.1-2008.
91 .SH HISTORY
92 POSIX.1-2001, 4.4BSD.
93 .P
94 .BR socketpair ()
95 first appeared in 4.2BSD.
96 It is generally portable to/from
97 non-BSD systems supporting clones of the BSD socket layer (including
98 System\ V variants).
99 .P
100 Since Linux 2.6.27,
101 .BR socketpair ()
102 supports the
103 .B SOCK_NONBLOCK
104 and
105 .B SOCK_CLOEXEC
106 flags in the
107 .I type
108 argument, as described in
109 .BR socket (2).
110 .SH SEE ALSO
111 .BR pipe (2),
112 .BR read (2),
113 .BR socket (2),
114 .BR write (2),
115 .BR socket (7),
116 .BR unix (7)