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.\" 4. 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.\" @(#)popen.3 8.2 (Berkeley) 5/3/95 29.\" $FreeBSD$ 30.\" 31.Dd May 20, 2013 32.Dt POPEN 3 33.Os 34.Sh NAME 35.Nm popen , 36.Nm pclose 37.Nd process 38.Tn I/O 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In stdio.h 43.Ft FILE * 44.Fn popen "const char *command" "const char *type" 45.Ft int 46.Fn pclose "FILE *stream" 47.Sh DESCRIPTION 48The 49.Fn popen 50function 51.Dq opens 52a process by creating a bidirectional pipe 53forking, 54and invoking the shell. 55Any streams opened by previous 56.Fn popen 57calls in the parent process are closed in the new child process. 58Historically, 59.Fn popen 60was implemented with a unidirectional pipe; 61hence many implementations of 62.Fn popen 63only allow the 64.Fa type 65argument to specify reading or writing, not both. 66Since 67.Fn popen 68is now implemented using a bidirectional pipe, the 69.Fa type 70argument may request a bidirectional data flow. 71The 72.Fa type 73argument is a pointer to a null-terminated string 74which must be 75.Ql r 76for reading, 77.Ql w 78for writing, or 79.Ql r+ 80for reading and writing. 81.Pp 82A letter 83.Ql e 84may be appended to that to request that the underlying file descriptor 85be set close-on-exec. 86.Pp 87The 88.Fa command 89argument is a pointer to a null-terminated string 90containing a shell command line. 91This command is passed to 92.Pa /bin/sh 93using the 94.Fl c 95flag; interpretation, if any, is performed by the shell. 96.Pp 97The return value from 98.Fn popen 99is a normal standard 100.Tn I/O 101stream in all respects 102save that it must be closed with 103.Fn pclose 104rather than 105.Fn fclose . 106Writing to such a stream 107writes to the standard input of the command; 108the command's standard output is the same as that of the process that called 109.Fn popen , 110unless this is altered by the command itself. 111Conversely, reading from a 112.Dq popened 113stream reads the command's standard output, and 114the command's standard input is the same as that of the process that called 115.Fn popen . 116.Pp 117Note that output 118.Fn popen 119streams are fully buffered by default. 120.Pp 121The 122.Fn pclose 123function waits for the associated process to terminate 124and returns the exit status of the command 125as returned by 126.Xr wait4 2 . 127.Sh RETURN VALUES 128The 129.Fn popen 130function returns 131.Dv NULL 132if the 133.Xr fork 2 134or 135.Xr pipe 2 136calls fail, 137or if it cannot allocate memory. 138.Pp 139The 140.Fn pclose 141function 142returns \-1 if 143.Fa stream 144is not associated with a 145.Dq popened 146command, if 147.Fa stream 148already 149.Dq pclosed , 150or if 151.Xr wait4 2 152returns an error. 153.Sh ERRORS 154The 155.Fn popen 156function does not reliably set 157.Va errno . 158.Sh SEE ALSO 159.Xr sh 1 , 160.Xr fork 2 , 161.Xr pipe 2 , 162.Xr wait4 2 , 163.Xr fclose 3 , 164.Xr fflush 3 , 165.Xr fopen 3 , 166.Xr stdio 3 , 167.Xr system 3 168.Sh HISTORY 169A 170.Fn popen 171and a 172.Fn pclose 173function appeared in 174.At v7 . 175.Pp 176Bidirectional functionality was added in 177.Fx 2.2.6 . 178.Sh BUGS 179Since the standard input of a command opened for reading 180shares its seek offset with the process that called 181.Fn popen , 182if the original process has done a buffered read, 183the command's input position may not be as expected. 184Similarly, the output from a command opened for writing 185may become intermingled with that of the original process. 186The latter can be avoided by calling 187.Xr fflush 3 188before 189.Fn popen . 190.Pp 191Failure to execute the shell 192is indistinguishable from the shell's failure to execute command, 193or an immediate exit of the command. 194The only hint is an exit status of 127. 195.Pp 196The 197.Fn popen 198function 199always calls 200.Xr sh 1 , 201never calls 202.Xr csh 1 . 203