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