1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)popen.3 8.2 (Berkeley) 05/03/95 7.\" 8.Dd 9.Dt POPEN 3 10.Os 11.Sh NAME 12.Nm popen , 13.Nm pclose 14.Nd process 15.Tn I/O 16.Sh SYNOPSIS 17.Fd #include <stdio.h> 18.Ft FILE * 19.Fn popen "const char *command" "const char *type" 20.Ft int 21.Fn pclose "FILE *stream" 22.Sh DESCRIPTION 23The 24.Fn popen 25function 26.Dq opens 27a process by creating an IPC connection, 28forking, 29and invoking the shell. 30Historically, 31.Nm popen 32was implemented with a unidirectional pipe; 33hence many implementations of 34.Nm popen 35only allow the 36.Fa type 37argument to specify reading or writing, not both. 38Since 39.Nm popen 40is now implemented using sockets, the 41.Fa type 42may request a bidirectional data flow. 43The 44.Fa type 45argument is a pointer to a null-terminated string 46which must be 47.Ql r 48for reading, 49.Ql w 50for writing, or 51.Ql r+ 52for reading and writing. 53.Pp 54The 55.Fa command 56argument is a pointer to a null-terminated string 57containing 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. 63.Pp 64The return value from 65.Fn popen 66is a normal standard 67.Tn I/O 68stream in all respects 69save that it must be closed with 70.Fn pclose 71rather than 72.Fn fclose . 73Writing to such a stream 74writes to the standard input of the command; 75the command's standard output is the same as that of the process that called 76.Fn popen , 77unless this is altered by the command itself. 78Conversely, reading from a 79.Dq popened 80stream reads the command's standard output, and 81the command's standard input is the same as that of the process that called 82.Fn popen . 83.Pp 84Note that output 85.Fn popen 86streams are fully buffered by default. 87.Pp 88The 89.Fn pclose 90function waits for the associated process to terminate 91and returns the exit status of the command 92as returned by 93.Fn wait4 . 94.Sh RETURN VALUE 95The 96.Fn popen 97function returns 98.Dv NULL 99if the 100.Xr fork 2 , 101.Xr pipe 2 , 102or 103.Xr socketpair 2 104calls fail, 105or if it cannot allocate memory. 106.Pp 107The 108.Fn pclose 109function 110returns \-1 if 111.Fa stream 112is not associated with a 113.Dq popened 114command, if 115.Fa stream 116already 117.Dq pclosed , 118or if 119.Xr wait4 120returns an error. 121.Sh ERRORS 122The 123.Fn popen 124function does not reliably set 125.Va errno . 126.Sh SEE ALSO 127.Xr fork 2 , 128.Xr sh 1 , 129.Xr pipe 2 , 130.Xr socketpair 2 , 131.Xr wait4 2 , 132.Xr fflush 3 , 133.Xr fclose 3 , 134.Xr fopen 3 , 135.Xr stdio 3 , 136.Xr system 3 137.Sh BUGS 138Since the standard input of a command opened for reading 139shares its seek offset with the process that called 140.Fn popen , 141if the original process has done a buffered read, 142the command's input position may not be as expected. 143Similarly, the output from a command opened for writing 144may become intermingled with that of the original process. 145The latter can be avoided by calling 146.Xr fflush 3 147before 148.Fn popen . 149.Pp 150Failure to execute the shell 151is indistinguishable from the shell's failure to execute command, 152or an immediate exit of the command. 153The only hint is an exit status of 127. 154.Pp 155The 156.Fn popen 157argument 158always calls 159.Xr sh , 160never calls 161.Xr csh . 162.Sh HISTORY 163A 164.Fn popen 165and a 166.Fn pclose 167function appeared in 168.At v7 . 169