man2/socketpair.2

   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 <faith@cs.unc.edu>
   9 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
  10 .\" Modified 2002-07-22 by Michael Kerrisk <mtk.manpages@gmail.com>
  11 .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
  12 .\" 2008-10-11, mtk: Add description of SOCK_NONBLOCK and SOCK_CLOEXEC
  13 .\"
  14 .TH SOCKETPAIR 2 2021-03-22 "Linux man-pages (unreleased)"
  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 .PP
  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 .PP
  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 .PP
  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 STANDARDS
  81 POSIX.1-2001, POSIX.1-2008, 4.4BSD.
  82 .BR socketpair ()
  83 first appeared in 4.2BSD.
  84 It is generally portable to/from
  85 non-BSD systems supporting clones of the BSD socket layer (including
  86 System\ V variants).
  87 .SH NOTES
  88 On Linux, the only supported domains for this call are
  89 .B AF_UNIX
  90 (or synonymously,
  91 .BR AF_LOCAL )
  92 and
  93 .B AF_TIPC
  94 .\" commit: 70b03759e9ecfae400605fa34f3d7154cccbbba3
  95 (since Linux 4.12).
  96 .PP
  97 Since Linux 2.6.27,
  98 .BR socketpair ()
  99 supports the
 100 .B SOCK_NONBLOCK
 101 and
 102 .B SOCK_CLOEXEC
 103 flags in the
 104 .I type
 105 argument, as described in
 106 .BR socket (2).
 107 .SH SEE ALSO
 108 .BR pipe (2),
 109 .BR read (2),
 110 .BR socket (2),
 111 .BR write (2),
 112 .BR socket (7),
 113 .BR unix (7)