Misc cleanups.
[kopensolaris-gnu/glibc.git] / manual / pipe.texi
1 @node Pipes and FIFOs, Sockets, File System Interface, Top
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; it generates a
22 @code{SIGPIPE} signal and fails with error code @code{EPIPE} if you
23 handle the signal.
24
25 Neither pipes nor FIFO special files allow file positioning.  Both
26 reading and writing operations happen sequentially; reading from the
27 beginning of the file and writing at the end.
28
29 @menu
30 * Creating a Pipe::             Making a pipe with the @code{pipe} function.
31 * Pipe to a Subprocess::        Using a pipe to communicate with a
32                                  child process.
33 * FIFO Special Files::          Making a FIFO special file.
34 * Pipe Atomicity::              When pipe (or FIFO) I/O is atomic.
35 @end menu
36
37 @node Creating a Pipe
38 @section Creating a Pipe
39 @cindex creating a pipe
40 @cindex opening a pipe
41 @cindex interprocess communication, with pipes
42
43 The primitive for creating a pipe is the @code{pipe} function.  This
44 creates both the reading and writing ends of the pipe.  It is not very
45 useful for a single process to use a pipe to talk to itself.  In typical
46 use, a process creates a pipe just before it forks one or more child
47 processes (@pxref{Creating a Process}).  The pipe is then used for
48 communication either between the parent or child processes, or between
49 two sibling processes.
50
51 The @code{pipe} function is declared in the header file
52 @file{unistd.h}.
53 @pindex unistd.h
54
55 @comment unistd.h
56 @comment POSIX.1
57 @deftypefun int pipe (int @var{filedes}@t{[2]})
58 The @code{pipe} function creates a pipe and puts the file descriptors
59 for the reading and writing ends of the pipe (respectively) into
60 @code{@var{filedes}[0]} and @code{@var{filedes}[1]}.
61
62 An easy way to remember that the input end comes first is that file
63 descriptor @code{0} is standard input, and file descriptor @code{1} is
64 standard output.
65
66 If successful, @code{pipe} returns a value of @code{0}.  On failure,
67 @code{-1} is returned.  The following @code{errno} error conditions are
68 defined for this function:
69
70 @table @code
71 @item EMFILE
72 The process has too many files open.
73
74 @item ENFILE
75 There are too many open files in the entire system.  @xref{Error Codes},
76 for more information about @code{ENFILE}.
77 @end table
78 @end deftypefun
79
80 Here is an example of a simple program that creates a pipe.  This program
81 uses the @code{fork} function (@pxref{Creating a Process}) to create
82 a child process.  The parent process writes data to the pipe, which is
83 read by the child process.
84
85 @example
86 @include pipe.c.texi
87 @end example
88
89 @node Pipe to a Subprocess
90 @section Pipe to a Subprocess
91 @cindex creating a pipe to a subprocess
92 @cindex pipe to a subprocess
93 @cindex filtering i/o through subprocess
94
95 A common use of pipes is to send data to or receive data from a program
96 being run as subprocess.  One way of doing this is by using a combination of
97 @code{pipe} (to create the pipe), @code{fork} (to create the subprocess),
98 @code{dup2} (to force the subprocess to use the pipe as its standard input
99 or output channel), and @code{exec} (to execute the new program).  Or,
100 you can use @code{popen} and @code{pclose}.
101
102 The advantage of using @code{popen} and @code{pclose} is that the
103 interface is much simpler and easier to use.  But it doesn't offer as
104 much flexibility as using the low-level functions directly.
105
106 @comment stdio.h
107 @comment POSIX.2, SVID, BSD
108 @deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode})
109 The @code{popen} function is closely related to the @code{system}
110 function; see @ref{Running a Command}.  It executes the shell command
111 @var{command} as a subprocess.  However, instead of waiting for the
112 command to complete, it creates a pipe to the subprocess and returns a
113 stream that corresponds to that pipe.
114
115 If you specify a @var{mode} argument of @code{"r"}, you can read from the 
116 stream to retrieve data from the standard output channel of the subprocess.
117 The subprocess inherits its standard input channel from the parent process.
118
119 Similarly, if you specify a @var{mode} argument of @code{"w"}, you can
120 write to the stream to send data to the standard input channel of the
121 subprocess.  The subprocess inherits its standard output channel from
122 the parent process.
123
124 In the event of an error, @code{popen} returns a null pointer.  This
125 might happen if the pipe or stream cannot be created, if the subprocess
126 cannot be forked, or if the program cannot be executed.
127 @end deftypefun
128
129 @comment stdio.h
130 @comment POSIX.2, SVID, BSD
131 @deftypefun int pclose (FILE *@var{stream})
132 The @code{pclose} function is used to close a stream created by @code{popen}.
133 It waits for the child process to terminate and returns its status value,
134 as for the @code{system} function.
135 @end deftypefun
136
137 Here is an example showing how to use @code{popen} and @code{pclose} to
138 filter output through another program, in this case the paging program
139 @code{more}.
140
141 @example
142 @include popen.c.texi
143 @end example
144
145 @node FIFO Special Files
146 @section FIFO Special Files
147 @cindex creating a FIFO special file
148 @cindex interprocess communication, with FIFO
149
150 A FIFO special file is similar to a pipe, except that it is created in a
151 different way.  Instead of being an anonymous communications channel, a
152 FIFO special file is entered into the file system by calling
153 @code{mkfifo}.
154
155 Once you have created a FIFO special file in this way, any process can
156 open it for reading or writing, in the same way as an ordinary file.
157 However, it has to be open at both ends simultaneously before you can
158 proceed to do any input or output operations on it.  Opening a FIFO for
159 reading normally blocks until some other process opens the same FIFO for
160 writing, and vice versa.
161
162 The @code{mkfifo} function is declared in the header file
163 @file{sys/stat.h}.
164 @pindex sys/stat.h
165
166 @comment sys/stat.h
167 @comment POSIX.1
168 @deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode})
169 The @code{mkfifo} function makes a FIFO special file with name
170 @var{filename}.  The @var{mode} argument is used to set the file's
171 permissions; see @ref{Setting Permissions}.
172
173 The normal, successful return value from @code{mkfifo} is @code{0}.  In
174 the case of an error, @code{-1} is returned.  In addition to the usual
175 file name syntax errors (@pxref{File Name Errors}), the following
176 @code{errno} error conditions are defined for this function:
177
178 @table @code
179 @item EEXIST
180 The named file already exists.
181
182 @item ENOSPC
183 The directory or file system cannot be extended.
184
185 @item EROFS
186 The directory that would contain the file resides on a read-only file
187 system.
188 @end table
189 @end deftypefun
190
191 @node Pipe Atomicity
192 @section Atomicity of Pipe I/O
193
194 Reading or writing pipe data is @dfn{atomic} if the size of data written
195 is less than @code{PIPE_BUF}.  This means that the data transfer seems
196 to be an instantaneous unit, in that nothing else in the system can
197 observe a state in which it is partially complete.  Atomic I/O may not
198 begin right away (it may need to wait for buffer space or for data), but
199 once it does begin, it finishes immediately.
200
201 Reading or writing a larger amount of data may not be atomic; for
202 example, output data from other processes sharing the descriptor may be
203 interspersed.
204
205 @xref{Limits for Files}, for information about the @code{PIPE_BUF}
206 parameter.