]>
Commit | Line | Data |
---|---|---|
2adb3bd6 MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright (C) 2005 Michael Kerrisk <mtk-manpages@gmx.net> | |
4 | .\" | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. | |
18 | .\" | |
19 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
20 | .\" the source, must acknowledge the copyright and authors of this work. | |
21 | .\" | |
22 | .TH PIPE 7 2005-12-08 "Linux 2.6.15" "Linux Programmer's Manual" | |
23 | .SH NAME | |
3a20b4ca | 24 | pipe \- overview of pipes and FIFOs |
2adb3bd6 MK |
25 | .SH DESCRIPTION |
26 | Pipes and FIFOs (also known as named pipes) | |
27 | provide a unidirectional interprocess communication channel. | |
28 | A pipe has a | |
29 | .I read end | |
30 | and a | |
31 | .IR "write end" . | |
32 | Data written to the write end of a pipe can be read | |
48afe71d | 33 | from the read end of the pipe. |
2adb3bd6 MK |
34 | |
35 | A pipe is created using | |
36 | .BR pipe (2), | |
37 | which creates a new pipe and returns two file descriptors, | |
38 | one referring to the read end of the pipe, | |
39 | the other referring to the write end. | |
6d563954 MK |
40 | Pipes can be used to create a communication channel between related |
41 | processes; see | |
42 | .BR pipe (2) | |
43 | for an example. | |
2adb3bd6 MK |
44 | |
45 | A FIFO (short for First In First Out) has a name within the file | |
46 | system (created using | |
47 | .BR mkfifo (3)), | |
48 | and is opened using | |
49 | .BR open (2). | |
50 | Any process may open a FIFO, assuming the file permissions allow it. | |
51 | The read end is opened using the | |
52 | .B O_RDONLY | |
53 | flag; the write end is opened using the | |
54 | .B O_WRONLY | |
55 | flag. | |
56 | See | |
57 | .BR fifo (4) | |
58 | for further details. | |
59 | .IR Note : | |
60 | although FIFOs have a pathname in the file system, | |
48afe71d MK |
61 | I/O on FIFOs does not involve operations on the underlying device |
62 | (if there is one). | |
2adb3bd6 MK |
63 | .SS "I/O on Pipes and FIFOs" |
64 | The only difference between pipes and FIFOs is the manner in which | |
65 | they are created and opened. | |
66 | Once these tasks have been accomplished, | |
67 | I/O on pipes and FIFOs has exactly the same semantics. | |
2adb3bd6 | 68 | |
2adb3bd6 MK |
69 | If a process attempts to read from an empty pipe, then |
70 | .BR read (2) | |
71 | will block until data is available. | |
72 | If a process attempts to write to a full pipe (see below), then | |
73 | .BR write (2) | |
74 | blocks until sufficient data has been read from the pipe | |
75 | to allow the write to complete. | |
76 | Non-blocking I/O is possible by using the | |
77 | .BR fcntl (2) | |
78 | .B F_SETFL | |
79 | operation to enable the | |
80 | .B O_NONBLOCK | |
81 | open file status flag. | |
82 | ||
48afe71d MK |
83 | The communication channel provided by a pipe is a |
84 | .IR "byte stream" : | |
85 | there is no concept of message boundaries. | |
86 | ||
2adb3bd6 MK |
87 | If all file descriptors referring to the write end of a pipe |
88 | have been closed, then an attempt to | |
89 | .BR read (2) | |
90 | from the pipe will see end-of-file | |
91 | .RB ( read (2) | |
92 | will return 0). | |
93 | If all file descriptors referring to the read end of a pipe | |
94 | have been closed, then a | |
95 | .BR write (2) | |
96 | will cause a | |
97 | .B SIGPIPE | |
98 | signal to be generated for the calling process. | |
99 | If the calling process is ignoring this signal, then | |
100 | .BR write (2) | |
101 | fails with the error | |
102 | .BR EPIPE . | |
103 | An application that uses | |
104 | .BR pipe (2) | |
105 | and | |
106 | .BR fork (2) | |
107 | should use suitable | |
108 | .BR close (2) | |
109 | calls to close unnecessary duplicate file descriptors; | |
110 | this ensures that end-of-file and | |
111 | .BR SIGPIPE / EPIPE | |
112 | are delivered when appropriate. | |
113 | ||
48afe71d | 114 | It is not possible to apply |
2adb3bd6 | 115 | .BR lseek (2) |
48afe71d | 116 | to a pipe. |
2adb3bd6 MK |
117 | .SS "Pipe Capacity" |
118 | A pipe has a limited capacity. | |
119 | If the pipe is full, then a | |
120 | .BR write (2) | |
121 | will block or fail, depending on whether the | |
122 | .B O_NONBLOCK | |
123 | flag is set (see below). | |
124 | Different implementations have different limits for the pipe capacity. | |
125 | Applications should not rely on a particular capacity: | |
126 | an application should be designed so that a reading process consumes data | |
127 | as soon as it is available, | |
128 | so that a writing process does not remain blocked. | |
129 | ||
130 | In Linux versions before 2.6.11, the capacity of a pipe was the same as | |
131 | the system page size (e.g., 4096 bytes on x86). | |
132 | Since Linux 2.6.11, the pipe capacity is 65536 bytes. | |
133 | .SS PIPE_BUF | |
134 | POSIX.1 says that | |
135 | .BR write (2)s | |
136 | of less than | |
137 | .B PIPE_BUF | |
138 | bytes must be atomic: the output data is written to the pipe as a | |
139 | contiguous sequence. | |
140 | Writes of more than | |
141 | .B PIPE_BUF | |
142 | bytes may be non-atomic: the kernel may interleave the data | |
143 | with data written by other processes. | |
144 | POSIX.1 requires | |
145 | .B PIPE_BUF | |
146 | to be at least 512 bytes. (On Linux, | |
147 | .B PIPE_BUF | |
148 | is 4096 bytes.) | |
149 | The precise semantics depend on whether the file descriptor is non-blocking | |
150 | .RB ( O_NONBLOCK ), | |
151 | whether there are multiple writers to the pipe, and on | |
152 | .IR n , | |
153 | the number of bytes to be written: | |
154 | .TP | |
155 | \fBO_NONBLOCK\fP disabled, \fIn\fP <= \fBPIPE_BUF\fP | |
156 | All | |
157 | .I n | |
158 | bytes are written atomically; | |
159 | .BR write (2) | |
160 | may block if there is not room for | |
161 | .I n | |
162 | bytes to be written immediately | |
163 | .TP | |
164 | \fBO_NONBLOCK\fP enabled, \fIn\fP <= \fBPIPE_BUF\fP | |
165 | If there is room to write | |
166 | .I n | |
167 | bytes to the pipe, then | |
168 | .BR write (2) | |
169 | succeeds immediately, writing all | |
170 | .I n | |
171 | bytes; otherwise | |
172 | .BR write (2) | |
173 | fails, with | |
174 | .I errno | |
175 | set to | |
176 | .BR EAGAIN . | |
177 | .TP | |
178 | \fBO_NONBLOCK\fP disabled, \fIn\fP > \fBPIPE_BUF\fP | |
179 | The write is non-atomic: the data given to | |
180 | .BR write (2) | |
181 | may be interleaved with | |
182 | .BR write (2)s | |
183 | by other process; | |
184 | the | |
185 | .BR write (2) | |
186 | blocks until | |
187 | .I n | |
188 | bytes have been written. | |
189 | .TP | |
190 | \fBO_NONBLOCK\fP enabled, \fIn\fP > \fBPIPE_BUF\fP | |
191 | If the pipe is full, then | |
192 | .BR write (2) | |
193 | fails, with | |
194 | .I errno | |
195 | set to | |
196 | .BR EAGAIN . | |
197 | Otherwise, from 1 to | |
198 | .I n | |
199 | bytes may be written (i.e., a "partial write" may occur; | |
200 | the caller should check the return value from | |
201 | .BR write (2) | |
202 | to see how many bytes were actually written), | |
203 | and these bytes may be interleaved with writes by other processes. | |
48afe71d MK |
204 | .SS "Open File Status Flags" |
205 | The only open file status flags that can be meaningfully applied to | |
206 | a pipe or FIFO are | |
207 | .B O_NONBLOCK | |
208 | and | |
209 | .BR O_ASYNC . | |
210 | ||
211 | Setting the | |
212 | .B O_ASYNC | |
213 | flag for the read end of a pipe causes a signal | |
214 | .RB ( SIGIO | |
215 | by default) to be generated when new input becomes available on the pipe | |
216 | (see | |
217 | .BR fcntl (2) | |
218 | for details). | |
219 | On Linux, | |
220 | .B O_ASYNC | |
221 | is supported for pipes and FIFOs only since kernel 2.6. | |
2adb3bd6 MK |
222 | .SS "Portability notes" |
223 | On some systems (but not Linux), pipes are bidirectional: | |
224 | data can be transmitted in both directions between the pipe ends. | |
225 | According to POSIX.1, pipes only need to be unidirectional. | |
226 | Portable applications should avoid reliance on | |
227 | bidirectional pipe semantics. | |
228 | .SH "SEE ALSO" | |
229 | .BR dup (2), | |
230 | .BR fcntl (2), | |
231 | .BR open (2), | |
232 | .BR pipe (2), | |
233 | .BR poll (2), | |
234 | .BR select (2), | |
235 | .BR socketpair (2), | |
236 | .BR stat (2), | |
237 | .BR mkfifo (3), | |
238 | .BR fifo (4), | |
2315114c | 239 | .BR epoll (7) |