(Feature Test Macros): Add _POSIX_C_SOURCE definition.
[kopensolaris-gnu/glibc.git] / manual / pipe.texi
index 875b3b9..274b93d 100644 (file)
@@ -18,7 +18,9 @@ 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.
+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
@@ -29,9 +31,10 @@ beginning of the file and writing at the end.
 * 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, Pipe to a Subprocess,  , Pipes and FIFOs
+@node Creating a Pipe
 @section Creating a Pipe
 @cindex creating a pipe
 @cindex opening a pipe
@@ -56,6 +59,10 @@ 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:
@@ -65,7 +72,9 @@ defined for this function:
 The process has too many files open.
 
 @item ENFILE
-The system has too many files open.
+There are too many open files in the entire system.  @xref{Error Codes},
+for more information about @code{ENFILE}.  This error never occurs in
+the GNU system.
 @end table
 @end deftypefun
 
@@ -74,12 +83,11 @@ 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.
 
-@example
+@smallexample
 @include pipe.c.texi
-@end example
-
+@end smallexample
 
-@node Pipe to a Subprocess, FIFO Special Files, Creating a Pipe, Pipes and FIFOs
+@node Pipe to a Subprocess
 @section Pipe to a Subprocess
 @cindex creating a pipe to a subprocess
 @cindex pipe to a subprocess
@@ -105,7 +113,7 @@ function; see @ref{Running a Command}.  It executes the shell command
 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 
+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.
 
@@ -127,15 +135,15 @@ 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{popen} to
+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}.
 
-@example
+@smallexample
 @include popen.c.texi
-@end example
+@end smallexample
 
-@node FIFO Special Files,  , Pipe to a Subprocess, Pipes and FIFOs
+@node FIFO Special Files
 @section FIFO Special Files
 @cindex creating a FIFO special file
 @cindex interprocess communication, with FIFO
@@ -165,7 +173,7 @@ 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 syntax errors (@pxref{File Name Errors}), the following
+file name errors (@pxref{File Name Errors}), the following
 @code{errno} error conditions are defined for this function:
 
 @table @code
@@ -181,4 +189,20 @@ 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.