320 lines
13 KiB
Plaintext
320 lines
13 KiB
Plaintext
@node Pipes and FIFOs, Sockets, File System Interface, Top
|
|
@c %MENU% A simple interprocess communication mechanism
|
|
@chapter Pipes and FIFOs
|
|
|
|
@cindex pipe
|
|
A @dfn{pipe} is a mechanism for interprocess communication; data written
|
|
to the pipe by one process can be read by another process. The data is
|
|
handled in a first-in, first-out (FIFO) order. The pipe has no name; it
|
|
is created for one use and both ends must be inherited from the single
|
|
process which created the pipe.
|
|
|
|
@cindex FIFO special file
|
|
A @dfn{FIFO special file} is similar to a pipe, but instead of being an
|
|
anonymous, temporary connection, a FIFO has a name or names like any
|
|
other file. Processes open the FIFO by name in order to communicate
|
|
through it.
|
|
|
|
A pipe or FIFO has to be open at both ends simultaneously. If you read
|
|
from a pipe or FIFO file that doesn't have any processes writing to it
|
|
(perhaps because they have all closed the file, or exited), the read
|
|
returns end-of-file. Writing to a pipe or FIFO that doesn't have a
|
|
reading process is treated as an error condition; it generates a
|
|
@code{SIGPIPE} signal, and fails with error code @code{EPIPE} if the
|
|
signal is handled or blocked.
|
|
|
|
Neither pipes nor FIFO special files allow file positioning. Both
|
|
reading and writing operations happen sequentially; reading from the
|
|
beginning of the file and writing at the end.
|
|
|
|
@menu
|
|
* Creating a Pipe:: Making a pipe with the @code{pipe} function.
|
|
* Pipe to a Subprocess:: Using a pipe to communicate with a
|
|
child process.
|
|
* FIFO Special Files:: Making a FIFO special file.
|
|
* Pipe Atomicity:: When pipe (or FIFO) I/O is atomic.
|
|
@end menu
|
|
|
|
@node Creating a Pipe
|
|
@section Creating a Pipe
|
|
@cindex creating a pipe
|
|
@cindex opening a pipe
|
|
@cindex interprocess communication, with pipes
|
|
|
|
The primitive for creating a pipe is the @code{pipe} function. This
|
|
creates both the reading and writing ends of the pipe. It is not very
|
|
useful for a single process to use a pipe to talk to itself. In typical
|
|
use, a process creates a pipe just before it forks one or more child
|
|
processes (@pxref{Creating a Process}). The pipe is then used for
|
|
communication either between the parent or child processes, or between
|
|
two sibling processes.
|
|
|
|
The @code{pipe} function is declared in the header file
|
|
@file{unistd.h}.
|
|
@pindex unistd.h
|
|
|
|
@comment unistd.h
|
|
@comment POSIX.1
|
|
@deftypefun int pipe (int @var{filedes}@t{[2]})
|
|
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
|
|
@c On Linux, syscall pipe2. On HURD, call socketpair.
|
|
The @code{pipe} function creates a pipe and puts the file descriptors
|
|
for the reading and writing ends of the pipe (respectively) into
|
|
@code{@var{filedes}[0]} and @code{@var{filedes}[1]}.
|
|
|
|
An easy way to remember that the input end comes first is that file
|
|
descriptor @code{0} is standard input, and file descriptor @code{1} is
|
|
standard output.
|
|
|
|
If successful, @code{pipe} returns a value of @code{0}. On failure,
|
|
@code{-1} is returned. The following @code{errno} error conditions are
|
|
defined for this function:
|
|
|
|
@table @code
|
|
@item EMFILE
|
|
The process has too many files open.
|
|
|
|
@item ENFILE
|
|
There are too many open files in the entire system. @xref{Error Codes},
|
|
for more information about @code{ENFILE}. This error never occurs on
|
|
@gnuhurdsystems{}.
|
|
@end table
|
|
@end deftypefun
|
|
|
|
Here is an example of a simple program that creates a pipe. This program
|
|
uses the @code{fork} function (@pxref{Creating a Process}) to create
|
|
a child process. The parent process writes data to the pipe, which is
|
|
read by the child process.
|
|
|
|
@smallexample
|
|
@include pipe.c.texi
|
|
@end smallexample
|
|
|
|
@node Pipe to a Subprocess
|
|
@section Pipe to a Subprocess
|
|
@cindex creating a pipe to a subprocess
|
|
@cindex pipe to a subprocess
|
|
@cindex filtering i/o through subprocess
|
|
|
|
A common use of pipes is to send data to or receive data from a program
|
|
being run as a subprocess. One way of doing this is by using a combination of
|
|
@code{pipe} (to create the pipe), @code{fork} (to create the subprocess),
|
|
@code{dup2} (to force the subprocess to use the pipe as its standard input
|
|
or output channel), and @code{exec} (to execute the new program). Or,
|
|
you can use @code{popen} and @code{pclose}.
|
|
|
|
The advantage of using @code{popen} and @code{pclose} is that the
|
|
interface is much simpler and easier to use. But it doesn't offer as
|
|
much flexibility as using the low-level functions directly.
|
|
|
|
@comment stdio.h
|
|
@comment POSIX.2, SVID, BSD
|
|
@deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode})
|
|
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
|
|
@c popen @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem
|
|
@c malloc dup @ascuheap @acsmem
|
|
@c _IO_init ok
|
|
@c _IO_no_init ok
|
|
@c _IO_old_init ok
|
|
@c _IO_lock_init ok
|
|
@c _IO_new_file_init @asucorrupt @acucorrupt @aculock @acsfd
|
|
@c _IO_link_in @asucorrupt @acucorrupt @aculock @acsfd
|
|
@c the linked list is guarded by a recursive lock;
|
|
@c it may get corrupted with async signals and cancellation
|
|
@c _IO_lock_lock dup @aculock
|
|
@c _IO_flockfile dup @aculock
|
|
@c _IO_funlockfile dup @aculock
|
|
@c _IO_lock_unlock dup @aculock
|
|
@c _IO_new_proc_open @asucorrupt @acucorrupt @aculock @acsfd
|
|
@c the linked list is guarded by a recursive lock;
|
|
@c it may get corrupted with async signals and cancellation
|
|
@c _IO_file_is_open ok
|
|
@c pipe2 dup @acsfd
|
|
@c pipe dup @acsfd
|
|
@c _IO_fork=fork @aculock
|
|
@c _IO_close=close_not_cancel dup @acsfd
|
|
@c fcntl dup ok
|
|
@c _IO_lock_lock @aculock
|
|
@c _IO_lock_unlock @aculock
|
|
@c _IO_mask_flags ok [no @mtasurace:stream, nearly but sufficiently exclusive access]
|
|
@c _IO_un_link @asucorrupt @acucorrupt @aculock @acsfd
|
|
@c the linked list is guarded by a recursive lock;
|
|
@c it may get corrupted with async signals and cancellation
|
|
@c _IO_lock_lock dup @aculock
|
|
@c _IO_flockfile dup @aculock
|
|
@c _IO_funlockfile dup @aculock
|
|
@c _IO_lock_unlock dup @aculock
|
|
@c free dup @ascuheap @acsmem
|
|
The @code{popen} function is closely related to the @code{system}
|
|
function; see @ref{Running a Command}. It executes the shell command
|
|
@var{command} as a subprocess. However, instead of waiting for the
|
|
command to complete, it creates a pipe to the subprocess and returns a
|
|
stream that corresponds to that pipe.
|
|
|
|
If you specify a @var{mode} argument of @code{"r"}, you can read from the
|
|
stream to retrieve data from the standard output channel of the subprocess.
|
|
The subprocess inherits its standard input channel from the parent process.
|
|
|
|
Similarly, if you specify a @var{mode} argument of @code{"w"}, you can
|
|
write to the stream to send data to the standard input channel of the
|
|
subprocess. The subprocess inherits its standard output channel from
|
|
the parent process.
|
|
|
|
In the event of an error @code{popen} returns a null pointer. This
|
|
might happen if the pipe or stream cannot be created, if the subprocess
|
|
cannot be forked, or if the program cannot be executed.
|
|
@end deftypefun
|
|
|
|
@comment stdio.h
|
|
@comment POSIX.2, SVID, BSD
|
|
@deftypefun int pclose (FILE *@var{stream})
|
|
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuplugin{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
|
|
@c Although the stream cannot be used after the call, even in case of
|
|
@c async cancellation, because the stream must not be used after pclose
|
|
@c is called, other stdio linked lists and their locks may be left in
|
|
@c corrupt states; that's where the corrupt and lock annotations come
|
|
@c from.
|
|
@c
|
|
@c pclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem
|
|
@c _IO_new_fclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem
|
|
@c _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
|
|
@c _IO_acquire_lock dup @aculock
|
|
@c _IO_flockfile dup @aculock
|
|
@c _IO_file_close_it @ascuheap @ascuplugin @asucorrupt @aculock @acucorrupt @acsfd @acsmem
|
|
@c _IO_file_is_open dup ok
|
|
@c _IO_do_flush @asucorrupt @ascuplugin @acucorrupt
|
|
@c _IO_do_write @asucorrupt @acucorrupt
|
|
@c new_do_write @asucorrupt @acucorrupt
|
|
@c _IO_SYSSEEK ok
|
|
@c lseek64 dup ok
|
|
@c _IO_SYSWRITE ok
|
|
@c write_not_cancel dup ok
|
|
@c write dup ok
|
|
@c _IO_adjust_column ok
|
|
@c _IO_setg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
|
|
@c _IO_wdo_write @asucorrupt @ascuplugin @acucorrupt
|
|
@c _IO_new_do_write=_IO_do_write dup @asucorrupt @acucorrupt
|
|
@c *cc->__codecvt_do_out @ascuplugin
|
|
@c _IO_wsetg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
|
|
@c _IO_unsave_markers @ascuheap @asucorrupt @acucorrupt @acsmem
|
|
@c _IO_have_backup dup ok
|
|
@c _IO_free_backup_area dup @ascuheap @asucorrupt @acucorrupt @acsmem
|
|
@c _IO_SYSCLOSE @aculock @acucorrupt @acsfd
|
|
@c _IO_lock_lock dup @aculock
|
|
@c _IO_close=close_not_cancel dup @acsfd
|
|
@c _IO_lock_unlock dup @aculock
|
|
@c _IO_waitpid=waitpid_not_cancel dup ok
|
|
@c _IO_have_wbackup ok
|
|
@c _IO_free_wbackup_area @ascuheap @asucorrupt @acucorrupt @acsmem
|
|
@c _IO_in_backup dup ok
|
|
@c _IO_switch_to_main_wget_area @asucorrupt @acucorrupt
|
|
@c free dup @ascuheap @acsmem
|
|
@c _IO_wsetb @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
|
|
@c _IO_wsetg @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
|
|
@c _IO_wsetp @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
|
|
@c _IO_setb @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
|
|
@c _IO_setg @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
|
|
@c _IO_setp @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
|
|
@c _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
|
|
@c _IO_release_lock dup @aculock
|
|
@c _IO_funlockfile dup @aculock
|
|
@c _IO_FINISH @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem
|
|
@c _IO_new_file_finish @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem
|
|
@c _IO_file_is_open dup ok
|
|
@c _IO_do_flush dup @ascuplugin @asucorrupt @acucorrupt
|
|
@c _IO_SYSCLOSE dup @aculock @acucorrupt @acsfd
|
|
@c _IO_default_finish @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem
|
|
@c FREE_BUF @acsmem
|
|
@c munmap dup @acsmem
|
|
@c free dup @ascuheap @acsmem
|
|
@c _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
|
|
@c _IO_lock_fini ok
|
|
@c libc_lock_fini_recursive ok
|
|
@c libc_lock_lock dup @asulock @aculock
|
|
@c gconv_release_step ok
|
|
@c libc_lock_unlock dup @asulock @aculock
|
|
@c _IO_have_backup ok
|
|
@c _IO_free_backup_area @ascuheap @asucorrupt @acucorrupt @acsmem
|
|
@c _IO_in_backup ok
|
|
@c _IO_switch_to_main_get_area @asucorrupt @acucorrupt
|
|
@c free dup @ascuheap @acsmem
|
|
@c free dup @ascuheap @acsmem
|
|
The @code{pclose} function is used to close a stream created by @code{popen}.
|
|
It waits for the child process to terminate and returns its status value,
|
|
as for the @code{system} function.
|
|
@end deftypefun
|
|
|
|
Here is an example showing how to use @code{popen} and @code{pclose} to
|
|
filter output through another program, in this case the paging program
|
|
@code{more}.
|
|
|
|
@smallexample
|
|
@include popen.c.texi
|
|
@end smallexample
|
|
|
|
@node FIFO Special Files
|
|
@section FIFO Special Files
|
|
@cindex creating a FIFO special file
|
|
@cindex interprocess communication, with FIFO
|
|
|
|
A FIFO special file is similar to a pipe, except that it is created in a
|
|
different way. Instead of being an anonymous communications channel, a
|
|
FIFO special file is entered into the file system by calling
|
|
@code{mkfifo}.
|
|
|
|
Once you have created a FIFO special file in this way, any process can
|
|
open it for reading or writing, in the same way as an ordinary file.
|
|
However, it has to be open at both ends simultaneously before you can
|
|
proceed to do any input or output operations on it. Opening a FIFO for
|
|
reading normally blocks until some other process opens the same FIFO for
|
|
writing, and vice versa.
|
|
|
|
The @code{mkfifo} function is declared in the header file
|
|
@file{sys/stat.h}.
|
|
@pindex sys/stat.h
|
|
|
|
@comment sys/stat.h
|
|
@comment POSIX.1
|
|
@deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode})
|
|
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
@c On generic Posix, calls xmknod.
|
|
The @code{mkfifo} function makes a FIFO special file with name
|
|
@var{filename}. The @var{mode} argument is used to set the file's
|
|
permissions; see @ref{Setting Permissions}.
|
|
|
|
The normal, successful return value from @code{mkfifo} is @code{0}. In
|
|
the case of an error, @code{-1} is returned. In addition to the usual
|
|
file name errors (@pxref{File Name Errors}), the following
|
|
@code{errno} error conditions are defined for this function:
|
|
|
|
@table @code
|
|
@item EEXIST
|
|
The named file already exists.
|
|
|
|
@item ENOSPC
|
|
The directory or file system cannot be extended.
|
|
|
|
@item EROFS
|
|
The directory that would contain the file resides on a read-only file
|
|
system.
|
|
@end table
|
|
@end deftypefun
|
|
|
|
@node Pipe Atomicity
|
|
@section Atomicity of Pipe I/O
|
|
|
|
Reading or writing pipe data is @dfn{atomic} if the size of data written
|
|
is not greater than @code{PIPE_BUF}. This means that the data transfer
|
|
seems to be an instantaneous unit, in that nothing else in the system
|
|
can observe a state in which it is partially complete. Atomic I/O may
|
|
not begin right away (it may need to wait for buffer space or for data),
|
|
but once it does begin it finishes immediately.
|
|
|
|
Reading or writing a larger amount of data may not be atomic; for
|
|
example, output data from other processes sharing the descriptor may be
|
|
interspersed. Also, once @code{PIPE_BUF} characters have been written,
|
|
further writes will block until some characters are read.
|
|
|
|
@xref{Limits for Files}, for information about the @code{PIPE_BUF}
|
|
parameter.
|