diff options
Diffstat (limited to 'manual/pipe.texi')
| -rw-r--r-- | manual/pipe.texi | 319 |
1 files changed, 0 insertions, 319 deletions
diff --git a/manual/pipe.texi b/manual/pipe.texi deleted file mode 100644 index 2d7e30e796..0000000000 --- a/manual/pipe.texi +++ /dev/null @@ -1,319 +0,0 @@ -@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. |