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