]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
47009d5e | 4 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
5 | .\" |
6 | .\" @(#)popen.3 6.4 (Berkeley) 4/30/91 | |
7 | .\" | |
8 | .\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu | |
9 | .\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de) | |
10 | .\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) | |
11 | .\" | |
4c1c5274 | 12 | .TH popen 3 (date) "Linux man-pages (unreleased)" |
fea681da | 13 | .SH NAME |
2f81a9f3 | 14 | popen, pclose \- pipe stream to or from a process |
a47ec6f6 AC |
15 | .SH LIBRARY |
16 | Standard C library | |
8fc3b2cf | 17 | .RI ( libc ", " \-lc ) |
fea681da | 18 | .SH SYNOPSIS |
0f200f07 | 19 | .nf |
fea681da | 20 | .B #include <stdio.h> |
68e4db0a | 21 | .PP |
fea681da | 22 | .BI "FILE *popen(const char *" command ", const char *" type ); |
fea681da | 23 | .BI "int pclose(FILE *" stream ); |
0f200f07 | 24 | .fi |
68e4db0a | 25 | .PP |
d39ad78f | 26 | .RS -4 |
0f200f07 MK |
27 | Feature Test Macro Requirements for glibc (see |
28 | .BR feature_test_macros (7)): | |
d39ad78f | 29 | .RE |
68e4db0a | 30 | .PP |
0f200f07 MK |
31 | .BR popen (), |
32 | .BR pclose (): | |
9d2adbae | 33 | .nf |
5c10d2c5 | 34 | _POSIX_C_SOURCE >= 2 |
9d2adbae MK |
35 | || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE |
36 | .fi | |
fea681da MK |
37 | .SH DESCRIPTION |
38 | The | |
63aa9df0 | 39 | .BR popen () |
fea681da | 40 | function opens a process by creating a pipe, forking, and invoking the |
c13182ef MK |
41 | shell. |
42 | Since a pipe is by definition unidirectional, the | |
fea681da MK |
43 | .I type |
44 | argument may specify only reading or writing, not both; the resulting | |
45 | stream is correspondingly read-only or write-only. | |
46 | .PP | |
47 | The | |
48 | .I command | |
49 | argument is a pointer to a null-terminated string containing a shell | |
c13182ef MK |
50 | command line. |
51 | This command is passed to | |
fea681da MK |
52 | .I /bin/sh |
53 | using the | |
54 | .B \-c | |
c13182ef | 55 | flag; interpretation, if any, is performed by the shell. |
847e0d88 | 56 | .PP |
c13182ef | 57 | The |
fea681da | 58 | .I type |
28ddfa90 MK |
59 | argument is a pointer to a null-terminated string which must contain |
60 | either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing. | |
67cf694c MK |
61 | Since glibc 2.9, |
62 | this argument can additionally include the letter \(aqe\(aq, | |
63 | which causes the close-on-exec flag | |
e18599c0 | 64 | .RB ( FD_CLOEXEC ) |
67cf694c | 65 | to be set on the underlying file descriptor; |
c5571b61 | 66 | see the description of the |
e18599c0 MK |
67 | .B O_CLOEXEC |
68 | flag in | |
69 | .BR open (2) | |
70 | for reasons why this may be useful. | |
fea681da MK |
71 | .PP |
72 | The return value from | |
63aa9df0 | 73 | .BR popen () |
fea681da MK |
74 | is a normal standard I/O stream in all respects save that it must be closed |
75 | with | |
63aa9df0 | 76 | .BR pclose () |
fea681da | 77 | rather than |
fb186734 | 78 | .BR fclose (3). |
fea681da MK |
79 | Writing to such a stream writes to the standard input of the command; the |
80 | command's standard output is the same as that of the process that called | |
63aa9df0 | 81 | .BR popen (), |
c13182ef | 82 | unless this is altered by the command itself. |
8228dbfe MK |
83 | Conversely, reading from |
84 | the stream reads the command's standard output, and the command's | |
fea681da | 85 | standard input is the same as that of the process that called |
e511ffb6 | 86 | .BR popen (). |
fea681da MK |
87 | .PP |
88 | Note that output | |
e511ffb6 | 89 | .BR popen () |
d7d10e10 | 90 | streams are block buffered by default. |
fea681da MK |
91 | .PP |
92 | The | |
e511ffb6 | 93 | .BR pclose () |
fea681da MK |
94 | function waits for the associated process to terminate and returns the exit |
95 | status of the command as returned by | |
fb186734 | 96 | .BR wait4 (2). |
47297adb | 97 | .SH RETURN VALUE |
ea5bce08 NF |
98 | .BR popen (): |
99 | on success, returns a pointer to an open stream that | |
100 | can be used to read or write to the pipe; | |
101 | if the | |
fea681da MK |
102 | .BR fork (2) |
103 | or | |
104 | .BR pipe (2) | |
ea5bce08 NF |
105 | calls fail, or if the function cannot allocate memory, |
106 | NULL is returned. | |
847e0d88 | 107 | .PP |
ea5bce08 NF |
108 | .BR pclose (): |
109 | on success, returns the exit status of the command; if | |
fea681da MK |
110 | .\" These conditions actually give undefined results, so I commented |
111 | .\" them out. | |
112 | .\" .I stream | |
324633ae | 113 | .\" is not associated with a "popen()ed" command, if |
fea681da | 114 | .\".I stream |
324633ae | 115 | .\" already "pclose()d", or if |
91fe9d5c | 116 | .BR wait4 (2) |
ea5bce08 NF |
117 | returns an error, or some other error is detected, |
118 | \-1 is returned. | |
119 | .PP | |
7a6227d3 | 120 | On failure, both functions set |
eb204b94 | 121 | .I errno |
7a6227d3 | 122 | to indicate the error. |
fea681da MK |
123 | .SH ERRORS |
124 | The | |
e511ffb6 | 125 | .BR popen () |
fea681da MK |
126 | function does not set |
127 | .I errno | |
c13182ef MK |
128 | if memory allocation fails. |
129 | If the underlying | |
fb186734 | 130 | .BR fork (2) |
c13182ef | 131 | or |
fb186734 | 132 | .BR pipe (2) |
fea681da MK |
133 | fails, |
134 | .I errno | |
f6a4078b | 135 | is set to indicate the error. |
c13182ef | 136 | If the |
fea681da MK |
137 | .I type |
138 | argument is invalid, and this condition is detected, | |
139 | .I errno | |
140 | is set to | |
141 | .BR EINVAL . | |
142 | .PP | |
143 | If | |
63aa9df0 | 144 | .BR pclose () |
fea681da MK |
145 | cannot obtain the child status, |
146 | .I errno | |
147 | is set to | |
148 | .BR ECHILD . | |
8ae2d625 MS |
149 | .SH ATTRIBUTES |
150 | For an explanation of the terms used in this section, see | |
151 | .BR attributes (7). | |
c466875e MK |
152 | .ad l |
153 | .nh | |
8ae2d625 MS |
154 | .TS |
155 | allbox; | |
c466875e | 156 | lbx lb lb |
8ae2d625 MS |
157 | l l l. |
158 | Interface Attribute Value | |
159 | T{ | |
160 | .BR popen (), | |
161 | .BR pclose () | |
162 | T} Thread safety MT-Safe | |
163 | .TE | |
c466875e MK |
164 | .hy |
165 | .ad | |
847e0d88 | 166 | .sp 1 |
3113c7f3 | 167 | .SH STANDARDS |
0ba861e9 | 168 | POSIX.1-2001, POSIX.1-2008. |
847e0d88 | 169 | .PP |
e18599c0 MK |
170 | The \(aqe\(aq value for |
171 | .I type | |
172 | is a Linux extension. | |
fefbc57d MK |
173 | .SH NOTES |
174 | .BR Note : | |
175 | carefully read Caveats in | |
176 | .BR system (3). | |
fea681da MK |
177 | .SH BUGS |
178 | Since the standard input of a command opened for reading shares its seek | |
179 | offset with the process that called | |
63aa9df0 | 180 | .BR popen (), |
fea681da | 181 | if the original process has done a buffered read, the command's input |
c13182ef MK |
182 | position may not be as expected. |
183 | Similarly, the output from a command | |
fea681da | 184 | opened for writing may become intermingled with that of the original |
c13182ef MK |
185 | process. |
186 | The latter can be avoided by calling | |
fea681da MK |
187 | .BR fflush (3) |
188 | before | |
e511ffb6 | 189 | .BR popen (). |
fea681da MK |
190 | .PP |
191 | Failure to execute the shell is indistinguishable from the shell's failure | |
c13182ef MK |
192 | to execute command, or an immediate exit of the command. |
193 | The only hint is an exit status of 127. | |
889829be MK |
194 | .\" .SH HISTORY |
195 | .\" A | |
196 | .\" .BR popen () | |
197 | .\" and a | |
198 | .\" .BR pclose () | |
199 | .\" function appeared in Version 7 AT&T UNIX. | |
47297adb | 200 | .SH SEE ALSO |
fea681da MK |
201 | .BR sh (1), |
202 | .BR fork (2), | |
203 | .BR pipe (2), | |
204 | .BR wait4 (2), | |
205 | .BR fclose (3), | |
206 | .BR fflush (3), | |
207 | .BR fopen (3), | |
208 | .BR stdio (3), | |
209 | .BR system (3) |