]>
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 | .\" | |
963904cd | 40 | .TH POPEN 3 2010-02-03 "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 MK |
45 | .B #include <stdio.h> |
46 | .sp | |
47 | .BI "FILE *popen(const char *" command ", const char *" type ); | |
48 | .sp | |
49 | .BI "int pclose(FILE *" stream ); | |
0f200f07 MK |
50 | .fi |
51 | .sp | |
52 | .in -4n | |
53 | Feature Test Macro Requirements for glibc (see | |
54 | .BR feature_test_macros (7)): | |
55 | .ad l | |
56 | .in | |
57 | .sp | |
58 | .BR popen (), | |
59 | .BR pclose (): | |
0dc41197 | 60 | .RS 4 |
963904cd | 61 | _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE |
0dc41197 | 62 | .RE |
0f200f07 | 63 | .ad b |
fea681da MK |
64 | .SH DESCRIPTION |
65 | The | |
63aa9df0 | 66 | .BR popen () |
fea681da | 67 | function opens a process by creating a pipe, forking, and invoking the |
c13182ef MK |
68 | shell. |
69 | Since a pipe is by definition unidirectional, the | |
fea681da MK |
70 | .I type |
71 | argument may specify only reading or writing, not both; the resulting | |
72 | stream is correspondingly read-only or write-only. | |
73 | .PP | |
74 | The | |
75 | .I command | |
76 | argument is a pointer to a null-terminated string containing a shell | |
c13182ef MK |
77 | command line. |
78 | This command is passed to | |
fea681da MK |
79 | .I /bin/sh |
80 | using the | |
81 | .B \-c | |
c13182ef MK |
82 | flag; interpretation, if any, is performed by the shell. |
83 | The | |
fea681da | 84 | .I type |
28ddfa90 MK |
85 | argument is a pointer to a null-terminated string which must contain |
86 | either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing. | |
67cf694c MK |
87 | Since glibc 2.9, |
88 | this argument can additionally include the letter \(aqe\(aq, | |
89 | which causes the close-on-exec flag | |
e18599c0 | 90 | .RB ( FD_CLOEXEC ) |
67cf694c | 91 | to be set on the underlying file descriptor; |
c5571b61 | 92 | see the description of the |
e18599c0 MK |
93 | .B O_CLOEXEC |
94 | flag in | |
95 | .BR open (2) | |
96 | for reasons why this may be useful. | |
fea681da MK |
97 | .PP |
98 | The return value from | |
63aa9df0 | 99 | .BR popen () |
fea681da MK |
100 | is a normal standard I/O stream in all respects save that it must be closed |
101 | with | |
63aa9df0 | 102 | .BR pclose () |
fea681da | 103 | rather than |
fb186734 | 104 | .BR fclose (3). |
fea681da MK |
105 | Writing to such a stream writes to the standard input of the command; the |
106 | command's standard output is the same as that of the process that called | |
63aa9df0 | 107 | .BR popen (), |
c13182ef MK |
108 | unless this is altered by the command itself. |
109 | Conversely, reading from a | |
324633ae | 110 | "popened" stream reads the command's standard output, and the command's |
fea681da | 111 | standard input is the same as that of the process that called |
e511ffb6 | 112 | .BR popen (). |
fea681da MK |
113 | .PP |
114 | Note that output | |
e511ffb6 | 115 | .BR popen () |
fea681da MK |
116 | streams are fully buffered by default. |
117 | .PP | |
118 | The | |
e511ffb6 | 119 | .BR pclose () |
fea681da MK |
120 | function waits for the associated process to terminate and returns the exit |
121 | status of the command as returned by | |
fb186734 | 122 | .BR wait4 (2). |
47297adb | 123 | .SH RETURN VALUE |
fea681da | 124 | The |
e511ffb6 | 125 | .BR popen () |
8478ee02 | 126 | function returns NULL if the |
fea681da MK |
127 | .BR fork (2) |
128 | or | |
129 | .BR pipe (2) | |
130 | calls fail, or if it cannot allocate memory. | |
131 | .PP | |
132 | The | |
e511ffb6 | 133 | .BR pclose () |
fea681da MK |
134 | function returns \-1 if |
135 | .\" These conditions actually give undefined results, so I commented | |
136 | .\" them out. | |
137 | .\" .I stream | |
324633ae | 138 | .\" is not associated with a "popen()ed" command, if |
fea681da | 139 | .\".I stream |
324633ae | 140 | .\" already "pclose()d", or if |
91fe9d5c | 141 | .BR wait4 (2) |
fea681da MK |
142 | returns an error, or some other error is detected. |
143 | .SH ERRORS | |
144 | The | |
e511ffb6 | 145 | .BR popen () |
fea681da MK |
146 | function does not set |
147 | .I errno | |
c13182ef MK |
148 | if memory allocation fails. |
149 | If the underlying | |
fb186734 | 150 | .BR fork (2) |
c13182ef | 151 | or |
fb186734 | 152 | .BR pipe (2) |
fea681da MK |
153 | fails, |
154 | .I errno | |
c13182ef MK |
155 | is set appropriately. |
156 | If the | |
fea681da MK |
157 | .I type |
158 | argument is invalid, and this condition is detected, | |
159 | .I errno | |
160 | is set to | |
161 | .BR EINVAL . | |
162 | .PP | |
163 | If | |
63aa9df0 | 164 | .BR pclose () |
fea681da MK |
165 | cannot obtain the child status, |
166 | .I errno | |
167 | is set to | |
168 | .BR ECHILD . | |
47297adb | 169 | .SH CONFORMING TO |
68e1685c | 170 | POSIX.1-2001. |
e18599c0 MK |
171 | |
172 | The \(aqe\(aq value for | |
173 | .I type | |
174 | is a Linux extension. | |
fea681da MK |
175 | .SH BUGS |
176 | Since the standard input of a command opened for reading shares its seek | |
177 | offset with the process that called | |
63aa9df0 | 178 | .BR popen (), |
fea681da | 179 | if the original process has done a buffered read, the command's input |
c13182ef MK |
180 | position may not be as expected. |
181 | Similarly, the output from a command | |
fea681da | 182 | opened for writing may become intermingled with that of the original |
c13182ef MK |
183 | process. |
184 | The latter can be avoided by calling | |
fea681da MK |
185 | .BR fflush (3) |
186 | before | |
e511ffb6 | 187 | .BR popen (). |
fea681da MK |
188 | .PP |
189 | Failure to execute the shell is indistinguishable from the shell's failure | |
c13182ef MK |
190 | to execute command, or an immediate exit of the command. |
191 | The only hint is an exit status of 127. | |
889829be MK |
192 | .\" .SH HISTORY |
193 | .\" A | |
194 | .\" .BR popen () | |
195 | .\" and a | |
196 | .\" .BR pclose () | |
197 | .\" function appeared in Version 7 AT&T UNIX. | |
47297adb | 198 | .SH SEE ALSO |
fea681da MK |
199 | .BR sh (1), |
200 | .BR fork (2), | |
201 | .BR pipe (2), | |
202 | .BR wait4 (2), | |
203 | .BR fclose (3), | |
204 | .BR fflush (3), | |
205 | .BR fopen (3), | |
206 | .BR stdio (3), | |
207 | .BR system (3) |