Debian Codegraph @

upstream/debian-unstable/man3/popen.3

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