]>
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 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
fea681da MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
fea681da MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
fea681da MK |
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> | |
c11b1abf | 30 | .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
9d227bc5 MK |
31 | .\" Modified 2005, mtk: added an example program |
32 | .\" Modified 2008-01-09, mtk: rewrote DESCRIPTION; minor additions | |
33 | .\" to EXAMPLE text. | |
14393ac0 | 34 | .\" 2008-10-10, mtk: add description of pipe2() |
fea681da | 35 | .\" |
9ba01802 | 36 | .TH PIPE 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
fea681da | 37 | .SH NAME |
14393ac0 | 38 | pipe, pipe2 \- create pipe |
fea681da | 39 | .SH SYNOPSIS |
14393ac0 | 40 | .nf |
fea681da | 41 | .B #include <unistd.h> |
a12f0259 | 42 | .PP |
70ea1968 ES |
43 | /* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64; see NOTES */ |
44 | .B struct fd_pair { | |
45 | .B " long fd[2];" | |
46 | .B "};" | |
47 | .B struct fd_pair pipe(); | |
48 | .PP | |
49 | /* On all other architectures */ | |
a17e03f5 | 50 | .BI "int pipe(int " pipefd "[2]);" |
f90f031e | 51 | |
86b91fdf | 52 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
509b5e8b | 53 | .BR "#include <fcntl.h>" " /* Obtain O_* constant definitions */ |
14393ac0 | 54 | .B #include <unistd.h> |
a12f0259 | 55 | .PP |
344689bd | 56 | .BI "int pipe2(int " pipefd "[2], int " flags ); |
14393ac0 | 57 | .fi |
fea681da | 58 | .SH DESCRIPTION |
e511ffb6 | 59 | .BR pipe () |
9d227bc5 MK |
60 | creates a pipe, a unidirectional data channel that |
61 | can be used for interprocess communication. | |
62 | The array | |
63 | .IR pipefd | |
64 | is used to return two file descriptors referring to the ends of the pipe. | |
65 | .IR pipefd[0] | |
66 | refers to the read end of the pipe. | |
67 | .IR pipefd[1] | |
68 | refers to the write end of the pipe. | |
69 | Data written to the write end of the pipe is buffered by the kernel | |
70 | until it is read from the read end of the pipe. | |
71 | For further details, see | |
72 | .BR pipe (7). | |
a12f0259 | 73 | .PP |
14393ac0 MK |
74 | If |
75 | .IR flags | |
76 | is 0, then | |
77 | .BR pipe2 () | |
78 | is the same as | |
79 | .BR pipe (). | |
80 | The following values can be bitwise ORed in | |
81 | .IR flags | |
82 | to obtain different behavior: | |
75761059 | 83 | .TP |
14393ac0 | 84 | .B O_CLOEXEC |
c7d42779 | 85 | Set the close-on-exec |
8c6e516d | 86 | .RB ( FD_CLOEXEC ) |
c7d42779 | 87 | flag on the two new file descriptors. |
14393ac0 MK |
88 | See the description of the same flag in |
89 | .BR open (2) | |
90 | for reasons why this may be useful. | |
781c32a3 | 91 | .TP |
aeabba50 MK |
92 | .BR O_DIRECT " (since Linux 3.4)" |
93 | .\" commit 9883035ae7edef3ec62ad215611cb8e17d6a1a5d | |
94 | Create a pipe that performs I/O in "packet" mode. | |
95 | Each | |
96 | .BR write (2) | |
97 | to the pipe is dealt with as a separate packet, and | |
98 | .BR read (2)s | |
99 | from the pipe will read one packet at a time. | |
100 | Note the following points: | |
101 | .RS | |
102 | .IP * 3 | |
103 | Writes of greater than | |
104 | .BR PIPE_BUF | |
105 | bytes (see | |
106 | .BR pipe (7)) | |
107 | will be split into multiple packets. | |
4fe82a33 EDB |
108 | The constant |
109 | .BR PIPE_BUF | |
110 | is defined in | |
111 | .IR <limits.h> . | |
aeabba50 MK |
112 | .IP * |
113 | If a | |
114 | .BR read (2) | |
115 | specifies a buffer size that is smaller than the next packet, | |
116 | then the requested number of bytes are read, | |
117 | and the excess bytes in the packet are discarded. | |
118 | Specifying a buffer size of | |
119 | .BR PIPE_BUF | |
120 | will be sufficient to read the largest possible packets | |
121 | (see the previous point). | |
122 | .IP * | |
123 | Zero-length packets are not supported. | |
124 | (A | |
125 | .BR read (2) | |
126 | that specifies a buffer size of zero is a no-op, and returns 0.) | |
127 | .RE | |
128 | .IP | |
129 | Older kernels that do not support this flag will indicate this via an | |
130 | .B EINVAL | |
131 | error. | |
2a871e99 MK |
132 | .IP |
133 | Since Linux 4.5, | |
134 | .\" commit 0dbf5f20652108106cb822ad7662c786baaa03ff | |
135 | .\" FIXME . But, it is not possible to specify O_DIRECT when opening a FIFO | |
136 | it is possible to change the | |
137 | .B O_DIRECT | |
138 | setting of a pipe file descriptor using | |
139 | .BR fcntl (2). | |
aeabba50 | 140 | .TP |
781c32a3 MK |
141 | .B O_NONBLOCK |
142 | Set the | |
143 | .BR O_NONBLOCK | |
7f11e32c MK |
144 | file status flag on the open file descriptions |
145 | referred to by the new file descriptors. | |
781c32a3 MK |
146 | Using this flag saves extra calls to |
147 | .BR fcntl (2) | |
148 | to achieve the same result. | |
47297adb | 149 | .SH RETURN VALUE |
c13182ef | 150 | On success, zero is returned. |
1a29a70d | 151 | On error, \-1 is returned, |
fea681da | 152 | .I errno |
1a29a70d MK |
153 | is set appropriately, and |
154 | .I pipefd | |
155 | is left unchanged. | |
a12f0259 | 156 | .PP |
89cfe0cf MK |
157 | On Linux (and other systems), |
158 | .BR pipe () | |
159 | does not modify | |
160 | .I pipefd | |
161 | on failure. | |
162 | A requirement standardizing this behavior was added in POSIX.1-2016. | |
163 | .\" http://austingroupbugs.net/view.php?id=467 | |
164 | The Linux-specific | |
165 | .BR pipe2 () | |
166 | system call | |
167 | likewise does not modify | |
168 | .I pipefd | |
169 | on failure. | |
fea681da MK |
170 | .SH ERRORS |
171 | .TP | |
172 | .B EFAULT | |
a17e03f5 | 173 | .I pipefd |
fea681da MK |
174 | is not valid. |
175 | .TP | |
14393ac0 MK |
176 | .B EINVAL |
177 | .RB ( pipe2 ()) | |
178 | Invalid value in | |
179 | .IR flags . | |
180 | .TP | |
fea681da | 181 | .B EMFILE |
26c32fab | 182 | The per-process limit on the number of open file descriptors has been reached. |
fea681da MK |
183 | .TP |
184 | .B ENFILE | |
e258766b | 185 | The system-wide limit on the total number of open files has been reached. |
4288fe32 MK |
186 | .TP |
187 | .B ENFILE | |
188 | The user hard limit on memory that can be allocated for pipes | |
189 | has been reached and the caller is not privileged; see | |
190 | .BR pipe (7). | |
14393ac0 MK |
191 | .SH VERSIONS |
192 | .BR pipe2 () | |
193 | was added to Linux in version 2.6.27; | |
194 | glibc support is available starting with | |
195 | version 2.9. | |
70ea1968 ES |
196 | .SH NOTES |
197 | .\" See http://math-atlas.sourceforge.net/devel/assembly/64.psabi.1.33.ps.Z | |
198 | .\" for example, section 3.2.1 "Registers and the Stack Frame". | |
a3d4007c | 199 | The System V ABI on some architectures allows the use of more than one register |
70ea1968 ES |
200 | for returning multiple values; several architectures |
201 | (namely, Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64) | |
03936fb4 | 202 | (ab)use this feature in order to implement the |
70ea1968 | 203 | .BR pipe () |
03936fb4 MK |
204 | system call in a functional manner: |
205 | the call doesn't take any arguments and returns | |
206 | a pair of file descriptors as the return value on success. | |
70ea1968 ES |
207 | The glibc |
208 | .BR pipe () | |
03936fb4 | 209 | wrapper function transparently deals with this. |
70ea1968 ES |
210 | See |
211 | .BR syscall (2) | |
212 | for information regarding registers used for storing second file descriptor. | |
47297adb | 213 | .SH CONFORMING TO |
14393ac0 | 214 | .BR pipe (): |
12faf449 | 215 | POSIX.1-2001, POSIX.1-2008. |
a12f0259 | 216 | .PP |
14393ac0 MK |
217 | .BR pipe2 () |
218 | is Linux-specific. | |
15740f8a | 219 | .SH EXAMPLE |
cde9f44b | 220 | .\" fork.2 refers to this example program. |
c13182ef MK |
221 | The following program creates a pipe, and then |
222 | .BR fork (2)s | |
9d227bc5 MK |
223 | to create a child process; |
224 | the child inherits a duplicate set of file | |
225 | descriptors that refer to the same pipe. | |
c13182ef | 226 | After the |
15740f8a | 227 | .BR fork (2), |
d9cb0d7d | 228 | each process closes the file descriptors that it doesn't need for the pipe |
c13182ef | 229 | (see |
15740f8a | 230 | .BR pipe (7)). |
c13182ef MK |
231 | The parent then writes the string contained in the program's |
232 | command-line argument to the pipe, | |
233 | and the child reads this string a byte at a time from the pipe | |
15740f8a | 234 | and echoes it on standard output. |
f30b7415 | 235 | .SS Program source |
a12f0259 | 236 | .EX |
25505615 | 237 | #include <sys/types.h> |
15740f8a | 238 | #include <sys/wait.h> |
15740f8a MK |
239 | #include <stdio.h> |
240 | #include <stdlib.h> | |
241 | #include <unistd.h> | |
242 | #include <string.h> | |
243 | ||
244 | int | |
245 | main(int argc, char *argv[]) | |
246 | { | |
a17e03f5 | 247 | int pipefd[2]; |
15740f8a MK |
248 | pid_t cpid; |
249 | char buf; | |
250 | ||
6b34fb3f | 251 | if (argc != 2) { |
d1a71985 | 252 | fprintf(stderr, "Usage: %s <string>\en", argv[0]); |
5a6194a4 | 253 | exit(EXIT_FAILURE); |
6b34fb3f | 254 | } |
15740f8a | 255 | |
a17e03f5 | 256 | if (pipe(pipefd) == \-1) { |
29059a65 MK |
257 | perror("pipe"); |
258 | exit(EXIT_FAILURE); | |
259 | } | |
15740f8a MK |
260 | |
261 | cpid = fork(); | |
29059a65 MK |
262 | if (cpid == \-1) { |
263 | perror("fork"); | |
264 | exit(EXIT_FAILURE); | |
265 | } | |
15740f8a MK |
266 | |
267 | if (cpid == 0) { /* Child reads from pipe */ | |
a17e03f5 | 268 | close(pipefd[1]); /* Close unused write end */ |
15740f8a | 269 | |
a17e03f5 | 270 | while (read(pipefd[0], &buf, 1) > 0) |
15740f8a MK |
271 | write(STDOUT_FILENO, &buf, 1); |
272 | ||
d1a71985 | 273 | write(STDOUT_FILENO, "\en", 1); |
a17e03f5 | 274 | close(pipefd[0]); |
15740f8a MK |
275 | _exit(EXIT_SUCCESS); |
276 | ||
277 | } else { /* Parent writes argv[1] to pipe */ | |
a17e03f5 MK |
278 | close(pipefd[0]); /* Close unused read end */ |
279 | write(pipefd[1], argv[1], strlen(argv[1])); | |
280 | close(pipefd[1]); /* Reader will see EOF */ | |
281 | wait(NULL); /* Wait for child */ | |
15740f8a MK |
282 | exit(EXIT_SUCCESS); |
283 | } | |
284 | } | |
a12f0259 | 285 | .EE |
47297adb | 286 | .SH SEE ALSO |
fea681da MK |
287 | .BR fork (2), |
288 | .BR read (2), | |
289 | .BR socketpair (2), | |
2da4fd31 | 290 | .BR splice (2), |
d7669838 MK |
291 | .BR tee (2), |
292 | .BR vmsplice (2), | |
be37f2c5 | 293 | .BR write (2), |
61fccf7c | 294 | .BR popen (3), |
be37f2c5 | 295 | .BR pipe (7) |