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