1 .\" Copyright 1991 The Regents of the University of California.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)popen.3 6.4 (Berkeley) 4/30/91
34 .\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu
35 .\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de)
36 .\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
38 .TH POPEN 3 2010-02-03 "GNU" "Linux Programmer's Manual"
40 popen, pclose \- pipe stream to or from a process
45 .BI "FILE *popen(const char *" command ", const char *" type );
47 .BI "int pclose(FILE *" stream );
51 Feature Test Macro Requirements for glibc (see
52 .BR feature_test_macros (7)):
59 _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
65 function opens a process by creating a pipe, forking, and invoking the
67 Since a pipe is by definition unidirectional, the
69 argument may specify only reading or writing, not both; the resulting
70 stream is correspondingly read-only or write-only.
74 argument is a pointer to a null-terminated string containing a shell
76 This command is passed to
80 flag; interpretation, if any, is performed by the shell.
83 argument is a pointer to a null-terminated string which must contain
84 either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing.
86 this argument can additionally include the letter \(aqe\(aq,
87 which causes the close-on-exec flag
89 to be set on the underlying file descriptor;
90 see the description of the
94 for reasons why this may be useful.
98 is a normal standard I/O stream in all respects save that it must be closed
103 Writing to such a stream writes to the standard input of the command; the
104 command's standard output is the same as that of the process that called
106 unless this is altered by the command itself.
107 Conversely, reading from a
108 "popened" stream reads the command's standard output, and the command's
109 standard input is the same as that of the process that called
114 streams are fully buffered by default.
118 function waits for the associated process to terminate and returns the exit
119 status of the command as returned by
124 function returns NULL if the
128 calls fail, or if it cannot allocate memory.
132 function returns \-1 if
133 .\" These conditions actually give undefined results, so I commented
136 .\" is not associated with a "popen()ed" command, if
138 .\" already "pclose()d", or if
140 returns an error, or some other error is detected.
144 function does not set
146 if memory allocation fails.
153 is set appropriately.
156 argument is invalid, and this condition is detected,
163 cannot obtain the child status,
170 The \(aqe\(aq value for
172 is a Linux extension.
174 Since the standard input of a command opened for reading shares its seek
175 offset with the process that called
177 if the original process has done a buffered read, the command's input
178 position may not be as expected.
179 Similarly, the output from a command
180 opened for writing may become intermingled with that of the original
182 The latter can be avoided by calling
187 Failure to execute the shell is indistinguishable from the shell's failure
188 to execute command, or an immediate exit of the command.
189 The only hint is an exit status of 127.
195 .\" function appeared in Version 7 AT&T UNIX.