]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
a9cd9cb7 | 4 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
5 | .\" Redistribution and use in source and binary forms, with or without |
6 | .\" modification, are permitted provided that the following conditions | |
7 | .\" are met: | |
8 | .\" 1. Redistributions of source code must retain the above copyright | |
9 | .\" notice, this list of conditions and the following disclaimer. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. All advertising materials mentioning features or use of this software | |
14 | .\" must display the following acknowledgement: | |
15 | .\" This product includes software developed by the University of | |
16 | .\" California, Berkeley and its contributors. | |
17 | .\" 4. Neither the name of the University nor the names of its contributors | |
18 | .\" may be used to endorse or promote products derived from this software | |
19 | .\" without specific prior written permission. | |
20 | .\" | |
21 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
31 | .\" SUCH DAMAGE. | |
8c9302dc | 32 | .\" %%%LICENSE_END |
fea681da MK |
33 | .\" |
34 | .\" @(#)popen.3 6.4 (Berkeley) 4/30/91 | |
35 | .\" | |
36 | .\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu | |
37 | .\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de) | |
38 | .\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) | |
39 | .\" | |
4b8c67d9 | 40 | .TH POPEN 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da | 41 | .SH NAME |
2f81a9f3 | 42 | popen, pclose \- pipe stream to or from a process |
fea681da | 43 | .SH SYNOPSIS |
0f200f07 | 44 | .nf |
fea681da | 45 | .B #include <stdio.h> |
68e4db0a | 46 | .PP |
fea681da | 47 | .BI "FILE *popen(const char *" command ", const char *" type ); |
68e4db0a | 48 | .PP |
fea681da | 49 | .BI "int pclose(FILE *" stream ); |
0f200f07 | 50 | .fi |
68e4db0a | 51 | .PP |
0f200f07 MK |
52 | .in -4n |
53 | Feature Test Macro Requirements for glibc (see | |
54 | .BR feature_test_macros (7)): | |
55 | .ad l | |
56 | .in | |
68e4db0a | 57 | .PP |
0f200f07 MK |
58 | .BR popen (), |
59 | .BR pclose (): | |
0dc41197 | 60 | .RS 4 |
d59161f9 MK |
61 | _POSIX_C_SOURCE\ >=\ 2 |
62 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE | |
0dc41197 | 63 | .RE |
0f200f07 | 64 | .ad b |
fea681da MK |
65 | .SH DESCRIPTION |
66 | The | |
63aa9df0 | 67 | .BR popen () |
fea681da | 68 | function opens a process by creating a pipe, forking, and invoking the |
c13182ef MK |
69 | shell. |
70 | Since a pipe is by definition unidirectional, the | |
fea681da MK |
71 | .I type |
72 | argument may specify only reading or writing, not both; the resulting | |
73 | stream is correspondingly read-only or write-only. | |
74 | .PP | |
75 | The | |
76 | .I command | |
77 | argument is a pointer to a null-terminated string containing a shell | |
c13182ef MK |
78 | command line. |
79 | This command is passed to | |
fea681da MK |
80 | .I /bin/sh |
81 | using the | |
82 | .B \-c | |
c13182ef | 83 | flag; interpretation, if any, is performed by the shell. |
847e0d88 | 84 | .PP |
c13182ef | 85 | The |
fea681da | 86 | .I type |
28ddfa90 MK |
87 | argument is a pointer to a null-terminated string which must contain |
88 | either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing. | |
67cf694c MK |
89 | Since glibc 2.9, |
90 | this argument can additionally include the letter \(aqe\(aq, | |
91 | which causes the close-on-exec flag | |
e18599c0 | 92 | .RB ( FD_CLOEXEC ) |
67cf694c | 93 | to be set on the underlying file descriptor; |
c5571b61 | 94 | see the description of the |
e18599c0 MK |
95 | .B O_CLOEXEC |
96 | flag in | |
97 | .BR open (2) | |
98 | for reasons why this may be useful. | |
fea681da MK |
99 | .PP |
100 | The return value from | |
63aa9df0 | 101 | .BR popen () |
fea681da MK |
102 | is a normal standard I/O stream in all respects save that it must be closed |
103 | with | |
63aa9df0 | 104 | .BR pclose () |
fea681da | 105 | rather than |
fb186734 | 106 | .BR fclose (3). |
fea681da MK |
107 | Writing to such a stream writes to the standard input of the command; the |
108 | command's standard output is the same as that of the process that called | |
63aa9df0 | 109 | .BR popen (), |
c13182ef | 110 | unless this is altered by the command itself. |
8228dbfe MK |
111 | Conversely, reading from |
112 | the stream reads the command's standard output, and the command's | |
fea681da | 113 | standard input is the same as that of the process that called |
e511ffb6 | 114 | .BR popen (). |
fea681da MK |
115 | .PP |
116 | Note that output | |
e511ffb6 | 117 | .BR popen () |
d7d10e10 | 118 | streams are block buffered by default. |
fea681da MK |
119 | .PP |
120 | The | |
e511ffb6 | 121 | .BR pclose () |
fea681da MK |
122 | function waits for the associated process to terminate and returns the exit |
123 | status of the command as returned by | |
fb186734 | 124 | .BR wait4 (2). |
47297adb | 125 | .SH RETURN VALUE |
ea5bce08 NF |
126 | .BR popen (): |
127 | on success, returns a pointer to an open stream that | |
128 | can be used to read or write to the pipe; | |
129 | if the | |
fea681da MK |
130 | .BR fork (2) |
131 | or | |
132 | .BR pipe (2) | |
ea5bce08 NF |
133 | calls fail, or if the function cannot allocate memory, |
134 | NULL is returned. | |
847e0d88 | 135 | .PP |
ea5bce08 NF |
136 | .BR pclose (): |
137 | on success, returns the exit status of the command; if | |
fea681da MK |
138 | .\" These conditions actually give undefined results, so I commented |
139 | .\" them out. | |
140 | .\" .I stream | |
324633ae | 141 | .\" is not associated with a "popen()ed" command, if |
fea681da | 142 | .\".I stream |
324633ae | 143 | .\" already "pclose()d", or if |
91fe9d5c | 144 | .BR wait4 (2) |
ea5bce08 NF |
145 | returns an error, or some other error is detected, |
146 | \-1 is returned. | |
147 | .PP | |
148 | Both functions set | |
eb204b94 | 149 | .I errno |
ea5bce08 | 150 | to an appropriate value in the case of an error. |
fea681da MK |
151 | .SH ERRORS |
152 | The | |
e511ffb6 | 153 | .BR popen () |
fea681da MK |
154 | function does not set |
155 | .I errno | |
c13182ef MK |
156 | if memory allocation fails. |
157 | If the underlying | |
fb186734 | 158 | .BR fork (2) |
c13182ef | 159 | or |
fb186734 | 160 | .BR pipe (2) |
fea681da MK |
161 | fails, |
162 | .I errno | |
c13182ef MK |
163 | is set appropriately. |
164 | If the | |
fea681da MK |
165 | .I type |
166 | argument is invalid, and this condition is detected, | |
167 | .I errno | |
168 | is set to | |
169 | .BR EINVAL . | |
170 | .PP | |
171 | If | |
63aa9df0 | 172 | .BR pclose () |
fea681da MK |
173 | cannot obtain the child status, |
174 | .I errno | |
175 | is set to | |
176 | .BR ECHILD . | |
8ae2d625 MS |
177 | .SH ATTRIBUTES |
178 | For an explanation of the terms used in this section, see | |
179 | .BR attributes (7). | |
180 | .TS | |
181 | allbox; | |
182 | lbw17 lb lb | |
183 | l l l. | |
184 | Interface Attribute Value | |
185 | T{ | |
186 | .BR popen (), | |
187 | .BR pclose () | |
188 | T} Thread safety MT-Safe | |
189 | .TE | |
847e0d88 | 190 | .sp 1 |
47297adb | 191 | .SH CONFORMING TO |
0ba861e9 | 192 | POSIX.1-2001, POSIX.1-2008. |
847e0d88 | 193 | .PP |
e18599c0 MK |
194 | The \(aqe\(aq value for |
195 | .I type | |
196 | is a Linux extension. | |
fefbc57d MK |
197 | .SH NOTES |
198 | .BR Note : | |
199 | carefully read Caveats in | |
200 | .BR system (3). | |
fea681da MK |
201 | .SH BUGS |
202 | Since the standard input of a command opened for reading shares its seek | |
203 | offset with the process that called | |
63aa9df0 | 204 | .BR popen (), |
fea681da | 205 | if the original process has done a buffered read, the command's input |
c13182ef MK |
206 | position may not be as expected. |
207 | Similarly, the output from a command | |
fea681da | 208 | opened for writing may become intermingled with that of the original |
c13182ef MK |
209 | process. |
210 | The latter can be avoided by calling | |
fea681da MK |
211 | .BR fflush (3) |
212 | before | |
e511ffb6 | 213 | .BR popen (). |
fea681da MK |
214 | .PP |
215 | Failure to execute the shell is indistinguishable from the shell's failure | |
c13182ef MK |
216 | to execute command, or an immediate exit of the command. |
217 | The only hint is an exit status of 127. | |
889829be MK |
218 | .\" .SH HISTORY |
219 | .\" A | |
220 | .\" .BR popen () | |
221 | .\" and a | |
222 | .\" .BR pclose () | |
223 | .\" function appeared in Version 7 AT&T UNIX. | |
47297adb | 224 | .SH SEE ALSO |
fea681da MK |
225 | .BR sh (1), |
226 | .BR fork (2), | |
227 | .BR pipe (2), | |
228 | .BR wait4 (2), | |
229 | .BR fclose (3), | |
230 | .BR fflush (3), | |
231 | .BR fopen (3), | |
232 | .BR stdio (3), | |
233 | .BR system (3) |