Miscellaneous corrections after 1st proofreading.
[kopensolaris-gnu/glibc.git] / manual / pipe.texi
1 @node Pipes and FIFOs, Sockets, File System Interface, Top
2 @chapter Pipes and FIFOs
3
4 @cindex pipe
5 A @dfn{pipe} is a mechanism for interprocess communication; data written
6 to the pipe by one process can be read by another process.  The data is
7 handled in a first-in, first-out (FIFO) order.  The pipe has no name; it
8 is created for one use and both ends must be inherited from the single
9 process which created the pipe.
10
11 @cindex FIFO special file
12 A @dfn{FIFO special file} is similar to a pipe, but instead of being an
13 anonymous, temporary connection, a FIFO has a name or names like any
14 other file.  Processes open the FIFO by name in order to communicate
15 through it.
16
17 A pipe or FIFO has to be open at both ends simultaneously.  If you read
18 from a pipe or FIFO file that doesn't have any processes writing to it
19 (perhaps because they have all closed the file, or exited), the read
20 returns end-of-file.  Writing to a pipe or FIFO that doesn't have a
21 reading process is treated as an error condition.
22 @c !!! is this really true?  what about SIGPIPE?
23
24 Neither pipes nor FIFO special files allow file positioning.  Both
25 reading and writing operations happen sequentially; reading from the
26 beginning of the file and writing at the end.
27
28 @menu
29 * Creating a Pipe::             Making a pipe with the @code{pipe} function.
30 * Pipe to a Subprocess::        Using a pipe to communicate with a
31                                  child process.
32 * FIFO Special Files::          Making a FIFO special file.
33 * Pipe Atomicity::              When pipe (or FIFO) I/O is atomic.
34 @end menu
35
36 @node Creating a Pipe
37 @section Creating a Pipe
38 @cindex creating a pipe
39 @cindex opening a pipe
40 @cindex interprocess communication, with pipes
41
42 The primitive for creating a pipe is the @code{pipe} function.  This
43 creates both the reading and writing ends of the pipe.  It is not very
44 useful for a single process to use a pipe to talk to itself.  In typical
45 use, a process creates a pipe just before it forks one or more child
46 processes (@pxref{Creating a Process}).  The pipe is then used for
47 communication either between the parent or child processes, or between
48 two sibling processes.
49
50 The @code{pipe} function is declared in the header file
51 @file{unistd.h}.
52 @pindex unistd.h
53
54 @comment unistd.h
55 @comment POSIX.1
56 @deftypefun int pipe (int @var{filedes}@t{[2]})
57 The @code{pipe} function creates a pipe and puts the file descriptors
58 for the reading and writing ends of the pipe (respectively) into
59 @code{@var{filedes}[0]} and @code{@var{filedes}[1]}.
60 @c !!! say something like:
61 An easy way to remember which element is which is that file descriptor
62 @code{0} is standard input, and file descriptor @code{1} is standard
63 output.  You can use @code{@var{filedes}[STDIN_FILENO]} and
64 @code{@var{filedes}[STDOUT_FILENO]} to help you remember.
65
66 If successful, @code{pipe} returns a value of @code{0}.  On failure,
67 @code{-1} is returned.  The following @code{errno} error conditions are
68 defined for this function:
69
70 @table @code
71 @item EMFILE
72 The process has too many files open.
73
74 @item ENFILE
75 The system has too many files open.
76 @c !!! this will never happen in GNU.  probably should say somewhere (in
77 @c EMFILE description in errno.texinfo?) that everything that can get
78 @c EMFILE can also get ENFILE in Unix, but not in GNU.
79 @end table
80 @end deftypefun
81
82 Here is an example of a simple program that creates a pipe.  This program
83 uses the @code{fork} function (@pxref{Creating a Process}) to create
84 a child process.  The parent process writes data to the pipe, which is
85 read by the child process.
86
87 @example
88 @include pipe.c.texi
89 @end example
90
91 @node Pipe to a Subprocess
92 @section Pipe to a Subprocess
93 @cindex creating a pipe to a subprocess
94 @cindex pipe to a subprocess
95 @cindex filtering i/o through subprocess
96
97 A common use of pipes is to send data to or receive data from a program
98 being run as subprocess.  One way of doing this is by using a combination of
99 @code{pipe} (to create the pipe), @code{fork} (to create the subprocess),
100 @code{dup2} (to force the subprocess to use the pipe as its standard input
101 or output channel), and @code{exec} (to execute the new program).  Or,
102 you can use @code{popen} and @code{pclose}.
103
104 The advantage of using @code{popen} and @code{pclose} is that the
105 interface is much simpler and easier to use.  But it doesn't offer as
106 much flexibility as using the low-level functions directly.
107
108 @comment stdio.h
109 @comment POSIX.2, SVID, BSD
110 @deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode})
111 The @code{popen} function is closely related to the @code{system}
112 function; see @ref{Running a Command}.  It executes the shell command
113 @var{command} as a subprocess.  However, instead of waiting for the
114 command to complete, it creates a pipe to the subprocess and returns a
115 stream that corresponds to that pipe.
116
117 If you specify a @var{mode} argument of @code{"r"}, you can read from the 
118 stream to retrieve data from the standard output channel of the subprocess.
119 The subprocess inherits its standard input channel from the parent process.
120
121 Similarly, if you specify a @var{mode} argument of @code{"w"}, you can
122 write to the stream to send data to the standard input channel of the
123 subprocess.  The subprocess inherits its standard output channel from
124 the parent process.
125
126 In the event of an error, @code{popen} returns a null pointer.  This
127 might happen if the pipe or stream cannot be created, if the subprocess
128 cannot be forked, or if the program cannot be executed.
129 @end deftypefun
130
131 @comment stdio.h
132 @comment POSIX.2, SVID, BSD
133 @deftypefun int pclose (FILE *@var{stream})
134 The @code{pclose} function is used to close a stream created by @code{popen}.
135 It waits for the child process to terminate and returns its status value,
136 as for the @code{system} function.
137 @end deftypefun
138
139 Here is an example showing how to use @code{popen} and @code{pclose} to
140 filter output through another program, in this case the paging program
141 @code{more}.
142
143 @example
144 @include popen.c.texi
145 @end example
146
147 @node FIFO Special Files
148 @section FIFO Special Files
149 @cindex creating a FIFO special file
150 @cindex interprocess communication, with FIFO
151
152 A FIFO special file is similar to a pipe, except that it is created in a
153 different way.  Instead of being an anonymous communications channel, a
154 FIFO special file is entered into the file system by calling
155 @code{mkfifo}.
156
157 Once you have created a FIFO special file in this way, any process can
158 open it for reading or writing, in the same way as an ordinary file.
159 However, it has to be open at both ends simultaneously before you can
160 proceed to do any input or output operations on it.  Opening a FIFO for
161 reading normally blocks until some other process opens the same FIFO for
162 writing, and vice versa.
163
164 The @code{mkfifo} function is declared in the header file
165 @file{sys/stat.h}.
166 @pindex sys/stat.h
167
168 @comment sys/stat.h
169 @comment POSIX.1
170 @deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode})
171 The @code{mkfifo} function makes a FIFO special file with name
172 @var{filename}.  The @var{mode} argument is used to set the file's
173 permissions; see @ref{Setting Permissions}.
174
175 The normal, successful return value from @code{mkfifo} is @code{0}.  In
176 the case of an error, @code{-1} is returned.  In addition to the usual
177 file name syntax errors (@pxref{File Name Errors}), the following
178 @code{errno} error conditions are defined for this function:
179
180 @table @code
181 @item EEXIST
182 The named file already exists.
183
184 @item ENOSPC
185 The directory or file system cannot be extended.
186
187 @item EROFS
188 The directory that would contain the file resides on a read-only file
189 system.
190 @end table
191 @end deftypefun
192
193 @node Pipe Atomicity
194 @section Atomicity of Pipe I/O
195
196 Reading or writing pipe data is @dfn{atomic} if the size of data written
197 is less than @code{PIPE_BUF}.  This means that the data transfer seems
198 to be an instantaneous unit, in that nothing else in the system can
199 observe a state in which it is partially complete.  Atomic I/O may not
200 begin right away (it may need to wait for buffer space or for data), but
201 once it does begin, it finishes immediately.
202
203 Reading or writing a larger amount of data may not be atomic; for
204 example, output data from other processes sharing the descriptor may be
205 interspersed.
206
207 @xref{Limits for Files}, for information about the @code{PIPE_BUF}
208 parameter.