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