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