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)):
58 _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
63 function opens a process by creating a pipe, forking, and invoking the
65 Since a pipe is by definition unidirectional, the
67 argument may specify only reading or writing, not both; the resulting
68 stream is correspondingly read-only or write-only.
72 argument is a pointer to a null-terminated string containing a shell
74 This command is passed to
78 flag; interpretation, if any, is performed by the shell.
81 argument is a pointer to a null-terminated string which must contain
82 either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing.
84 this argument can additionally include the letter \(aqe\(aq,
85 which causes the close-on-exec flag
87 to be set on the underlying file descriptor;
88 see the description of the
92 for reasons why this may be useful.
96 is a normal standard I/O stream in all respects save that it must be closed
101 Writing to such a stream writes to the standard input of the command; the
102 command's standard output is the same as that of the process that called
104 unless this is altered by the command itself.
105 Conversely, reading from a
106 "popened" stream reads the command's standard output, and the command's
107 standard input is the same as that of the process that called
112 streams are fully buffered by default.
116 function waits for the associated process to terminate and returns the exit
117 status of the command as returned by
122 function returns NULL if the
126 calls fail, or if it cannot allocate memory.
130 function returns \-1 if
131 .\" These conditions actually give undefined results, so I commented
134 .\" is not associated with a "popen()ed" command, if
136 .\" already "pclose()d", or if
138 returns an error, or some other error is detected.
142 function does not set
144 if memory allocation fails.
151 is set appropriately.
154 argument is invalid, and this condition is detected,
161 cannot obtain the child status,
168 The \(aqe\(aq value for
170 is a Linux extension.
172 Since the standard input of a command opened for reading shares its seek
173 offset with the process that called
175 if the original process has done a buffered read, the command's input
176 position may not be as expected.
177 Similarly, the output from a command
178 opened for writing may become intermingled with that of the original
180 The latter can be avoided by calling
185 Failure to execute the shell is indistinguishable from the shell's failure
186 to execute command, or an immediate exit of the command.
187 The only hint is an exit status of 127.
193 .\" function appeared in Version 7 AT&T UNIX.