lib/libc/sys/pipe.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd December 1, 2017
  29 .Dt PIPE 2
  30 .Os
  31 .Sh NAME
  32 .Nm pipe ,
  33 .Nm pipe2
  34 .Nd create descriptor pair for interprocess communication
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In unistd.h
  39 .Ft int
  40 .Fn pipe "int fildes[2]"
  41 .Ft int
  42 .Fn pipe2 "int fildes[2]" "int flags"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn pipe
  46 function
  47 creates a
  48 .Em pipe ,
  49 which is an object allowing
  50 bidirectional data flow,
  51 and allocates a pair of file descriptors.
  52 .Pp
  53 The
  54 .Fn pipe2
  55 system call allows control over the attributes of the file descriptors
  56 via the
  57 .Fa flags
  58 argument.
  59 Values for
  60 .Fa flags
  61 are constructed by a bitwise-inclusive OR of flags from the following
  62 list, defined in
  63 .In fcntl.h :
  64 .Bl -tag -width ".Dv O_NONBLOCK"
  65 .It Dv O_CLOEXEC
  66 Set the close-on-exec flag for the new file descriptors.
  67 .It Dv O_NONBLOCK
  68 Set the non-blocking flag for the ends of the pipe.
  69 .El
  70 .Pp
  71 If the
  72 .Fa flags
  73 argument is 0, the behavior is identical to a call to
  74 .Fn pipe .
  75 .Pp
  76 By convention, the first descriptor is normally used as the
  77 .Em read end
  78 of the pipe,
  79 and the second is normally the
  80 .Em write end ,
  81 so that data written to
  82 .Fa fildes[1]
  83 appears on (i.e., can be read from)
  84 .Fa fildes[0] .
  85 This allows the output of one program to be
  86 sent
  87 to another program:
  88 the source's standard output is set up to be
  89 the write end of the pipe,
  90 and the sink's standard input is set up to be
  91 the read end of the pipe.
  92 The pipe itself persists until all its associated descriptors are
  93 closed.
  94 .Pp
  95 A pipe that has had an end closed is considered
  96 .Em widowed .
  97 Writing on such a pipe causes the writing process to receive
  98 a
  99 .Dv SIGPIPE
 100 signal.
 101 Widowing a pipe is the only way to deliver end-of-file to a reader:
 102 after the reader consumes any buffered data, reading a widowed pipe
 103 returns a zero count.
 104 .Pp
 105 The bidirectional nature of this implementation of pipes is not
 106 portable to older systems, so it is recommended to use the convention
 107 for using the endpoints in the traditional manner when using a
 108 pipe in one direction.
 109 .Sh IMPLEMENTATION NOTES
 110 The
 111 .Fn pipe
 112 function calls the
 113 .Fn pipe2
 114 system call.
 115 As a result, system call traces such as those captured by
 116 .Xr dtrace 1
 117 or
 118 .Xr ktrace 1
 119 will show calls to
 120 .Fn pipe2 .
 121 .Sh RETURN VALUES
 122 .Rv -std pipe
 123 .Sh ERRORS
 124 The
 125 .Fn pipe
 126 and
 127 .Fn pipe2
 128 system calls will fail if:
 129 .Bl -tag -width Er
 130 .It Bq Er EFAULT
 131 .Ar fildes
 132 argument points to an invalid memory location.
 133 .It Bq Er EMFILE
 134 Too many descriptors are active.
 135 .It Bq Er ENFILE
 136 The system file table is full.
 137 .It Bq Er ENOMEM
 138 Not enough kernel memory to establish a pipe.
 139 .El
 140 .Pp
 141 The
 142 .Fn pipe2
 143 system call will also fail if:
 144 .Bl -tag -width Er
 145 .It Bq Er EINVAL
 146 The
 147 .Fa flags
 148 argument is invalid.
 149 .El
 150 .Sh SEE ALSO
 151 .Xr sh 1 ,
 152 .Xr fork 2 ,
 153 .Xr read 2 ,
 154 .Xr socketpair 2 ,
 155 .Xr write 2
 156 .Sh HISTORY
 157 The
 158 .Fn pipe
 159 function appeared in
 160 .At v3 .
 161 .Pp
 162 Bidirectional pipes were first used on
 163 .At V.4 .
 164 .Pp
 165 The
 166 .Fn pipe2
 167 function appeared in
 168 .Fx 10.0 .
 169 .Pp
 170 The
 171 .Fn pipe
 172 function became a wrapper around
 173 .Fn pipe2
 174 in
 175 .Fx 11.0 .