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 3, 1995 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 82The 83.Fa command 84argument is a pointer to a null-terminated string 85containing a shell command line. 86This command is passed to 87.Pa /bin/sh 88using the 89.Fl c 90flag; interpretation, if any, is performed by the shell. 91.Pp 92The return value from 93.Fn popen 94is a normal standard 95.Tn I/O 96stream in all respects 97save that it must be closed with 98.Fn pclose 99rather than 100.Fn fclose . 101Writing to such a stream 102writes to the standard input of the command; 103the command's standard output is the same as that of the process that called 104.Fn popen , 105unless this is altered by the command itself. 106Conversely, reading from a 107.Dq popened 108stream reads the command's standard output, and 109the command's standard input is the same as that of the process that called 110.Fn popen . 111.Pp 112Note that output 113.Fn popen 114streams are fully buffered by default. 115.Pp 116The 117.Fn pclose 118function waits for the associated process to terminate 119and returns the exit status of the command 120as returned by 121.Xr wait4 2 . 122.Sh RETURN VALUES 123The 124.Fn popen 125function returns 126.Dv NULL 127if the 128.Xr fork 2 129or 130.Xr pipe 2 131calls fail, 132or if it cannot allocate memory. 133.Pp 134The 135.Fn pclose 136function 137returns \-1 if 138.Fa stream 139is not associated with a 140.Dq popened 141command, if 142.Fa stream 143already 144.Dq pclosed , 145or if 146.Xr wait4 2 147returns an error. 148.Sh ERRORS 149The 150.Fn popen 151function does not reliably set 152.Va errno . 153.Sh SEE ALSO 154.Xr sh 1 , 155.Xr fork 2 , 156.Xr pipe 2 , 157.Xr wait4 2 , 158.Xr fclose 3 , 159.Xr fflush 3 , 160.Xr fopen 3 , 161.Xr stdio 3 , 162.Xr system 3 163.Sh HISTORY 164A 165.Fn popen 166and a 167.Fn pclose 168function appeared in 169.At v7 . 170.Pp 171Bidirectional functionality was added in 172.Fx 2.2.6 . 173.Sh BUGS 174Since the standard input of a command opened for reading 175shares its seek offset with the process that called 176.Fn popen , 177if the original process has done a buffered read, 178the command's input position may not be as expected. 179Similarly, the output from a command opened for writing 180may become intermingled with that of the original process. 181The latter can be avoided by calling 182.Xr fflush 3 183before 184.Fn popen . 185.Pp 186Failure to execute the shell 187is indistinguishable from the shell's failure to execute command, 188or an immediate exit of the command. 189The only hint is an exit status of 127. 190.Pp 191The 192.Fn popen 193function 194always calls 195.Xr sh 1 , 196never calls 197.Xr csh 1 . 198