Debian Codegraph @

upstream/debian-trixie/man2/pipe.2

raw
1 .\" Copyright (C) 2005, 2008, Michael Kerrisk <[email protected]>
2 .\" (A few fragments remain from an earlier (1992) version by
3 .\" Drew Eckhardt <[email protected]>.)
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" Modified by Michael Haardt <[email protected]>
8 .\" Modified 1993-07-23 by Rik Faith <[email protected]>
9 .\" Modified 1996-10-22 by Eric S. Raymond <[email protected]>
10 .\" Modified 2004-06-17 by Michael Kerrisk <[email protected]>
11 .\" Modified 2005, mtk: added an example program
12 .\" Modified 2008-01-09, mtk: rewrote DESCRIPTION; minor additions
13 .\" to EXAMPLE text.
14 .\" 2008-10-10, mtk: add description of pipe2()
15 .\"
16 .TH pipe 2 2024-06-15 "Linux man-pages 6.9.1"
17 .SH NAME
18 pipe, pipe2 \- create pipe
19 .SH LIBRARY
20 Standard C library
21 .RI ( libc ", " \-lc )
22 .SH SYNOPSIS
23 .nf
24 .B #include <unistd.h>
25 .P
26 .BI "int pipe(int " pipefd [2]);
27 .P
28 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
29 .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */"
30 .B #include <unistd.h>
31 .P
32 .BI "int pipe2(int " pipefd "[2], int " flags );
33 .P
34 /* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64, pipe() has the
35 following prototype; see VERSIONS */
36 .P
37 .B #include <unistd.h>
38 .P
39 .B struct fd_pair {
40 .B " long fd[2];"
41 .B "};"
42 .B struct fd_pair pipe(void);
43 .fi
44 .SH DESCRIPTION
45 .BR pipe ()
46 creates a pipe, a unidirectional data channel that
47 can be used for interprocess communication.
48 The array
49 .I pipefd
50 is used to return two file descriptors referring to the ends of the pipe.
51 .I pipefd[0]
52 refers to the read end of the pipe.
53 .I pipefd[1]
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).
59 .P
60 If
61 .I flags
62 is 0, then
63 .BR pipe2 ()
64 is the same as
65 .BR pipe ().
66 The following values can be bitwise ORed in
67 .I flags
68 to obtain different behavior:
69 .TP
70 .B O_CLOEXEC
71 Set the close-on-exec
72 .RB ( FD_CLOEXEC )
73 flag on the two new file descriptors.
74 See the description of the same flag in
75 .BR open (2)
76 for reasons why this may be useful.
77 .TP
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 \[bu] 3
89 Writes of greater than
90 .B PIPE_BUF
91 bytes (see
92 .BR pipe (7))
93 will be split into multiple packets.
94 The constant
95 .B PIPE_BUF
96 is defined in
97 .IR <limits.h> .
98 .IP \[bu]
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
105 .B PIPE_BUF
106 will be sufficient to read the largest possible packets
107 (see the previous point).
108 .IP \[bu]
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.
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).
126 .TP
127 .B O_NONBLOCK
128 Set the
129 .B O_NONBLOCK
130 file status flag on the open file descriptions
131 referred to by the new file descriptors.
132 Using this flag saves extra calls to
133 .BR fcntl (2)
134 to achieve the same result.
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.
144 .SH RETURN VALUE
145 On success, zero is returned.
146 On error, \-1 is returned,
147 .I errno
148 is set to indicate the error, and
149 .I pipefd
150 is left unchanged.
151 .P
152 On Linux (and other systems),
153 .BR pipe ()
154 does not modify
155 .I pipefd
156 on failure.
157 A requirement standardizing this behavior was added in POSIX.1-2008 TC2.
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.
165 .SH ERRORS
166 .TP
167 .B EFAULT
168 .I pipefd
169 is not valid.
170 .TP
171 .B EINVAL
172 .RB ( pipe2 ())
173 Invalid value in
174 .IR flags .
175 .TP
176 .B EMFILE
177 The per-process limit on the number of open file descriptors has been reached.
178 .TP
179 .B ENFILE
180 The system-wide limit on the total number of open files has been reached.
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).
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.
195 .SH VERSIONS
196 .\" See http://math-atlas.sourceforge.net/devel/assembly/64.psabi.1.33.ps.Z
197 .\" for example, section 3.2.1 "Registers and the Stack Frame".
198 The System V ABI on some architectures allows the use of more than one register
199 for returning multiple values; several architectures
200 (namely, Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64)
201 (ab)use this feature in order to implement the
202 .BR pipe ()
203 system call in a functional manner:
204 the call doesn't take any arguments and returns
205 a pair of file descriptors as the return value on success.
206 The glibc
207 .BR pipe ()
208 wrapper function transparently deals with this.
209 See
210 .BR syscall (2)
211 for information regarding registers used for storing second file descriptor.
212 .SH STANDARDS
213 .TP
214 .BR pipe ()
215 POSIX.1-2008.
216 .TP
217 .BR pipe2 ()
218 Linux.
219 .SH HISTORY
220 .TP
221 .BR pipe ()
222 POSIX.1-2001.
223 .TP
224 .BR pipe2 ()
225 Linux 2.6.27,
226 glibc 2.9.
227 .SH EXAMPLES
228 .\" fork.2 refers to this example program.
229 The following program creates a pipe, and then
230 .BR fork (2)s
231 to create a child process;
232 the child inherits a duplicate set of file
233 descriptors that refer to the same pipe.
234 After the
235 .BR fork (2),
236 each process closes the file descriptors that it doesn't need for the pipe
237 (see
238 .BR pipe (7)).
239 The parent then writes the string contained in the program's
240 command-line argument to the pipe,
241 and the child reads this string a byte at a time from the pipe
242 and echoes it on standard output.
243 .SS Program source
244 .\" SRC BEGIN (pipe.c)
245 .EX
246 #include <stdio.h>
247 #include <stdlib.h>
248 #include <string.h>
249 #include <sys/types.h>
250 #include <sys/wait.h>
251 #include <unistd.h>
252 \&
253 int
254 main(int argc, char *argv[])
255 {
256 int pipefd[2];
257 char buf;
258 pid_t cpid;
259 \&
260 if (argc != 2) {
261 fprintf(stderr, "Usage: %s <string>\[rs]n", argv[0]);
262 exit(EXIT_FAILURE);
263 }
264 \&
265 if (pipe(pipefd) == \-1) {
266 perror("pipe");
267 exit(EXIT_FAILURE);
268 }
269 \&
270 cpid = fork();
271 if (cpid == \-1) {
272 perror("fork");
273 exit(EXIT_FAILURE);
274 }
275 \&
276 if (cpid == 0) { /* Child reads from pipe */
277 close(pipefd[1]); /* Close unused write end */
278 \&
279 while (read(pipefd[0], &buf, 1) > 0)
280 write(STDOUT_FILENO, &buf, 1);
281 \&
282 write(STDOUT_FILENO, "\[rs]n", 1);
283 close(pipefd[0]);
284 _exit(EXIT_SUCCESS);
285 \&
286 } else { /* Parent writes argv[1] to pipe */
287 close(pipefd[0]); /* Close unused read end */
288 write(pipefd[1], argv[1], strlen(argv[1]));
289 close(pipefd[1]); /* Reader will see EOF */
290 wait(NULL); /* Wait for child */
291 exit(EXIT_SUCCESS);
292 }
293 }
294 .EE
295 .\" SRC END
296 .SH SEE ALSO
297 .BR fork (2),
298 .BR read (2),
299 .BR socketpair (2),
300 .BR splice (2),
301 .BR tee (2),
302 .BR vmsplice (2),
303 .BR write (2),
304 .BR popen (3),
305 .BR pipe (7)