1PIPE(2)                    Linux Programmer's Manual                   PIPE(2)
2
3
4

NAME

6       pipe, pipe2 - create pipe
7

SYNOPSIS

9       #include <unistd.h>
10
11       int pipe(int pipefd[2]);
12
13       #define _GNU_SOURCE             /* See feature_test_macros(7) */
14       #include <fcntl.h>              /* Obtain O_* constant definitions */
15       #include <unistd.h>
16
17       int pipe2(int pipefd[2], int flags);
18

DESCRIPTION

20       pipe()  creates  a pipe, a unidirectional data channel that can be used
21       for interprocess communication.  The array pipefd is used to return two
22       file  descriptors  referring to the ends of the pipe.  pipefd[0] refers
23       to the read end of the pipe.  pipefd[1] refers to the write end of  the
24       pipe.   Data  written  to  the write end of the pipe is buffered by the
25       kernel until it is read from the read end of  the  pipe.   For  further
26       details, see pipe(7).
27
28       If  flags is 0, then pipe2() is the same as pipe().  The following val‐
29       ues can be bitwise ORed in flags to obtain different behavior:
30
31       O_CLOEXEC
32              Set the close-on-exec (FD_CLOEXEC) flag  on  the  two  new  file
33              descriptors.   See  the  description of the same flag in open(2)
34              for reasons why this may be useful.
35
36       O_DIRECT (since Linux 3.4)
37              Create a pipe that performs I/O in "packet" mode.  Each write(2)
38              to  the  pipe  is  dealt with as a separate packet, and read(2)s
39              from the pipe will read one packet at a time.  Note the  follow‐
40              ing points:
41
42              *  Writes  of  greater than PIPE_BUF bytes (see pipe(7)) will be
43                 split  into  multiple  packets.   The  constant  PIPE_BUF  is
44                 defined in <limits.h>.
45
46              *  If a read(2) specifies a buffer size that is smaller than the
47                 next packet, then the requested number of bytes are read, and
48                 the  excess  bytes in the packet are discarded.  Specifying a
49                 buffer size of  PIPE_BUF  will  be  sufficient  to  read  the
50                 largest possible packets (see the previous point).
51
52              *  Zero-length packets are not supported.  (A read(2) that spec‐
53                 ifies a buffer size of zero is a no-op, and returns 0.)
54
55              Older kernels that do not support this flag will  indicate  this
56              via an EINVAL error.
57
58              Since  Linux  4.5, it is possible to change the O_DIRECT setting
59              of a pipe file descriptor using fcntl(2).
60
61       O_NONBLOCK
62              Set the O_NONBLOCK file status flag on the  two  new  open  file
63              descriptions.   Using this flag saves extra calls to fcntl(2) to
64              achieve the same result.
65

RETURN VALUE

67       On success, zero is returned.  On error, -1 is returned, and  errno  is
68       set appropriately.
69
70       On Linux (and other systems), pipe() does not modify pipefd on failure.
71       A requirement standardizing this behavior was  added  in  POSIX.1-2016.
72       The  Linux-specific pipe2() system call likewise does not modify pipefd
73       on failure.
74

ERRORS

76       EFAULT pipefd is not valid.
77
78       EINVAL (pipe2()) Invalid value in flags.
79
80       EMFILE The per-process limit on the number of open file descriptors has
81              been reached.
82
83       ENFILE The system-wide limit on the total number of open files has been
84              reached.
85
86       ENFILE The user hard limit on memory that can be  allocated  for  pipes
87              has been reached and the caller is not privileged; see pipe(7).
88

VERSIONS

90       pipe2()  was  added to Linux in version 2.6.27; glibc support is avail‐
91       able starting with version 2.9.
92

CONFORMING TO

94       pipe(): POSIX.1-2001, POSIX.1-2008.
95
96       pipe2() is Linux-specific.
97

EXAMPLE

99       The following program creates a pipe, and then  fork(2)s  to  create  a
100       child  process;  the child inherits a duplicate set of file descriptors
101       that refer to the same pipe.  After the fork(2),  each  process  closes
102       the  file  descriptors that it doesn't need for the pipe (see pipe(7)).
103       The parent then writes the string contained in the  program's  command-
104       line  argument to the pipe, and the child reads this string a byte at a
105       time from the pipe and echoes it on standard output.
106
107   Program source
108       #include <sys/types.h>
109       #include <sys/wait.h>
110       #include <stdio.h>
111       #include <stdlib.h>
112       #include <unistd.h>
113       #include <string.h>
114
115       int
116       main(int argc, char *argv[])
117       {
118           int pipefd[2];
119           pid_t cpid;
120           char buf;
121
122           if (argc != 2) {
123               fprintf(stderr, "Usage: %s <string>\n", argv[0]);
124               exit(EXIT_FAILURE);
125           }
126
127           if (pipe(pipefd) == -1) {
128               perror("pipe");
129               exit(EXIT_FAILURE);
130           }
131
132           cpid = fork();
133           if (cpid == -1) {
134               perror("fork");
135               exit(EXIT_FAILURE);
136           }
137
138           if (cpid == 0) {    /* Child reads from pipe */
139               close(pipefd[1]);          /* Close unused write end */
140
141               while (read(pipefd[0], &buf, 1) > 0)
142                   write(STDOUT_FILENO, &buf, 1);
143
144               write(STDOUT_FILENO, "\n", 1);
145               close(pipefd[0]);
146               _exit(EXIT_SUCCESS);
147
148           } else {            /* Parent writes argv[1] to pipe */
149               close(pipefd[0]);          /* Close unused read end */
150               write(pipefd[1], argv[1], strlen(argv[1]));
151               close(pipefd[1]);          /* Reader will see EOF */
152               wait(NULL);                /* Wait for child */
153               exit(EXIT_SUCCESS);
154           }
155       }
156

SEE ALSO

158       fork(2),  read(2),  socketpair(2),  splice(2),   tee(2),   vmsplice(2),
159       write(2), popen(3), pipe(7)
160

COLOPHON

162       This  page  is  part of release 4.16 of the Linux man-pages project.  A
163       description of the project, information about reporting bugs,  and  the
164       latest     version     of     this    page,    can    be    found    at
165       https://www.kernel.org/doc/man-pages/.
166
167
168
169Linux                             2017-11-26                           PIPE(2)
Impressum