1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd May 3, 1995 29.Dt POPEN 3 30.Os 31.Sh NAME 32.Nm popen , 33.Nm pclose 34.Nd process 35.Tn I/O 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In stdio.h 40.Ft FILE * 41.Fn popen "const char *command" "const char *type" 42.Ft int 43.Fn pclose "FILE *stream" 44.Sh DESCRIPTION 45The 46.Fn popen 47function 48.Dq opens 49a process by creating a bidirectional pipe 50forking, 51and invoking the shell. 52Any streams opened by previous 53.Fn popen 54calls in the parent process are closed in the new child process. 55Historically, 56.Fn popen 57was implemented with a unidirectional pipe; 58hence many implementations of 59.Fn popen 60only allow the 61.Fa type 62argument to specify reading or writing, not both. 63Since 64.Fn popen 65is now implemented using a bidirectional pipe, the 66.Fa type 67argument may request a bidirectional data flow. 68The 69.Fa type 70argument is a pointer to a null-terminated string 71which must be 72.Ql r 73for reading, 74.Ql w 75for writing, or 76.Ql r+ 77for reading and writing. 78.Pp 79The 80.Fa type 81argument may be augmented by appending an 82.Ql e 83to set the descriptor's close-on-exec flag. 84For example, 85.Ql re 86for reading, 87.Ql we 88for writing, or 89.Ql r+e 90for reading and writing. 91Use of this flag is important when operating in threaded environments. 92.Pp 93The 94.Fa command 95argument is a pointer to a null-terminated string 96containing a shell command line. 97This command is passed to 98.Pa /bin/sh 99using the 100.Fl c 101flag; interpretation, if any, is performed by the shell. 102.Pp 103The return value from 104.Fn popen 105is a normal standard 106.Tn I/O 107stream in all respects 108save that it must be closed with 109.Fn pclose 110rather than 111.Fn fclose . 112Writing to such a stream 113writes to the standard input of the command; 114the command's standard output is the same as that of the process that called 115.Fn popen , 116unless this is altered by the command itself. 117Conversely, reading from a 118.Dq popened 119stream reads the command's standard output, and 120the command's standard input is the same as that of the process that called 121.Fn popen . 122.Pp 123Note that output 124.Fn popen 125streams are fully buffered by default. 126.Pp 127.Fn popen 128automatically interlocks and closes descriptors associated with other 129active 130.Fn popen 131files in any sub-process it creates, preventing file descriptor leakage 132between 133.Fn popen 134calls in a thread-safe manner. 135However, 136.Fn popen 137has no control over fork or fork/exec sequences run by other threads which 138do not use the popen mechanism and in this situation it is likely that 139popen descriptors will leak into those sub-processes. 140It is recommended that the 141.Ql e 142flag be used to prevent descriptor leakages into miscellaneous fork/exec 143sequences that might be executed by other threads in a multi-threaded 144program. 145.Pp 146The 147.Fn pclose 148function waits for the associated process to terminate 149and returns the exit status of the command 150as returned by 151.Fn wait4 . 152.Sh RETURN VALUES 153The 154.Fn popen 155function returns 156.Dv NULL 157if the 158.Xr fork 2 159or 160.Xr pipe 2 161calls fail, 162or if it cannot allocate memory. 163.Pp 164The 165.Fn pclose 166function 167returns \-1 if 168.Fa stream 169is not associated with a 170.Dq popened 171command, if 172.Fa stream 173already 174.Dq pclosed , 175or if 176.Xr wait4 2 177returns an error. 178.Sh ERRORS 179The 180.Fn popen 181function does not reliably set 182.Va errno . 183.Sh SEE ALSO 184.Xr sh 1 , 185.Xr fork 2 , 186.Xr pipe 2 , 187.Xr wait4 2 , 188.Xr fclose 3 , 189.Xr fflush 3 , 190.Xr fopen 3 , 191.Xr stdio 3 , 192.Xr system 3 193.Sh HISTORY 194A 195.Fn popen 196and a 197.Fn pclose 198function appeared in 199.At v7 . 200.Pp 201Bidirectional functionality was added in 202.Fx 2.2.6 . 203.Sh BUGS 204Since the standard input of a command opened for reading 205shares its seek offset with the process that called 206.Fn popen , 207if the original process has done a buffered read, 208the command's input position may not be as expected. 209Similarly, the output from a command opened for writing 210may become intermingled with that of the original process. 211The latter can be avoided by calling 212.Xr fflush 3 213before 214.Fn popen . 215.Pp 216Failure to execute the shell 217is indistinguishable from the shell's failure to execute command, 218or an immediate exit of the command. 219The only hint is an exit status of 127. 220.Pp 221The 222.Fn popen 223function 224always calls 225.Xr sh 1 , 226never calls 227.Xr csh 1 . 228