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 2012-02-14 "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 .BR "#include <fcntl.h>" "              /* Obtain O_* constant definitions */
  47 .B #include <unistd.h>
  48 .sp
  49 .BI "int pipe2(int " pipefd "[2], int " flags );
  50 .fi
  51 .SH DESCRIPTION
  52 .BR pipe ()
  53 creates a pipe, a unidirectional data channel that
  54 can be used for interprocess communication.
  55 The array
  56 .IR pipefd
  57 is used to return two file descriptors referring to the ends of the pipe.
  58 .IR pipefd[0]
  59 refers to the read end of the pipe.
  60 .IR pipefd[1]
  61 refers to the write end of the pipe.
  62 Data written to the write end of the pipe is buffered by the kernel
  63 until it is read from the read end of the pipe.
  64 For further details, see
  65 .BR pipe (7).
  66
  67 If
  68 .IR flags
  69 is 0, then
  70 .BR pipe2 ()
  71 is the same as
  72 .BR pipe ().
  73 The following values can be bitwise ORed in
  74 .IR flags
  75 to obtain different behavior:
  76 .TP 12
  77 .B O_NONBLOCK
  78 Set the
  79 .BR O_NONBLOCK
  80 file status flag on the two new open file descriptions.
  81 Using this flag saves extra calls to
  82 .BR fcntl (2)
  83 to achieve the same result.
  84 .TP
  85 .B O_CLOEXEC
  86 Set the close-on-exec
  87 .RB ( FD_CLOEXEC )
  88 flag on the two new file descriptors.
  89 See the description of the same flag in
  90 .BR open (2)
  91 for reasons why this may be useful.
  92 .SH "RETURN VALUE"
  93 On success, zero is returned.
  94 On error, \-1 is returned, and
  95 .I errno
  96 is set appropriately.
  97 .SH ERRORS
  98 .TP
  99 .B EFAULT
 100 .I pipefd
 101 is not valid.
 102 .TP
 103 .B EINVAL
 104 .RB ( pipe2 ())
 105 Invalid value in
 106 .IR flags .
 107 .TP
 108 .B EMFILE
 109 Too many file descriptors are in use by the process.
 110 .TP
 111 .B ENFILE
 112 The system limit on the total number of open files has been reached.
 113 .SH VERSIONS
 114 .BR pipe2 ()
 115 was added to Linux in version 2.6.27;
 116 glibc support is available starting with
 117 version 2.9.
 118 .SH "CONFORMING TO"
 119 .BR pipe ():
 120 POSIX.1-2001.
 121
 122 .BR pipe2 ()
 123 is Linux-specific.
 124 .SH EXAMPLE
 125 .\" fork.2 refers to this example program.
 126 The following program creates a pipe, and then
 127 .BR fork (2)s
 128 to create a child process;
 129 the child inherits a duplicate set of file
 130 descriptors that refer to the same pipe.
 131 After the
 132 .BR fork (2),
 133 each process closes the descriptors that it doesn't need for the pipe
 134 (see
 135 .BR pipe (7)).
 136 The parent then writes the string contained in the program's
 137 command-line argument to the pipe,
 138 and the child reads this string a byte at a time from the pipe
 139 and echoes it on standard output.
 140 .nf
 141
 142 #include <sys/wait.h>
 143 #include <stdio.h>
 144 #include <stdlib.h>
 145 #include <unistd.h>
 146 #include <string.h>
 147
 148 int
 149 main(int argc, char *argv[])
 150 {
 151     int pipefd[2];
 152     pid_t cpid;
 153     char buf;
 154
 155     if (argc != 2) {
 156         fprintf(stderr, "Usage: %s <string>\\n", argv[0]);
 157         exit(EXIT_FAILURE);
 158     }
 159
 160     if (pipe(pipefd) == \-1) {
 161         perror("pipe");
 162         exit(EXIT_FAILURE);
 163     }
 164
 165     cpid = fork();
 166     if (cpid == \-1) {
 167         perror("fork");
 168         exit(EXIT_FAILURE);
 169     }
 170
 171     if (cpid == 0) {    /* Child reads from pipe */
 172         close(pipefd[1]);          /* Close unused write end */
 173
 174         while (read(pipefd[0], &buf, 1) > 0)
 175             write(STDOUT_FILENO, &buf, 1);
 176
 177         write(STDOUT_FILENO, "\\n", 1);
 178         close(pipefd[0]);
 179         _exit(EXIT_SUCCESS);
 180
 181     } else {            /* Parent writes argv[1] to pipe */
 182         close(pipefd[0]);          /* Close unused read end */
 183         write(pipefd[1], argv[1], strlen(argv[1]));
 184         close(pipefd[1]);          /* Reader will see EOF */
 185         wait(NULL);                /* Wait for child */
 186         exit(EXIT_SUCCESS);
 187     }
 188 }
 189 .fi
 190 .SH "SEE ALSO"
 191 .BR fork (2),
 192 .BR read (2),
 193 .BR socketpair (2),
 194 .BR write (2),
 195 .BR popen (3),
 196 .BR pipe (7)