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