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