1@node Pipes and FIFOs, Sockets, File System Interface, Top 2@c %MENU% A simple interprocess communication mechanism 3@chapter Pipes and FIFOs 4 5@cindex pipe 6A @dfn{pipe} is a mechanism for interprocess communication; data written 7to the pipe by one process can be read by another process. The data is 8handled in a first-in, first-out (FIFO) order. The pipe has no name; it 9is created for one use and both ends must be inherited from the single 10process which created the pipe. 11 12@cindex FIFO special file 13A @dfn{FIFO special file} is similar to a pipe, but instead of being an 14anonymous, temporary connection, a FIFO has a name or names like any 15other file. Processes open the FIFO by name in order to communicate 16through it. 17 18A pipe or FIFO has to be open at both ends simultaneously. If you read 19from 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 21returns end-of-file. Writing to a pipe or FIFO that doesn't have a 22reading process is treated as an error condition; it generates a 23@code{SIGPIPE} signal, and fails with error code @code{EPIPE} if the 24signal is handled or blocked. 25 26Neither pipes nor FIFO special files allow file positioning. Both 27reading and writing operations happen sequentially; reading from the 28beginning 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 44The primitive for creating a pipe is the @code{pipe} function. This 45creates both the reading and writing ends of the pipe. It is not very 46useful for a single process to use a pipe to talk to itself. In typical 47use, a process creates a pipe just before it forks one or more child 48processes (@pxref{Creating a Process}). The pipe is then used for 49communication either between the parent or child processes, or between 50two sibling processes. 51 52The @code{pipe} function is declared in the header file 53@file{unistd.h}. 54@pindex unistd.h 55 56@deftypefun int pipe (int @var{filedes}@t{[2]}) 57@standards{POSIX.1, unistd.h} 58@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} 59@c On Linux, syscall pipe2. On HURD, call socketpair. 60The @code{pipe} function creates a pipe and puts the file descriptors 61for the reading and writing ends of the pipe (respectively) into 62@code{@var{filedes}[0]} and @code{@var{filedes}[1]}. 63 64An easy way to remember that the input end comes first is that file 65descriptor @code{0} is standard input, and file descriptor @code{1} is 66standard output. 67 68If successful, @code{pipe} returns a value of @code{0}. On failure, 69@code{-1} is returned. The following @code{errno} error conditions are 70defined for this function: 71 72@table @code 73@item EMFILE 74The process has too many files open. 75 76@item ENFILE 77There are too many open files in the entire system. @xref{Error Codes}, 78for more information about @code{ENFILE}. This error never occurs on 79@gnuhurdsystems{}. 80@end table 81@end deftypefun 82 83Here is an example of a simple program that creates a pipe. This program 84uses the @code{fork} function (@pxref{Creating a Process}) to create 85a child process. The parent process writes data to the pipe, which is 86read 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 98A common use of pipes is to send data to or receive data from a program 99being run as a subprocess. One way of doing this is by using a combination of 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 102or output channel), and @code{exec} (to execute the new program). Or, 103you can use @code{popen} and @code{pclose}. 104 105The advantage of using @code{popen} and @code{pclose} is that the 106interface is much simpler and easier to use. But it doesn't offer as 107much flexibility as using the low-level functions directly. 108 109@deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode}) 110@standards{POSIX.2, stdio.h} 111@standards{SVID, stdio.h} 112@standards{BSD, stdio.h} 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 148The @code{popen} function is closely related to the @code{system} 149function; see @ref{Running a Command}. It executes the shell command 150@var{command} as a subprocess. However, instead of waiting for the 151command to complete, it creates a pipe to the subprocess and returns a 152stream that corresponds to that pipe. 153 154If you specify a @var{mode} argument of @code{"r"}, you can read from the 155stream to retrieve data from the standard output channel of the subprocess. 156The subprocess inherits its standard input channel from the parent process. 157 158Similarly, if you specify a @var{mode} argument of @code{"w"}, you can 159write to the stream to send data to the standard input channel of the 160subprocess. The subprocess inherits its standard output channel from 161the parent process. 162 163In the event of an error @code{popen} returns a null pointer. This 164might happen if the pipe or stream cannot be created, if the subprocess 165cannot be forked, or if the program cannot be executed. 166@end deftypefun 167 168@deftypefun int pclose (FILE *@var{stream}) 169@standards{POSIX.2, stdio.h} 170@standards{SVID, stdio.h} 171@standards{BSD, stdio.h} 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 243The @code{pclose} function is used to close a stream created by @code{popen}. 244It waits for the child process to terminate and returns its status value, 245as for the @code{system} function. 246@end deftypefun 247 248Here is an example showing how to use @code{popen} and @code{pclose} to 249filter 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 261A FIFO special file is similar to a pipe, except that it is created in a 262different way. Instead of being an anonymous communications channel, a 263FIFO special file is entered into the file system by calling 264@code{mkfifo}. 265 266Once you have created a FIFO special file in this way, any process can 267open it for reading or writing, in the same way as an ordinary file. 268However, it has to be open at both ends simultaneously before you can 269proceed to do any input or output operations on it. Opening a FIFO for 270reading normally blocks until some other process opens the same FIFO for 271writing, and vice versa. 272 273The @code{mkfifo} function is declared in the header file 274@file{sys/stat.h}. 275@pindex sys/stat.h 276 277@deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode}) 278@standards{POSIX.1, sys/stat.h} 279@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 280@c On generic Posix, calls xmknod. 281The @code{mkfifo} function makes a FIFO special file with name 282@var{filename}. The @var{mode} argument is used to set the file's 283permissions; see @ref{Setting Permissions}. 284 285The normal, successful return value from @code{mkfifo} is @code{0}. In 286the case of an error, @code{-1} is returned. In addition to the usual 287file 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 292The named file already exists. 293 294@item ENOSPC 295The directory or file system cannot be extended. 296 297@item EROFS 298The directory that would contain the file resides on a read-only file 299system. 300@end table 301@end deftypefun 302 303@node Pipe Atomicity 304@section Atomicity of Pipe I/O 305 306Reading or writing pipe data is @dfn{atomic} if the size of data written 307is not greater than @code{PIPE_BUF}. This means that the data transfer 308seems to be an instantaneous unit, in that nothing else in the system 309can observe a state in which it is partially complete. Atomic I/O may 310not begin right away (it may need to wait for buffer space or for data), 311but once it does begin it finishes immediately. 312 313Reading or writing a larger amount of data may not be atomic; for 314example, output data from other processes sharing the descriptor may be 315interspersed. Also, once @code{PIPE_BUF} characters have been written, 316further writes will block until some characters are read. 317 318@xref{Limits for Files}, for information about the @code{PIPE_BUF} 319parameter. 320