(Feature Test Macros): Add _POSIX_C_SOURCE definition.
[kopensolaris-gnu/glibc.git] / manual / pipe.texi
index 9bb0faa..274b93d 100644 (file)
@@ -1,34 +1,44 @@
-@node Pipes and FIFOs
+@node Pipes and FIFOs, Sockets, File System Interface, Top
 @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.
+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 is an ordinary file with a name.
+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.
+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
 @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
@@ -39,13 +49,20 @@ 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>}.
+@file{unistd.h}.
+@pindex unistd.h
 
-@deftypefun int pipe (int @var{filedes}[2])
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int pipe (int @var{filedes}@t{[2]})
 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:
@@ -55,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
 
@@ -64,69 +83,15 @@ 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)) @{
-    fprintf (stderr, "Pipe failed.\n");
-    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.} */
-    fprintf (stderr, "Fork failed.\n");
-    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
+@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 subprocess.  One way of doing this is by using a combination of
@@ -139,14 +104,16 @@ 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})
 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.
 
@@ -160,52 +127,53 @@ 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})
 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) {
-    fprintf (stderr, "Could not run more.\n");
-    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
+@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>}.
+@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})
 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
@@ -221,10 +189,20 @@ system.
 @end table
 @end deftypefun
 
-Once a FIFO special file has been created, 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.
+@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.