(Feature Test Macros): Add _POSIX_C_SOURCE definition.
[kopensolaris-gnu/glibc.git] / manual / pipe.texi
index b482cc3..274b93d 100644 (file)
@@ -1,4 +1,4 @@
-@node Pipes and FIFOs
+@node Pipes and FIFOs, Sockets, File System Interface, Top
 @chapter Pipes and FIFOs
 
 @cindex pipe
@@ -18,17 +18,20 @@ 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
 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
+* 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.
+* FIFO Special Files::          Making a FIFO special file.
+* Pipe Atomicity::             When pipe (or FIFO) I/O is atomic.
 @end menu
 
 @node Creating 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,70 +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
-#include <sys/types.h>
-#include <unistd.h>
-#include <stdio.h>
-#include <stdlib.h>
-
-/* @r{Read characters from the pipe and echo them to stdout.}  */
-
-void 
-read_from_pipe (int file)
-@{
-  FILE *stream;
-  int c;
-  stream = fdopen (file, "r");
-  while ((c = fgetc (stream)) != EOF)
-    putchar (c);
-  fclose (stream);
-@}
-
-/* @r{Write some random text to the pipe.} */
-
-void 
-write_to_pipe (int file)
-@{
-  FILE *stream;
-  stream = fdopen (file, "w");
-  fprintf (stream, "hello, world!\n");
-  fprintf (stream, "goodbye, world!\n");
-  fclose (stream);
-@}
-
-
-void
-main (void)
-@{
-  pid_t pid;
-  int mypipe[2];
-
-  /* @r{Create the pipe.} */
-  if (pipe (mypipe)) @{
-    perror ("pipe failed");
-    exit (EXIT_FAILURE);
-    @}
-
-  /* @r{Create the child process.} */
-  pid = fork ();
-  if (pid == (pid_t) 0) @{
-    /* @r{This is the child process.} */
-    read_from_pipe (mypipe[0]);
-    exit (EXIT_SUCCESS);
-    @}
-  else if (pid < (pid_t) 0) @{
-    /* @r{The fork failed.} */
-    perror ("fork failed");
-    exit (EXIT_FAILURE);
-    @}
-  else @{
-    /* @r{This is the parent process.} */
-    write_to_pipe (mypipe[1]);
-    exit (EXIT_SUCCESS);
-    @}
-@}
-@end example
-
+@smallexample
+@include pipe.c.texi
+@end smallexample
 
 @node Pipe to a Subprocess
 @section Pipe to a Subprocess
@@ -157,15 +105,15 @@ 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, GNU
+@comment POSIX.2, SVID, BSD
 @deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode})
 The @code{popen} function is closely related to the @code{system}
-function; @pxref{Running a Command}.  It executes the shell command
+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 
+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.
 
@@ -180,39 +128,20 @@ cannot be forked, or if the program cannot be executed.
 @end deftypefun
 
 @comment stdio.h
-@comment POSIX.2, SVID, BSD, GNU
+@comment POSIX.2, SVID, BSD
 @deftypefun int pclose (FILE *@var{stream})
 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{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
-#include <stdio.h>
-#include <stdlib.h>
-
-void 
-main (void)
-@{
-  FILE *output;
-
-  output = popen ("more", "w");
-  if (!output) @{
-    perror ("popen failed, running `more'");
-    exit (EXIT_FAILURE);
-    @}
-  @dots{}
-  fprintf (output, @dots{});
-  @dots{}
-  pclose (output);
-  exit (EXIT_SUCCESS);
-@}
-@end example
-
+@smallexample
+@include popen.c.texi
+@end smallexample
 
 @node FIFO Special Files
 @section FIFO Special Files
@@ -240,11 +169,11 @@ The @code{mkfifo} function is declared in the header file
 @deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode})
 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; @pxref{Assigning File Permissions}.
+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
@@ -260,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.