]>
Commit | Line | Data |
---|---|---|
9d227bc5 MK |
1 | .\" Copyright (C) 2005, 2008, Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" (A few fragments remain from an earlier (1992) version by | |
3 | .\" Drew Eckhardt <drew@cs.colorado.edu>.) | |
fea681da | 4 | .\" |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
6 | .\" |
7 | .\" Modified by Michael Haardt <michael@moria.de> | |
8 | .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu> | |
9 | .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> | |
c11b1abf | 10 | .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
9d227bc5 MK |
11 | .\" Modified 2005, mtk: added an example program |
12 | .\" Modified 2008-01-09, mtk: rewrote DESCRIPTION; minor additions | |
13 | .\" to EXAMPLE text. | |
14393ac0 | 14 | .\" 2008-10-10, mtk: add description of pipe2() |
fea681da | 15 | .\" |
45186a5d | 16 | .TH PIPE 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 17 | .SH NAME |
14393ac0 | 18 | pipe, pipe2 \- create pipe |
6cef69cd AC |
19 | .SH LIBRARY |
20 | Standard C library | |
8fc3b2cf | 21 | .RI ( libc ", " \-lc ) |
fea681da | 22 | .SH SYNOPSIS |
14393ac0 | 23 | .nf |
fea681da | 24 | .B #include <unistd.h> |
a12f0259 | 25 | .PP |
5a24cb27 | 26 | .BI "int pipe(int " pipefd [2]); |
eaa18d3c | 27 | .PP |
86b91fdf | 28 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
5a24cb27 | 29 | .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" |
14393ac0 | 30 | .B #include <unistd.h> |
a12f0259 | 31 | .PP |
344689bd | 32 | .BI "int pipe2(int " pipefd "[2], int " flags ); |
92a4b093 MK |
33 | .PP |
34 | /* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64, pipe() has the | |
35 | following prototype; see NOTES */ | |
36 | .PP | |
37 | .B #include <unistd.h> | |
38 | .PP | |
39 | .B struct fd_pair { | |
40 | .B " long fd[2];" | |
41 | .B "};" | |
52b92a2a | 42 | .B struct fd_pair pipe(void); |
14393ac0 | 43 | .fi |
fea681da | 44 | .SH DESCRIPTION |
e511ffb6 | 45 | .BR pipe () |
9d227bc5 MK |
46 | creates a pipe, a unidirectional data channel that |
47 | can be used for interprocess communication. | |
48 | The array | |
1ae6b2c7 | 49 | .I pipefd |
9d227bc5 | 50 | is used to return two file descriptors referring to the ends of the pipe. |
1ae6b2c7 | 51 | .I pipefd[0] |
9d227bc5 | 52 | refers to the read end of the pipe. |
1ae6b2c7 | 53 | .I pipefd[1] |
9d227bc5 MK |
54 | refers to the write end of the pipe. |
55 | Data written to the write end of the pipe is buffered by the kernel | |
56 | until it is read from the read end of the pipe. | |
57 | For further details, see | |
58 | .BR pipe (7). | |
a12f0259 | 59 | .PP |
14393ac0 | 60 | If |
1ae6b2c7 | 61 | .I flags |
14393ac0 MK |
62 | is 0, then |
63 | .BR pipe2 () | |
64 | is the same as | |
65 | .BR pipe (). | |
66 | The following values can be bitwise ORed in | |
1ae6b2c7 | 67 | .I flags |
14393ac0 | 68 | to obtain different behavior: |
75761059 | 69 | .TP |
14393ac0 | 70 | .B O_CLOEXEC |
c7d42779 | 71 | Set the close-on-exec |
8c6e516d | 72 | .RB ( FD_CLOEXEC ) |
c7d42779 | 73 | flag on the two new file descriptors. |
14393ac0 MK |
74 | See the description of the same flag in |
75 | .BR open (2) | |
76 | for reasons why this may be useful. | |
781c32a3 | 77 | .TP |
aeabba50 MK |
78 | .BR O_DIRECT " (since Linux 3.4)" |
79 | .\" commit 9883035ae7edef3ec62ad215611cb8e17d6a1a5d | |
80 | Create a pipe that performs I/O in "packet" mode. | |
81 | Each | |
82 | .BR write (2) | |
83 | to the pipe is dealt with as a separate packet, and | |
84 | .BR read (2)s | |
85 | from the pipe will read one packet at a time. | |
86 | Note the following points: | |
87 | .RS | |
88 | .IP * 3 | |
89 | Writes of greater than | |
1ae6b2c7 | 90 | .B PIPE_BUF |
aeabba50 MK |
91 | bytes (see |
92 | .BR pipe (7)) | |
93 | will be split into multiple packets. | |
4fe82a33 | 94 | The constant |
1ae6b2c7 | 95 | .B PIPE_BUF |
4fe82a33 EDB |
96 | is defined in |
97 | .IR <limits.h> . | |
aeabba50 MK |
98 | .IP * |
99 | If a | |
100 | .BR read (2) | |
101 | specifies a buffer size that is smaller than the next packet, | |
102 | then the requested number of bytes are read, | |
103 | and the excess bytes in the packet are discarded. | |
104 | Specifying a buffer size of | |
1ae6b2c7 | 105 | .B PIPE_BUF |
aeabba50 MK |
106 | will be sufficient to read the largest possible packets |
107 | (see the previous point). | |
108 | .IP * | |
109 | Zero-length packets are not supported. | |
110 | (A | |
111 | .BR read (2) | |
112 | that specifies a buffer size of zero is a no-op, and returns 0.) | |
113 | .RE | |
114 | .IP | |
115 | Older kernels that do not support this flag will indicate this via an | |
116 | .B EINVAL | |
117 | error. | |
2a871e99 MK |
118 | .IP |
119 | Since Linux 4.5, | |
120 | .\" commit 0dbf5f20652108106cb822ad7662c786baaa03ff | |
121 | .\" FIXME . But, it is not possible to specify O_DIRECT when opening a FIFO | |
122 | it is possible to change the | |
123 | .B O_DIRECT | |
124 | setting of a pipe file descriptor using | |
125 | .BR fcntl (2). | |
aeabba50 | 126 | .TP |
781c32a3 MK |
127 | .B O_NONBLOCK |
128 | Set the | |
1ae6b2c7 | 129 | .B O_NONBLOCK |
7f11e32c MK |
130 | file status flag on the open file descriptions |
131 | referred to by the new file descriptors. | |
781c32a3 MK |
132 | Using this flag saves extra calls to |
133 | .BR fcntl (2) | |
134 | to achieve the same result. | |
f2bd7926 CH |
135 | .TP |
136 | .B O_NOTIFICATION_PIPE | |
137 | Since Linux 5.8, | |
138 | .\" commit c73be61cede5882f9605a852414db559c0ebedfd | |
139 | general notification mechanism is built on the top of the pipe where | |
140 | kernel splices notification messages into pipes opened by user space. | |
141 | The owner of the pipe has to tell the kernel which sources of events to watch | |
142 | and filters can also be applied to select | |
143 | which subevents should be placed into the pipe. | |
47297adb | 144 | .SH RETURN VALUE |
c13182ef | 145 | On success, zero is returned. |
1a29a70d | 146 | On error, \-1 is returned, |
fea681da | 147 | .I errno |
c112329f | 148 | is set to indicate the error, and |
1a29a70d MK |
149 | .I pipefd |
150 | is left unchanged. | |
a12f0259 | 151 | .PP |
89cfe0cf MK |
152 | On Linux (and other systems), |
153 | .BR pipe () | |
154 | does not modify | |
155 | .I pipefd | |
156 | on failure. | |
5dbd04b5 | 157 | A requirement standardizing this behavior was added in POSIX.1-2008 TC2. |
89cfe0cf MK |
158 | .\" http://austingroupbugs.net/view.php?id=467 |
159 | The Linux-specific | |
160 | .BR pipe2 () | |
161 | system call | |
162 | likewise does not modify | |
163 | .I pipefd | |
164 | on failure. | |
fea681da MK |
165 | .SH ERRORS |
166 | .TP | |
167 | .B EFAULT | |
a17e03f5 | 168 | .I pipefd |
fea681da MK |
169 | is not valid. |
170 | .TP | |
14393ac0 MK |
171 | .B EINVAL |
172 | .RB ( pipe2 ()) | |
173 | Invalid value in | |
174 | .IR flags . | |
175 | .TP | |
fea681da | 176 | .B EMFILE |
26c32fab | 177 | The per-process limit on the number of open file descriptors has been reached. |
fea681da MK |
178 | .TP |
179 | .B ENFILE | |
e258766b | 180 | The system-wide limit on the total number of open files has been reached. |
4288fe32 MK |
181 | .TP |
182 | .B ENFILE | |
183 | The user hard limit on memory that can be allocated for pipes | |
184 | has been reached and the caller is not privileged; see | |
185 | .BR pipe (7). | |
f2bd7926 CH |
186 | .TP |
187 | .B ENOPKG | |
188 | .RB ( pipe2 ()) | |
189 | .B O_NOTIFICATION_PIPE | |
190 | was passed in | |
191 | .I flags | |
192 | and support for notifications | |
193 | .RB ( CONFIG_WATCH_QUEUE ) | |
194 | is not compiled into the kernel. | |
14393ac0 MK |
195 | .SH VERSIONS |
196 | .BR pipe2 () | |
197 | was added to Linux in version 2.6.27; | |
198 | glibc support is available starting with | |
199 | version 2.9. | |
3113c7f3 | 200 | .SH STANDARDS |
81b8997f MK |
201 | .BR pipe (): |
202 | POSIX.1-2001, POSIX.1-2008. | |
203 | .PP | |
204 | .BR pipe2 () | |
205 | is Linux-specific. | |
70ea1968 ES |
206 | .SH NOTES |
207 | .\" See http://math-atlas.sourceforge.net/devel/assembly/64.psabi.1.33.ps.Z | |
208 | .\" for example, section 3.2.1 "Registers and the Stack Frame". | |
a3d4007c | 209 | The System V ABI on some architectures allows the use of more than one register |
70ea1968 ES |
210 | for returning multiple values; several architectures |
211 | (namely, Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64) | |
03936fb4 | 212 | (ab)use this feature in order to implement the |
70ea1968 | 213 | .BR pipe () |
03936fb4 MK |
214 | system call in a functional manner: |
215 | the call doesn't take any arguments and returns | |
216 | a pair of file descriptors as the return value on success. | |
70ea1968 ES |
217 | The glibc |
218 | .BR pipe () | |
03936fb4 | 219 | wrapper function transparently deals with this. |
70ea1968 ES |
220 | See |
221 | .BR syscall (2) | |
222 | for information regarding registers used for storing second file descriptor. | |
a14af333 | 223 | .SH EXAMPLES |
cde9f44b | 224 | .\" fork.2 refers to this example program. |
c13182ef MK |
225 | The following program creates a pipe, and then |
226 | .BR fork (2)s | |
9d227bc5 MK |
227 | to create a child process; |
228 | the child inherits a duplicate set of file | |
229 | descriptors that refer to the same pipe. | |
c13182ef | 230 | After the |
15740f8a | 231 | .BR fork (2), |
d9cb0d7d | 232 | each process closes the file descriptors that it doesn't need for the pipe |
c13182ef | 233 | (see |
15740f8a | 234 | .BR pipe (7)). |
c13182ef MK |
235 | The parent then writes the string contained in the program's |
236 | command-line argument to the pipe, | |
237 | and the child reads this string a byte at a time from the pipe | |
15740f8a | 238 | and echoes it on standard output. |
f30b7415 | 239 | .SS Program source |
33857069 | 240 | .\" SRC BEGIN (pipe.c) |
a12f0259 | 241 | .EX |
15740f8a MK |
242 | #include <stdio.h> |
243 | #include <stdlib.h> | |
15740f8a | 244 | #include <string.h> |
47b94bbd AC |
245 | #include <sys/wait.h> |
246 | #include <unistd.h> | |
15740f8a MK |
247 | |
248 | int | |
249 | main(int argc, char *argv[]) | |
250 | { | |
a17e03f5 | 251 | int pipefd[2]; |
15740f8a MK |
252 | pid_t cpid; |
253 | char buf; | |
254 | ||
6b34fb3f | 255 | if (argc != 2) { |
d1a71985 | 256 | fprintf(stderr, "Usage: %s <string>\en", argv[0]); |
5a6194a4 | 257 | exit(EXIT_FAILURE); |
6b34fb3f | 258 | } |
15740f8a | 259 | |
a17e03f5 | 260 | if (pipe(pipefd) == \-1) { |
29059a65 MK |
261 | perror("pipe"); |
262 | exit(EXIT_FAILURE); | |
263 | } | |
15740f8a MK |
264 | |
265 | cpid = fork(); | |
29059a65 MK |
266 | if (cpid == \-1) { |
267 | perror("fork"); | |
268 | exit(EXIT_FAILURE); | |
269 | } | |
15740f8a MK |
270 | |
271 | if (cpid == 0) { /* Child reads from pipe */ | |
a17e03f5 | 272 | close(pipefd[1]); /* Close unused write end */ |
15740f8a | 273 | |
a17e03f5 | 274 | while (read(pipefd[0], &buf, 1) > 0) |
15740f8a MK |
275 | write(STDOUT_FILENO, &buf, 1); |
276 | ||
d1a71985 | 277 | write(STDOUT_FILENO, "\en", 1); |
a17e03f5 | 278 | close(pipefd[0]); |
15740f8a MK |
279 | _exit(EXIT_SUCCESS); |
280 | ||
281 | } else { /* Parent writes argv[1] to pipe */ | |
a17e03f5 MK |
282 | close(pipefd[0]); /* Close unused read end */ |
283 | write(pipefd[1], argv[1], strlen(argv[1])); | |
284 | close(pipefd[1]); /* Reader will see EOF */ | |
285 | wait(NULL); /* Wait for child */ | |
15740f8a MK |
286 | exit(EXIT_SUCCESS); |
287 | } | |
288 | } | |
a12f0259 | 289 | .EE |
33857069 | 290 | .\" SRC END |
47297adb | 291 | .SH SEE ALSO |
fea681da MK |
292 | .BR fork (2), |
293 | .BR read (2), | |
294 | .BR socketpair (2), | |
2da4fd31 | 295 | .BR splice (2), |
d7669838 MK |
296 | .BR tee (2), |
297 | .BR vmsplice (2), | |
be37f2c5 | 298 | .BR write (2), |
61fccf7c | 299 | .BR popen (3), |
be37f2c5 | 300 | .BR pipe (7) |