miscellaneous edits
[kopensolaris-gnu/glibc.git] / manual / pipe.texi
1 @node Pipes and FIFOs
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
23 Neither pipes nor FIFO special files allow file positioning.  Both
24 reading and writing operations happen sequentially; reading from the
25 beginning of the file and writing at the end.
26
27 @menu
28 * Creating a Pipe::             Making a pipe with the @code{pipe} function.
29 * Pipe to a Subprocess::        Using a pipe to communicate with a
30                                  child process.
31 * FIFO Special Files::          Making a FIFO special file.
32 @end menu
33
34 @node Creating a Pipe
35 @section Creating a Pipe
36 @cindex creating a pipe
37 @cindex opening a pipe
38 @cindex interprocess communication, with pipes
39
40 The primitive for creating a pipe is the @code{pipe} function.  This
41 creates both the reading and writing ends of the pipe.  It is not very
42 useful for a single process to use a pipe to talk to itself.  In typical
43 use, a process creates a pipe just before it forks one or more child
44 processes (@pxref{Creating a Process}).  The pipe is then used for
45 communication either between the parent or child processes, or between
46 two sibling processes.
47
48 The @code{pipe} function is declared in the header file
49 @file{unistd.h}.
50 @pindex unistd.h
51
52 @comment unistd.h
53 @comment POSIX.1
54 @deftypefun int pipe (int @var{filedes}@t{[2]})
55 The @code{pipe} function creates a pipe and puts the file descriptors
56 for the reading and writing ends of the pipe (respectively) into
57 @code{@var{filedes}[0]} and @code{@var{filedes}[1]}.
58
59 If successful, @code{pipe} returns a value of @code{0}.  On failure,
60 @code{-1} is returned.  The following @code{errno} error conditions are
61 defined for this function:
62
63 @table @code
64 @item EMFILE
65 The process has too many files open.
66
67 @item ENFILE
68 The system has too many files open.
69 @end table
70 @end deftypefun
71
72 Here is an example of a simple program that creates a pipe.  This program
73 uses the @code{fork} function (@pxref{Creating a Process}) to create
74 a child process.  The parent process writes data to the pipe, which is
75 read by the child process.
76
77 @example
78 #include <sys/types.h>
79 #include <unistd.h>
80 #include <stdio.h>
81 #include <stdlib.h>
82
83 /* @r{Read characters from the pipe and echo them to stdout.}  */
84
85 void 
86 read_from_pipe (int file)
87 @{
88   FILE *stream;
89   int c;
90   stream = fdopen (file, "r");
91   while ((c = fgetc (stream)) != EOF)
92     putchar (c);
93   fclose (stream);
94 @}
95
96 /* @r{Write some random text to the pipe.} */
97
98 void 
99 write_to_pipe (int file)
100 @{
101   FILE *stream;
102   stream = fdopen (file, "w");
103   fprintf (stream, "hello, world!\n");
104   fprintf (stream, "goodbye, world!\n");
105   fclose (stream);
106 @}
107
108
109 void
110 main (void)
111 @{
112   pid_t pid;
113   int mypipe[2];
114
115   /* @r{Create the pipe.} */
116   if (pipe (mypipe)) @{
117     perror ("pipe failed");
118     exit (EXIT_FAILURE);
119     @}
120
121   /* @r{Create the child process.} */
122   pid = fork ();
123   if (pid == (pid_t) 0) @{
124     /* @r{This is the child process.} */
125     read_from_pipe (mypipe[0]);
126     exit (EXIT_SUCCESS);
127     @}
128   else if (pid < (pid_t) 0) @{
129     /* @r{The fork failed.} */
130     perror ("fork failed");
131     exit (EXIT_FAILURE);
132     @}
133   else @{
134     /* @r{This is the parent process.} */
135     write_to_pipe (mypipe[1]);
136     exit (EXIT_SUCCESS);
137     @}
138 @}
139 @end example
140
141
142 @node Pipe to a Subprocess
143 @section Pipe to a Subprocess
144 @cindex creating a pipe to a subprocess
145 @cindex pipe to a subprocess
146 @cindex filtering i/o through subprocess
147
148 A common use of pipes is to send data to or receive data from a program
149 being run as subprocess.  One way of doing this is by using a combination of
150 @code{pipe} (to create the pipe), @code{fork} (to create the subprocess),
151 @code{dup2} (to force the subprocess to use the pipe as its standard input
152 or output channel), and @code{exec} (to execute the new program).  Or,
153 you can use @code{popen} and @code{pclose}.
154
155 The advantage of using @code{popen} and @code{pclose} is that the
156 interface is much simpler and easier to use.  But it doesn't offer as
157 much flexibility as using the low-level functions directly.
158
159 @comment stdio.h
160 @comment POSIX.2, SVID, BSD, GNU
161 @deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode})
162 The @code{popen} function is closely related to the @code{system}
163 function; @pxref{Running a Command}.  It executes the shell command
164 @var{command} as a subprocess.  However, instead of waiting for the
165 command to complete, it creates a pipe to the subprocess and returns a
166 stream that corresponds to that pipe.
167
168 If you specify a @var{mode} argument of @code{"r"}, you can read from the 
169 stream to retrieve data from the standard output channel of the subprocess.
170 The subprocess inherits its standard input channel from the parent process.
171
172 Similarly, if you specify a @var{mode} argument of @code{"w"}, you can
173 write to the stream to send data to the standard input channel of the
174 subprocess.  The subprocess inherits its standard output channel from
175 the parent process.
176
177 In the event of an error, @code{popen} returns a null pointer.  This
178 might happen if the pipe or stream cannot be created, if the subprocess
179 cannot be forked, or if the program cannot be executed.
180 @end deftypefun
181
182 @comment stdio.h
183 @comment POSIX.2, SVID, BSD, GNU
184 @deftypefun int pclose (FILE *@var{stream})
185 The @code{pclose} function is used to close a stream created by @code{popen}.
186 It waits for the child process to terminate and returns its status value,
187 as for the @code{system} function.
188 @end deftypefun
189
190 Here is an example showing how to use @code{popen} and @code{popen} to
191 filter output through another program, in this case the paging program
192 @code{more}.
193
194 @example
195 #include <stdio.h>
196 #include <stdlib.h>
197
198 void 
199 main (void)
200 @{
201   FILE *output;
202
203   output = popen ("more", "w");
204   if (!output) @{
205     perror ("popen failed, running `more'");
206     exit (EXIT_FAILURE);
207     @}
208   @dots{}
209   fprintf (output, @dots{});
210   @dots{}
211   pclose (output);
212   exit (EXIT_SUCCESS);
213 @}
214 @end example
215
216
217 @node FIFO Special Files
218 @section FIFO Special Files
219 @cindex creating a FIFO special file
220 @cindex interprocess communication, with FIFO
221
222 A FIFO special file is similar to a pipe, except that it is created in a
223 different way.  Instead of being an anonymous communications channel, a
224 FIFO special file is entered into the file system by calling
225 @code{mkfifo}.
226
227 Once you have created a FIFO special file in this way, any process can
228 open it for reading or writing, in the same way as an ordinary file.
229 However, it has to be open at both ends simultaneously before you can
230 proceed to do any input or output operations on it.  Opening a FIFO for
231 reading normally blocks until some other process opens the same FIFO for
232 writing, and vice versa.
233
234 The @code{mkfifo} function is declared in the header file
235 @file{sys/stat.h}.
236 @pindex sys/stat.h
237
238 @comment sys/stat.h
239 @comment POSIX.1
240 @deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode})
241 The @code{mkfifo} function makes a FIFO special file with name
242 @var{filename}.  The @var{mode} argument is used to set the file's
243 permissions; @pxref{Assigning File Permissions}.
244
245 The normal, successful return value from @code{mkfifo} is @code{0}.  In
246 the case of an error, @code{-1} is returned.  In addition to the usual
247 file name syntax errors (@pxref{File Name Errors}), the following
248 @code{errno} error conditions are defined for this function:
249
250 @table @code
251 @item EEXIST
252 The named file already exists.
253
254 @item ENOSPC
255 The directory or file system cannot be extended.
256
257 @item EROFS
258 The directory that would contain the file resides on a read-only file
259 system.
260 @end table
261 @end deftypefun
262
263