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