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.\" $FreeBSD: src/lib/libc/gen/popen.3,v 1.10.2.4 2003/03/15 15:11:05 trhodes Exp $ 34.\" $DragonFly: src/lib/libc/gen/popen.3,v 1.4 2006/04/08 08:17:06 swildner Exp $ 35.\" 36.Dd May 3, 1995 37.Dt POPEN 3 38.Os 39.Sh NAME 40.Nm popen , 41.Nm pclose 42.Nd process 43.Tn I/O 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In stdio.h 48.Ft FILE * 49.Fn popen "const char *command" "const char *type" 50.Ft int 51.Fn pclose "FILE *stream" 52.Sh DESCRIPTION 53The 54.Fn popen 55function 56.Dq opens 57a process by creating a bidirectional pipe 58forking, 59and invoking the shell. 60Any streams opened by previous 61.Fn popen 62calls in the parent process are closed in the new child process. 63Historically, 64.Fn popen 65was implemented with a unidirectional pipe; 66hence many implementations of 67.Fn popen 68only allow the 69.Fa type 70argument to specify reading or writing, not both. 71Since 72.Fn popen 73is now implemented using a bidirectional pipe, the 74.Fa type 75argument may request a bidirectional data flow. 76The 77.Fa type 78argument is a pointer to a null-terminated string 79which must be 80.Ql r 81for reading, 82.Ql w 83for writing, or 84.Ql r+ 85for reading and writing. 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.Fn wait4 . 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