original/man2/pipe.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) 2005, 2008, Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\" (A few fragments remain from an earlier (1992) version by
   5 .\" Drew Eckhardt <drew@cs.colorado.edu>.)
   6 .\"
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\"
  27 .\" Modified by Michael Haardt <michael@moria.de>
  28 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
  29 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
  30 .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
  31 .\" Modified 2005, mtk: added an example program
  32 .\" Modified 2008-01-09, mtk: rewrote DESCRIPTION; minor additions
  33 .\"     to EXAMPLE text.
  34 .\" 2008-10-10, mtk: add description of pipe2()
  35 .\"
  36 .TH PIPE 2 2010-09-10 "Linux" "Linux Programmer's Manual"
  37 .SH NAME
  38 pipe, pipe2 \- create pipe
  39 .SH SYNOPSIS
  40 .nf
  41 .B #include <unistd.h>
  42 .sp
  43 .BI "int pipe(int " pipefd "[2]);"
  44 .sp
  45 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  46 .B #include <unistd.h>
  47 .sp
  48 .BI "int pipe2(int " pipefd "[2], int " flags );
  49 .fi
  50 .SH DESCRIPTION
  51 .BR pipe ()
  52 creates a pipe, a unidirectional data channel that
  53 can be used for interprocess communication.
  54 The array
  55 .IR pipefd
  56 is used to return two file descriptors referring to the ends of the pipe.
  57 .IR pipefd[0]
  58 refers to the read end of the pipe.
  59 .IR pipefd[1]
  60 refers to the write end of the pipe.
  61 Data written to the write end of the pipe is buffered by the kernel
  62 until it is read from the read end of the pipe.
  63 For further details, see
  64 .BR pipe (7).
  65
  66 If
  67 .IR flags
  68 is 0, then
  69 .BR pipe2 ()
  70 is the same as
  71 .BR pipe ().
  72 The following values can be bitwise ORed in
  73 .IR flags
  74 to obtain different behavior:
  75 .TP 12
  76 .B O_NONBLOCK
  77 Set the
  78 .BR O_NONBLOCK
  79 file status flag on the two new open file descriptions.
  80 Using this flag saves extra calls to
  81 .BR fcntl (2)
  82 to achieve the same result.
  83 .TP
  84 .B O_CLOEXEC
  85 Set the close-on-exec
  86 .RB ( FD_CLOEXEC )
  87 flag on the two new file descriptors.
  88 See the description of the same flag in
  89 .BR open (2)
  90 for reasons why this may be useful.
  91 .SH "RETURN VALUE"
  92 On success, zero is returned.
  93 On error, \-1 is returned, and
  94 .I errno
  95 is set appropriately.
  96 .SH ERRORS
  97 .TP
  98 .B EFAULT
  99 .I pipefd
 100 is not valid.
 101 .TP
 102 .B EINVAL
 103 .RB ( pipe2 ())
 104 Invalid value in
 105 .IR flags .
 106 .TP
 107 .B EMFILE
 108 Too many file descriptors are in use by the process.
 109 .TP
 110 .B ENFILE
 111 The system limit on the total number of open files has been reached.
 112 .SH VERSIONS
 113 .BR pipe2 ()
 114 was added to Linux in version 2.6.27;
 115 glibc support is available starting with
 116 version 2.9.
 117 .SH "CONFORMING TO"
 118 .BR pipe ():
 119 POSIX.1-2001.
 120
 121 .BR pipe2 ()
 122 is Linux-specific.
 123 .SH EXAMPLE
 124 .\" fork.2 refers to this example program.
 125 The following program creates a pipe, and then
 126 .BR fork (2)s
 127 to create a child process;
 128 the child inherits a duplicate set of file
 129 descriptors that refer to the same pipe.
 130 After the
 131 .BR fork (2),
 132 each process closes the descriptors that it doesn't need for the pipe
 133 (see
 134 .BR pipe (7)).
 135 The parent then writes the string contained in the program's
 136 command-line argument to the pipe,
 137 and the child reads this string a byte at a time from the pipe
 138 and echoes it on standard output.
 139 .nf
 140
 141 #include <sys/wait.h>
 142 #include <stdio.h>
 143 #include <stdlib.h>
 144 #include <unistd.h>
 145 #include <string.h>
 146
 147 int
 148 main(int argc, char *argv[])
 149 {
 150     int pipefd[2];
 151     pid_t cpid;
 152     char buf;
 153
 154     if (argc != 2) {
 155         fprintf(stderr, "Usage: %s <string>\\n", argv[0]);
 156         exit(EXIT_FAILURE);
 157     }
 158
 159     if (pipe(pipefd) == \-1) {
 160         perror("pipe");
 161         exit(EXIT_FAILURE);
 162     }
 163
 164     cpid = fork();
 165     if (cpid == \-1) {
 166         perror("fork");
 167         exit(EXIT_FAILURE);
 168     }
 169
 170     if (cpid == 0) {    /* Child reads from pipe */
 171         close(pipefd[1]);          /* Close unused write end */
 172
 173         while (read(pipefd[0], &buf, 1) > 0)
 174             write(STDOUT_FILENO, &buf, 1);
 175
 176         write(STDOUT_FILENO, "\\n", 1);
 177         close(pipefd[0]);
 178         _exit(EXIT_SUCCESS);
 179
 180     } else {            /* Parent writes argv[1] to pipe */
 181         close(pipefd[0]);          /* Close unused read end */
 182         write(pipefd[1], argv[1], strlen(argv[1]));
 183         close(pipefd[1]);          /* Reader will see EOF */
 184         wait(NULL);                /* Wait for child */
 185         exit(EXIT_SUCCESS);
 186     }
 187 }
 188 .fi
 189 .SH "SEE ALSO"
 190 .BR fork (2),
 191 .BR read (2),
 192 .BR socketpair (2),
 193 .BR write (2),
 194 .BR popen (3),
 195 .BR pipe (7)