man/man2/pipe.2

   1 .\" Copyright (c) 1980 Regents of the University of California.
   2 .\" All rights reserved.  The Berkeley software License Agreement
   3 .\" specifies the terms and conditions for redistribution.
   4 .\"
   5 .\"     @(#)pipe.2      6.2 (Berkeley) 8/26/85
   6 .\"
   7 .TH PIPE 2 "August 26, 1985"
   8 .UC 4
   9 .SH NAME
  10 pipe \- create an interprocess communication channel
  11 .SH SYNOPSIS
  12 .nf
  13 .ft B
  14 #include <unistd.h>
  15
  16 int pipe(int \fIfildes\fP[2])
  17 .fi
  18 .ft R
  19 .SH DESCRIPTION
  20 The
  21 .B pipe
  22 system call
  23 creates an I/O mechanism called a pipe.
  24 The file descriptors returned can
  25 be used in read and write operations.
  26 When the pipe is written using the descriptor
  27 .IR fildes [1]
  28 up to PIPE_MAX bytes of data are buffered
  29 before the writing process is suspended.
  30 A read using the descriptor
  31 .IR fildes [0]
  32 will pick up the data.
  33 .PP
  34 PIPE_MAX equals 7168 under MINIX 3, but note that most systems use 4096.
  35 .PP
  36 It is assumed that after the
  37 pipe has been set up,
  38 two (or more)
  39 cooperating processes
  40 (created by subsequent
  41 .B fork
  42 calls)
  43 will pass data through the
  44 pipe with
  45 .B read
  46 and
  47 .B write
  48 calls.
  49 .PP
  50 The shell has a syntax
  51 to set up a linear array of processes
  52 connected by pipes.
  53 .PP
  54 Read calls on an empty
  55 pipe (no buffered data) with only one end
  56 (all write file descriptors closed)
  57 returns an end-of-file.
  58 .PP
  59 The signal SIGPIPE is generated if a write on a pipe with only one end
  60 is attempted.
  61 .SH "RETURN VALUE
  62 The function value zero is returned if the
  63 pipe was created; \-1 if an error occurred.
  64 .SH ERRORS
  65 The \fBpipe\fP call will fail if:
  66 .TP 15
  67 [EMFILE]
  68 Too many descriptors are active.
  69 .TP 15
  70 [ENFILE]
  71 The system file table is full.
  72 .TP 15
  73 [ENOSPC]
  74 The pipe file system (usually the root file system) has no free inodes.
  75 .TP 15
  76 [EFAULT]
  77 The \fIfildes\fP buffer is in an invalid area of the process's address
  78 space.
  79 .SH "SEE ALSO"
  80 .BR sh (1),
  81 .BR read (2),
  82 .BR write (2),
  83 .BR fork (2).
  84 .SH NOTES
  85 Writes may return ENOSPC errors if no pipe data can be buffered, because
  86 the pipe file system is full.
  87 .SH BUGS
  88 Should more than PIPE_MAX bytes be necessary in any
  89 pipe among a loop of processes, deadlock will occur.