]>
Commit | Line | Data |
---|---|---|
28f540f4 | 1 | @node Pipes and FIFOs, Sockets, File System Interface, Top |
7a68c94a | 2 | @c %MENU% A simple interprocess communication mechanism |
28f540f4 RM |
3 | @chapter Pipes and FIFOs |
4 | ||
5 | @cindex pipe | |
6 | A @dfn{pipe} is a mechanism for interprocess communication; data written | |
7 | to the pipe by one process can be read by another process. The data is | |
8 | handled in a first-in, first-out (FIFO) order. The pipe has no name; it | |
9 | is created for one use and both ends must be inherited from the single | |
10 | process which created the pipe. | |
11 | ||
12 | @cindex FIFO special file | |
13 | A @dfn{FIFO special file} is similar to a pipe, but instead of being an | |
14 | anonymous, temporary connection, a FIFO has a name or names like any | |
15 | other file. Processes open the FIFO by name in order to communicate | |
16 | through it. | |
17 | ||
18 | A pipe or FIFO has to be open at both ends simultaneously. If you read | |
19 | from a pipe or FIFO file that doesn't have any processes writing to it | |
20 | (perhaps because they have all closed the file, or exited), the read | |
21 | returns end-of-file. Writing to a pipe or FIFO that doesn't have a | |
22 | reading process is treated as an error condition; it generates a | |
23 | @code{SIGPIPE} signal, and fails with error code @code{EPIPE} if the | |
24 | signal is handled or blocked. | |
25 | ||
26 | Neither pipes nor FIFO special files allow file positioning. Both | |
27 | reading and writing operations happen sequentially; reading from the | |
28 | beginning of the file and writing at the end. | |
29 | ||
30 | @menu | |
31 | * Creating a Pipe:: Making a pipe with the @code{pipe} function. | |
32 | * Pipe to a Subprocess:: Using a pipe to communicate with a | |
33 | child process. | |
34 | * FIFO Special Files:: Making a FIFO special file. | |
35 | * Pipe Atomicity:: When pipe (or FIFO) I/O is atomic. | |
36 | @end menu | |
37 | ||
38 | @node Creating a Pipe | |
39 | @section Creating a Pipe | |
40 | @cindex creating a pipe | |
41 | @cindex opening a pipe | |
42 | @cindex interprocess communication, with pipes | |
43 | ||
44 | The primitive for creating a pipe is the @code{pipe} function. This | |
45 | creates both the reading and writing ends of the pipe. It is not very | |
46 | useful for a single process to use a pipe to talk to itself. In typical | |
47 | use, a process creates a pipe just before it forks one or more child | |
48 | processes (@pxref{Creating a Process}). The pipe is then used for | |
49 | communication either between the parent or child processes, or between | |
50 | two sibling processes. | |
51 | ||
52 | The @code{pipe} function is declared in the header file | |
53 | @file{unistd.h}. | |
54 | @pindex unistd.h | |
55 | ||
28f540f4 | 56 | @deftypefun int pipe (int @var{filedes}@t{[2]}) |
d08a7e4c | 57 | @standards{POSIX.1, unistd.h} |
8c1413f5 AO |
58 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} |
59 | @c On Linux, syscall pipe2. On HURD, call socketpair. | |
28f540f4 RM |
60 | The @code{pipe} function creates a pipe and puts the file descriptors |
61 | for the reading and writing ends of the pipe (respectively) into | |
62 | @code{@var{filedes}[0]} and @code{@var{filedes}[1]}. | |
63 | ||
64 | An easy way to remember that the input end comes first is that file | |
65 | descriptor @code{0} is standard input, and file descriptor @code{1} is | |
66 | standard output. | |
67 | ||
68 | If successful, @code{pipe} returns a value of @code{0}. On failure, | |
69 | @code{-1} is returned. The following @code{errno} error conditions are | |
70 | defined for this function: | |
71 | ||
72 | @table @code | |
73 | @item EMFILE | |
74 | The process has too many files open. | |
75 | ||
76 | @item ENFILE | |
77 | There are too many open files in the entire system. @xref{Error Codes}, | |
a7a93d50 JM |
78 | for more information about @code{ENFILE}. This error never occurs on |
79 | @gnuhurdsystems{}. | |
28f540f4 RM |
80 | @end table |
81 | @end deftypefun | |
82 | ||
83 | Here is an example of a simple program that creates a pipe. This program | |
84 | uses the @code{fork} function (@pxref{Creating a Process}) to create | |
85 | a child process. The parent process writes data to the pipe, which is | |
86 | read by the child process. | |
87 | ||
88 | @smallexample | |
89 | @include pipe.c.texi | |
90 | @end smallexample | |
91 | ||
92 | @node Pipe to a Subprocess | |
93 | @section Pipe to a Subprocess | |
94 | @cindex creating a pipe to a subprocess | |
95 | @cindex pipe to a subprocess | |
96 | @cindex filtering i/o through subprocess | |
97 | ||
98 | A common use of pipes is to send data to or receive data from a program | |
04b9968b | 99 | being run as a subprocess. One way of doing this is by using a combination of |
28f540f4 RM |
100 | @code{pipe} (to create the pipe), @code{fork} (to create the subprocess), |
101 | @code{dup2} (to force the subprocess to use the pipe as its standard input | |
102 | or output channel), and @code{exec} (to execute the new program). Or, | |
103 | you can use @code{popen} and @code{pclose}. | |
104 | ||
105 | The advantage of using @code{popen} and @code{pclose} is that the | |
106 | interface is much simpler and easier to use. But it doesn't offer as | |
107 | much flexibility as using the low-level functions directly. | |
108 | ||
28f540f4 | 109 | @deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode}) |
d08a7e4c RJ |
110 | @standards{POSIX.2, stdio.h} |
111 | @standards{SVID, stdio.h} | |
112 | @standards{BSD, stdio.h} | |
8c1413f5 AO |
113 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
114 | @c popen @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem | |
115 | @c malloc dup @ascuheap @acsmem | |
116 | @c _IO_init ok | |
117 | @c _IO_no_init ok | |
118 | @c _IO_old_init ok | |
119 | @c _IO_lock_init ok | |
120 | @c _IO_new_file_init @asucorrupt @acucorrupt @aculock @acsfd | |
121 | @c _IO_link_in @asucorrupt @acucorrupt @aculock @acsfd | |
122 | @c the linked list is guarded by a recursive lock; | |
123 | @c it may get corrupted with async signals and cancellation | |
124 | @c _IO_lock_lock dup @aculock | |
125 | @c _IO_flockfile dup @aculock | |
126 | @c _IO_funlockfile dup @aculock | |
127 | @c _IO_lock_unlock dup @aculock | |
128 | @c _IO_new_proc_open @asucorrupt @acucorrupt @aculock @acsfd | |
129 | @c the linked list is guarded by a recursive lock; | |
130 | @c it may get corrupted with async signals and cancellation | |
131 | @c _IO_file_is_open ok | |
132 | @c pipe2 dup @acsfd | |
133 | @c pipe dup @acsfd | |
134 | @c _IO_fork=fork @aculock | |
135 | @c _IO_close=close_not_cancel dup @acsfd | |
136 | @c fcntl dup ok | |
137 | @c _IO_lock_lock @aculock | |
138 | @c _IO_lock_unlock @aculock | |
139 | @c _IO_mask_flags ok [no @mtasurace:stream, nearly but sufficiently exclusive access] | |
140 | @c _IO_un_link @asucorrupt @acucorrupt @aculock @acsfd | |
141 | @c the linked list is guarded by a recursive lock; | |
142 | @c it may get corrupted with async signals and cancellation | |
143 | @c _IO_lock_lock dup @aculock | |
144 | @c _IO_flockfile dup @aculock | |
145 | @c _IO_funlockfile dup @aculock | |
146 | @c _IO_lock_unlock dup @aculock | |
147 | @c free dup @ascuheap @acsmem | |
28f540f4 RM |
148 | The @code{popen} function is closely related to the @code{system} |
149 | function; see @ref{Running a Command}. It executes the shell command | |
150 | @var{command} as a subprocess. However, instead of waiting for the | |
151 | command to complete, it creates a pipe to the subprocess and returns a | |
152 | stream that corresponds to that pipe. | |
153 | ||
46d9215f | 154 | If you specify a @var{mode} argument of @code{"r"}, you can read from the |
28f540f4 RM |
155 | stream to retrieve data from the standard output channel of the subprocess. |
156 | The subprocess inherits its standard input channel from the parent process. | |
157 | ||
158 | Similarly, if you specify a @var{mode} argument of @code{"w"}, you can | |
159 | write to the stream to send data to the standard input channel of the | |
160 | subprocess. The subprocess inherits its standard output channel from | |
161 | the parent process. | |
162 | ||
04b9968b | 163 | In the event of an error @code{popen} returns a null pointer. This |
28f540f4 RM |
164 | might happen if the pipe or stream cannot be created, if the subprocess |
165 | cannot be forked, or if the program cannot be executed. | |
166 | @end deftypefun | |
167 | ||
28f540f4 | 168 | @deftypefun int pclose (FILE *@var{stream}) |
d08a7e4c RJ |
169 | @standards{POSIX.2, stdio.h} |
170 | @standards{SVID, stdio.h} | |
171 | @standards{BSD, stdio.h} | |
8c1413f5 AO |
172 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuplugin{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
173 | @c Although the stream cannot be used after the call, even in case of | |
174 | @c async cancellation, because the stream must not be used after pclose | |
175 | @c is called, other stdio linked lists and their locks may be left in | |
176 | @c corrupt states; that's where the corrupt and lock annotations come | |
177 | @c from. | |
178 | @c | |
179 | @c pclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem | |
180 | @c _IO_new_fclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem | |
181 | @c _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd | |
182 | @c _IO_acquire_lock dup @aculock | |
183 | @c _IO_flockfile dup @aculock | |
184 | @c _IO_file_close_it @ascuheap @ascuplugin @asucorrupt @aculock @acucorrupt @acsfd @acsmem | |
185 | @c _IO_file_is_open dup ok | |
186 | @c _IO_do_flush @asucorrupt @ascuplugin @acucorrupt | |
187 | @c _IO_do_write @asucorrupt @acucorrupt | |
188 | @c new_do_write @asucorrupt @acucorrupt | |
189 | @c _IO_SYSSEEK ok | |
190 | @c lseek64 dup ok | |
191 | @c _IO_SYSWRITE ok | |
192 | @c write_not_cancel dup ok | |
193 | @c write dup ok | |
194 | @c _IO_adjust_column ok | |
195 | @c _IO_setg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked] | |
196 | @c _IO_wdo_write @asucorrupt @ascuplugin @acucorrupt | |
197 | @c _IO_new_do_write=_IO_do_write dup @asucorrupt @acucorrupt | |
198 | @c *cc->__codecvt_do_out @ascuplugin | |
199 | @c _IO_wsetg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked] | |
200 | @c _IO_unsave_markers @ascuheap @asucorrupt @acucorrupt @acsmem | |
201 | @c _IO_have_backup dup ok | |
202 | @c _IO_free_backup_area dup @ascuheap @asucorrupt @acucorrupt @acsmem | |
203 | @c _IO_SYSCLOSE @aculock @acucorrupt @acsfd | |
204 | @c _IO_lock_lock dup @aculock | |
205 | @c _IO_close=close_not_cancel dup @acsfd | |
206 | @c _IO_lock_unlock dup @aculock | |
207 | @c _IO_waitpid=waitpid_not_cancel dup ok | |
208 | @c _IO_have_wbackup ok | |
209 | @c _IO_free_wbackup_area @ascuheap @asucorrupt @acucorrupt @acsmem | |
210 | @c _IO_in_backup dup ok | |
211 | @c _IO_switch_to_main_wget_area @asucorrupt @acucorrupt | |
212 | @c free dup @ascuheap @acsmem | |
213 | @c _IO_wsetb @asucorrupt @acucorrupt [no @mtasurace:stream, locked] | |
214 | @c _IO_wsetg @asucorrupt @acucorrupt [no @mtasurace:stream, locked] | |
215 | @c _IO_wsetp @asucorrupt @acucorrupt [no @mtasurace:stream, locked] | |
216 | @c _IO_setb @asucorrupt @acucorrupt [no @mtasurace:stream, locked] | |
217 | @c _IO_setg @asucorrupt @acucorrupt [no @mtasurace:stream, locked] | |
218 | @c _IO_setp @asucorrupt @acucorrupt [no @mtasurace:stream, locked] | |
219 | @c _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd | |
220 | @c _IO_release_lock dup @aculock | |
221 | @c _IO_funlockfile dup @aculock | |
222 | @c _IO_FINISH @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem | |
223 | @c _IO_new_file_finish @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem | |
224 | @c _IO_file_is_open dup ok | |
225 | @c _IO_do_flush dup @ascuplugin @asucorrupt @acucorrupt | |
226 | @c _IO_SYSCLOSE dup @aculock @acucorrupt @acsfd | |
227 | @c _IO_default_finish @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem | |
228 | @c FREE_BUF @acsmem | |
229 | @c munmap dup @acsmem | |
230 | @c free dup @ascuheap @acsmem | |
231 | @c _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd | |
232 | @c _IO_lock_fini ok | |
233 | @c libc_lock_fini_recursive ok | |
234 | @c libc_lock_lock dup @asulock @aculock | |
235 | @c gconv_release_step ok | |
236 | @c libc_lock_unlock dup @asulock @aculock | |
237 | @c _IO_have_backup ok | |
238 | @c _IO_free_backup_area @ascuheap @asucorrupt @acucorrupt @acsmem | |
239 | @c _IO_in_backup ok | |
240 | @c _IO_switch_to_main_get_area @asucorrupt @acucorrupt | |
241 | @c free dup @ascuheap @acsmem | |
242 | @c free dup @ascuheap @acsmem | |
28f540f4 RM |
243 | The @code{pclose} function is used to close a stream created by @code{popen}. |
244 | It waits for the child process to terminate and returns its status value, | |
245 | as for the @code{system} function. | |
246 | @end deftypefun | |
247 | ||
248 | Here is an example showing how to use @code{popen} and @code{pclose} to | |
249 | filter output through another program, in this case the paging program | |
250 | @code{more}. | |
251 | ||
252 | @smallexample | |
253 | @include popen.c.texi | |
254 | @end smallexample | |
255 | ||
256 | @node FIFO Special Files | |
257 | @section FIFO Special Files | |
258 | @cindex creating a FIFO special file | |
259 | @cindex interprocess communication, with FIFO | |
260 | ||
261 | A FIFO special file is similar to a pipe, except that it is created in a | |
262 | different way. Instead of being an anonymous communications channel, a | |
263 | FIFO special file is entered into the file system by calling | |
264 | @code{mkfifo}. | |
265 | ||
266 | Once you have created a FIFO special file in this way, any process can | |
267 | open it for reading or writing, in the same way as an ordinary file. | |
268 | However, it has to be open at both ends simultaneously before you can | |
269 | proceed to do any input or output operations on it. Opening a FIFO for | |
270 | reading normally blocks until some other process opens the same FIFO for | |
271 | writing, and vice versa. | |
272 | ||
273 | The @code{mkfifo} function is declared in the header file | |
274 | @file{sys/stat.h}. | |
275 | @pindex sys/stat.h | |
276 | ||
28f540f4 | 277 | @deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode}) |
d08a7e4c | 278 | @standards{POSIX.1, sys/stat.h} |
8c1413f5 AO |
279 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
280 | @c On generic Posix, calls xmknod. | |
28f540f4 RM |
281 | The @code{mkfifo} function makes a FIFO special file with name |
282 | @var{filename}. The @var{mode} argument is used to set the file's | |
283 | permissions; see @ref{Setting Permissions}. | |
284 | ||
285 | The normal, successful return value from @code{mkfifo} is @code{0}. In | |
286 | the case of an error, @code{-1} is returned. In addition to the usual | |
287 | file name errors (@pxref{File Name Errors}), the following | |
288 | @code{errno} error conditions are defined for this function: | |
289 | ||
290 | @table @code | |
291 | @item EEXIST | |
292 | The named file already exists. | |
293 | ||
294 | @item ENOSPC | |
295 | The directory or file system cannot be extended. | |
296 | ||
297 | @item EROFS | |
298 | The directory that would contain the file resides on a read-only file | |
299 | system. | |
300 | @end table | |
301 | @end deftypefun | |
302 | ||
303 | @node Pipe Atomicity | |
304 | @section Atomicity of Pipe I/O | |
305 | ||
306 | Reading or writing pipe data is @dfn{atomic} if the size of data written | |
46d9215f RM |
307 | is not greater than @code{PIPE_BUF}. This means that the data transfer |
308 | seems to be an instantaneous unit, in that nothing else in the system | |
309 | can observe a state in which it is partially complete. Atomic I/O may | |
310 | not begin right away (it may need to wait for buffer space or for data), | |
04b9968b | 311 | but once it does begin it finishes immediately. |
28f540f4 RM |
312 | |
313 | Reading or writing a larger amount of data may not be atomic; for | |
314 | example, output data from other processes sharing the descriptor may be | |
315 | interspersed. Also, once @code{PIPE_BUF} characters have been written, | |
316 | further writes will block until some characters are read. | |
317 | ||
318 | @xref{Limits for Files}, for information about the @code{PIPE_BUF} | |
319 | parameter. |