1.\" $OpenBSD: popen.3,v 1.18 2014/01/19 10:39:00 schwarze 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: January 19 2014 $ 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 68for reading 69or 70.Qq w 71for writing. 72.Pp 73The return value from 74.Fn popen 75is a normal standard I/O stream in all respects 76except that it must be closed with 77.Fn pclose 78rather than 79.Xr fclose 3 . 80Writing to such a stream 81writes to the standard input of the command; 82the command's standard output is the same as that of the process that called 83.Fn popen , 84unless this is altered by the command itself. 85Conversely, reading from a 86.Dq popened 87stream reads the command's standard output, and 88the command's standard input is the same as that of the process that called 89.Fn popen . 90.Pp 91Note that 92.Fn popen 93output streams are fully buffered by default. 94In addition, fork handlers established using 95.Xr pthread_atfork 3 96are not called when a multithreaded program calls 97.Fn popen . 98.Pp 99The 100.Fn pclose 101function waits for the associated process to terminate and returns the 102exit status of the command as returned by 103.Xr wait4 2 . 104.Sh RETURN VALUES 105The 106.Fn popen 107function returns 108.Dv NULL 109if the 110.Xr fork 2 111or 112.Xr pipe 2 113calls fail, 114or if it cannot allocate memory. 115.Pp 116The 117.Fn pclose 118function returns \-1 if 119.Fa stream 120is not associated with a 121.Dq popened 122command, if 123.Fa stream 124already 125.Dq pclosed , 126or if 127.Xr wait4 2 128returns an error. 129.Sh ERRORS 130The 131.Fn popen 132function does not reliably set 133.Va errno . 134.Sh SEE ALSO 135.Xr sh 1 , 136.Xr fork 2 , 137.Xr pipe 2 , 138.Xr wait4 2 , 139.Xr fclose 3 , 140.Xr fflush 3 , 141.Xr fopen 3 , 142.Xr stdio 3 , 143.Xr system 3 144.Sh HISTORY 145A 146.Fn popen 147and a 148.Fn pclose 149function appeared in 150.At v7 . 151.Sh BUGS 152Since the standard input of a command opened for reading 153shares its seek offset with the process that called 154.Fn popen , 155if the original process has done a buffered read, 156the command's input position may not be as expected. 157Similarly, the output from a command opened for writing 158may become intermingled with that of the original process. 159The latter can be avoided by calling 160.Xr fflush 3 161before 162.Fn popen . 163.Pp 164Failure to execute the shell is indistinguishable from the shell's 165failure to execute 166.Fa command , 167or an immediate exit of the command. 168The only hint is an exit status of 127. 169.Pp 170The 171.Fn popen 172argument always calls 173.Xr sh 1 . 174