1.\" $OpenBSD: popen.3,v 1.20 2016/02/05 18:09:20 espie Exp $ 2.\" 3.\" Copyright (c) 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: February 5 2016 $ 31.Dt POPEN 3 32.Os 33.Sh NAME 34.Nm popen , 35.Nm pclose 36.Nd process I/O 37.Sh SYNOPSIS 38.In stdio.h 39.Ft FILE * 40.Fn popen "const char *command" "const char *type" 41.Ft int 42.Fn pclose "FILE *stream" 43.Sh DESCRIPTION 44The 45.Fn popen 46function 47.Dq opens 48a process by creating a pipe, forking, and invoking the shell. 49Since a pipe is by definition unidirectional, the 50.Fa type 51argument may specify only reading or writing, not both; 52the resulting stream is correspondingly read-only or write-only. 53.Pp 54The 55.Fa command 56argument is a pointer to a NUL-terminated 57string containing a shell command line. 58This command is passed to 59.Pa /bin/sh 60using the 61.Fl c 62flag; interpretation, if any, is performed by the shell. 63The 64.Fa type 65argument is a pointer to a NUL-terminated 66string which must be either 67.Qq r 68or 69.Qq re 70for reading 71or 72.Qq w 73or 74.Qq we 75for writing. 76If the letter 77.Qq e 78is present in the string then the close-on-exec flag shall be set on the 79file descriptor underlying the 80.Vt FILE 81that is returned. 82.Pp 83The return value from 84.Fn popen 85is a normal standard I/O stream in all respects 86except that it must be closed with 87.Fn pclose 88rather than 89.Xr fclose 3 . 90Writing to such a stream 91writes to the standard input of the command; 92the command's standard output is the same as that of the process that called 93.Fn popen , 94unless this is altered by the command itself. 95Conversely, reading from a 96.Dq popened 97stream reads the command's standard output, and 98the command's standard input is the same as that of the process that called 99.Fn popen . 100.Pp 101Note that 102.Fn popen 103output streams are fully buffered by default. 104In addition, fork handlers established using 105.Xr pthread_atfork 3 106are not called when a multithreaded program calls 107.Fn popen . 108.Pp 109The 110.Fn pclose 111function waits for the associated process to terminate and returns the 112exit status of the command as returned by 113.Xr wait4 2 . 114.Sh RETURN VALUES 115The 116.Fn popen 117function returns 118.Dv NULL 119if the 120.Xr fork 2 121or 122.Xr pipe 2 123calls fail, 124or if it cannot allocate memory. 125.Pp 126The 127.Fn pclose 128function returns \-1 if 129.Fa stream 130is not associated with a 131.Dq popened 132command, if 133.Fa stream 134already 135.Dq pclosed , 136or if 137.Xr wait4 2 138returns an error. 139.Sh ERRORS 140The 141.Fn popen 142function does not reliably set 143.Va errno . 144.Sh SEE ALSO 145.Xr sh 1 , 146.Xr fork 2 , 147.Xr pipe 2 , 148.Xr wait4 2 , 149.Xr fclose 3 , 150.Xr fflush 3 , 151.Xr fopen 3 , 152.Xr stdio 3 , 153.Xr system 3 154.Sh HISTORY 155A 156.Fn popen 157and a 158.Fn pclose 159function appeared in 160.At v7 . 161.Sh CAVEATS 162Never supply the 163.Fn popen 164function with a command containing any part of an unsanitized user-supplied 165string. 166Shell meta-characters present will be honored by the 167.Xr sh 1 168command interpreter. 169.Pp 170It is often simpler to bypass the shell entirely and use 171.Xr pipe 2 , 172.Xr fork 2 , 173.Xr dup2 2 , 174.Xr execlp 3 , 175and 176.Xr fdopen 3 177directly instead of having to sanitize a string for shell consumption. 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 is indistinguishable from the shell's 192failure to execute 193.Fa command , 194or an immediate exit of the command. 195The only hint is an exit status of 127. 196