pipe2(2) - f39

1pipe(2)                       System Calls Manual                      pipe(2)
2
3
4

NAME

6       pipe, pipe2 - create pipe
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <unistd.h>
13
14       int pipe(int pipefd[2]);
15
16       #define _GNU_SOURCE             /* See feature_test_macros(7) */
17       #include <fcntl.h>              /* Definition of O_* constants */
18       #include <unistd.h>
19
20       int pipe2(int pipefd[2], int flags);
21
22       /* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64, pipe() has the
23          following prototype; see VERSIONS */
24
25       #include <unistd.h>
26
27       struct fd_pair {
28           long fd[2];
29       };
30       struct fd_pair pipe(void);
31

DESCRIPTION

33       pipe()  creates  a pipe, a unidirectional data channel that can be used
34       for interprocess communication.  The array pipefd is used to return two
35       file  descriptors  referring to the ends of the pipe.  pipefd[0] refers
36       to the read end of the pipe.  pipefd[1] refers to the write end of  the
37       pipe.   Data  written  to  the write end of the pipe is buffered by the
38       kernel until it is read from the read end of the pipe.  For further de‐
39       tails, see pipe(7).
40
41       If  flags is 0, then pipe2() is the same as pipe().  The following val‐
42       ues can be bitwise ORed in flags to obtain different behavior:
43
44       O_CLOEXEC
45              Set the close-on-exec (FD_CLOEXEC) flag on the two new file  de‐
46              scriptors.   See the description of the same flag in open(2) for
47              reasons why this may be useful.
48
49       O_DIRECT (since Linux 3.4)
50              Create a pipe that performs I/O in "packet" mode.  Each write(2)
51              to  the  pipe  is  dealt with as a separate packet, and read(2)s
52              from the pipe will read one packet at a time.  Note the  follow‐
53              ing points:
54
55              •  Writes  of  greater than PIPE_BUF bytes (see pipe(7)) will be
56                 split into multiple packets.  The constant  PIPE_BUF  is  de‐
57                 fined in <limits.h>.
58
59              •  If a read(2) specifies a buffer size that is smaller than the
60                 next packet, then the requested number of bytes are read, and
61                 the  excess  bytes in the packet are discarded.  Specifying a
62                 buffer size of  PIPE_BUF  will  be  sufficient  to  read  the
63                 largest possible packets (see the previous point).
64
65              •  Zero-length packets are not supported.  (A read(2) that spec‐
66                 ifies a buffer size of zero is a no-op, and returns 0.)
67
68              Older kernels that do not support this flag will  indicate  this
69              via an EINVAL error.
70
71              Since  Linux  4.5, it is possible to change the O_DIRECT setting
72              of a pipe file descriptor using fcntl(2).
73
74       O_NONBLOCK
75              Set the O_NONBLOCK file status flag on the  open  file  descrip‐
76              tions  referred to by the new file descriptors.  Using this flag
77              saves extra calls to fcntl(2) to achieve the same result.
78
79       O_NOTIFICATION_PIPE
80              Since Linux 5.8, general notification mechanism is built on  the
81              top  of the pipe where kernel splices notification messages into
82              pipes opened by user space.  The owner of the pipe has  to  tell
83              the kernel which sources of events to watch and filters can also
84              be applied to select which subevents should be placed  into  the
85              pipe.
86

RETURN VALUE

88       On  success,  zero is returned.  On error, -1 is returned, errno is set
89       to indicate the error, and pipefd is left unchanged.
90
91       On Linux (and other systems), pipe() does not modify pipefd on failure.
92       A  requirement  standardizing  this  behavior was added in POSIX.1-2008
93       TC2.  The Linux-specific pipe2() system call likewise does  not  modify
94       pipefd on failure.
95

ERRORS

97       EFAULT pipefd is not valid.
98
99       EINVAL (pipe2()) Invalid value in flags.
100
101       EMFILE The per-process limit on the number of open file descriptors has
102              been reached.
103
104       ENFILE The system-wide limit on the total number of open files has been
105              reached.
106
107       ENFILE The  user  hard  limit on memory that can be allocated for pipes
108              has been reached and the caller is not privileged; see pipe(7).
109
110       ENOPKG (pipe2()) O_NOTIFICATION_PIPE was passed in  flags  and  support
111              for  notifications (CONFIG_WATCH_QUEUE) is not compiled into the
112              kernel.
113

VERSIONS

115       The System V ABI on some architectures allows the use of more than  one
116       register  for returning multiple values; several architectures (namely,
117       Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64) (ab)use this feature  in
118       order  to  implement the pipe() system call in a functional manner: the
119       call doesn't take any arguments and returns a pair of file  descriptors
120       as  the  return  value  on  success.  The glibc pipe() wrapper function
121       transparently deals with this.  See syscall(2) for information  regard‐
122       ing registers used for storing second file descriptor.
123

STANDARDS

125       pipe() POSIX.1-2008.
126
127       pipe2()
128              Linux.
129

HISTORY

131       pipe() POSIX.1-2001.
132
133       pipe2()
134              Linux 2.6.27, glibc 2.9.
135

EXAMPLES

137       The  following  program  creates  a pipe, and then fork(2)s to create a
138       child process; the child inherits a duplicate set of  file  descriptors
139       that  refer  to  the same pipe.  After the fork(2), each process closes
140       the file descriptors that it doesn't need for the pipe  (see  pipe(7)).
141       The  parent  then writes the string contained in the program's command-
142       line argument to the pipe, and the child reads this string a byte at  a
143       time from the pipe and echoes it on standard output.
144
145   Program source
146       #include <stdio.h>
147       #include <stdlib.h>
148       #include <string.h>
149       #include <sys/wait.h>
150       #include <unistd.h>
151
152       int
153       main(int argc, char *argv[])
154       {
155           int    pipefd[2];
156           char   buf;
157           pid_t  cpid;
158
159           if (argc != 2) {
160               fprintf(stderr, "Usage: %s <string>\n", argv[0]);
161               exit(EXIT_FAILURE);
162           }
163
164           if (pipe(pipefd) == -1) {
165               perror("pipe");
166               exit(EXIT_FAILURE);
167           }
168
169           cpid = fork();
170           if (cpid == -1) {
171               perror("fork");
172               exit(EXIT_FAILURE);
173           }
174
175           if (cpid == 0) {    /* Child reads from pipe */
176               close(pipefd[1]);          /* Close unused write end */
177
178               while (read(pipefd[0], &buf, 1) > 0)
179                   write(STDOUT_FILENO, &buf, 1);
180
181               write(STDOUT_FILENO, "\n", 1);
182               close(pipefd[0]);
183               _exit(EXIT_SUCCESS);
184
185           } else {            /* Parent writes argv[1] to pipe */
186               close(pipefd[0]);          /* Close unused read end */
187               write(pipefd[1], argv[1], strlen(argv[1]));
188               close(pipefd[1]);          /* Reader will see EOF */
189               wait(NULL);                /* Wait for child */
190               exit(EXIT_SUCCESS);
191           }
192       }
193