(Feature Test Macros): Add _POSIX_C_SOURCE definition.
[kopensolaris-gnu/glibc.git] / manual / pipe.texi
index e16bed3..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
@@ -57,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:
@@ -66,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
 
@@ -75,9 +83,9 @@ 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
 @section 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,13 +135,13 @@ 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
 @section FIFO Special Files
@@ -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
@@ -185,15 +193,16 @@ system.
 @section Atomicity of Pipe I/O
 
 Reading or writing pipe data is @dfn{atomic} if the size of data written
-is less 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.
+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.
+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.