1.\" $NetBSD: popen.3,v 1.25 2022/12/04 11:25:08 uwe 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.\" @(#)popen.3 8.2 (Berkeley) 5/3/95 31.\" 32.Dd September 11, 2021 33.Dt POPEN 3 34.Os 35.Sh NAME 36.Nm popen , 37.Nm popenve , 38.Nm pclose 39.Nd process 40.Tn I/O 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In stdio.h 45.Ft FILE * 46.Fn popen "const char *command" "const char *type" 47.Ft FILE * 48.Fn popenve "const char *path" "char * const *argv" "char * const *envp" "const char *type" 49.Ft int 50.Fn pclose "FILE *stream" 51.Sh DESCRIPTION 52The 53.Fn popen 54function 55.Dq opens 56a process by creating an IPC connection, 57forking, 58and invoking the shell. 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 sockets, the 70.Fa type 71may 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. 82In addition if the character 83.Ql e 84is present in the 85.Fa type 86string, the file descriptor used internally is set to be closed on 87.Xr exec 3 . 88.Pp 89The 90.Fa command 91argument is a pointer to a null-terminated string 92containing a shell command line. 93This command is passed to 94.Pa /bin/sh 95using the 96.Fl c 97flag; interpretation, if any, is performed by the shell. 98.Pp 99The 100.Fn popenve 101function is similar to 102.Fn popen 103but the first three arguments are passed 104to 105.Xr execve 2 106and there is no shell involved in the command invocation. 107.Pp 108The return value from 109.Fn popen 110and 111.Fn popenve 112is a normal standard 113.Tn I/O 114stream in all respects 115save that it must be closed with 116.Fn pclose 117rather than 118.Fn fclose . 119Writing to such a stream 120writes to the standard input of the command; 121the command's standard output is the same as that of the process that called 122.Fn popen , 123unless this is altered by the command itself. 124Conversely, reading from a 125.Dq popened 126stream reads the command's standard output, and 127the command's standard input is the same as that of the process that called 128.Fn popen . 129.Pp 130Note that output 131.Fn popen 132streams are fully buffered by default. 133.Pp 134The 135.Fn pclose 136function waits for the associated process to terminate 137and returns the exit status of the command 138as returned by 139.Xr wait4 2 . 140.Sh RETURN VALUES 141The 142.Fn popen 143function returns 144.Dv NULL 145if the 146.Xr vfork 2 , 147.Xr pipe 2 , 148or 149.Xr socketpair 2 150calls fail, 151or if it cannot allocate memory, preserving 152the errno from those functions. 153.Pp 154The 155.Fn pclose 156function 157returns \-1 if 158.Fa stream 159is not associated with a 160.Dq popened 161command, if 162.Fa stream 163has already been 164.Dq pclosed , 165setting errno to 166.Er ESRCH , 167or if 168.Xr wait4 2 169returns an error, preserving the errno returned by 170.Xr wait4 2 . 171.Sh SEE ALSO 172.Xr sh 1 , 173.Xr execve 2 , 174.Xr fork 2 , 175.Xr pipe 2 , 176.Xr socketpair 2 , 177.Xr vfork 2 , 178.Xr wait4 2 , 179.Xr fclose 3 , 180.Xr fflush 3 , 181.Xr fopen 3 , 182.Xr shquote 3 , 183.Xr stdio 3 , 184.Xr system 3 185.Sh STANDARDS 186The 187.Fn popen 188and 189.Fn pclose 190functions conform to 191.St -p1003.2-92 . 192.Sh HISTORY 193A 194.Fn popen 195and a 196.Fn pclose 197function appeared in 198.At v7 . 199.Pp 200The 201.Fn popenve 202function first appeared in 203.Nx 8 . 204.Sh BUGS 205Since the standard input of a command opened for reading 206shares its seek offset with the process that called 207.Fn popen , 208if the original process has done a buffered read, 209the command's input position may not be as expected. 210Similarly, the output from a command opened for writing 211may become intermingled with that of the original process. 212The latter can be avoided by calling 213.Xr fflush 3 214before 215.Fn popen . 216.Pp 217Failure to execute the shell 218is indistinguishable from the shell's failure to execute the command, 219or an immediate exit of the command. 220The only hint is an exit status of 127. 221.Pp 222The 223.Fn popen 224argument 225always calls 226.Xr sh 1 , 227never calls 228.Xr csh 1 . 229