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.1 (Berkeley) 06/04/93 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 a pipe, 28forking, 29and invoking the shell. 30Since a pipe is by definition unidirectional, the 31.Fa type 32argument may specify only reading or writing, not both; 33the resulting stream is correspondingly read-only or write-only. 34.Pp 35The 36.Fa command 37argument is a pointer to a null-terminated string 38containing a shell command line. 39This command is passed to 40.Pa /bin/sh 41using the 42.Fl c 43flag; interpretation, if any, is performed by the shell. 44The 45.Fa mode 46argument is a pointer to a null-terminated string 47which must be either 48.Ql r 49for reading 50or 51.Ql w 52for writing. 53.Pp 54The return value from 55.Fn popen 56is a normal standard 57.Tn I/O 58stream in all respects 59save that it must be closed with 60.Fn pclose 61rather than 62.Fn fclose . 63Writing to such a stream 64writes to the standard input of the command; 65the command's standard output is the same as that of the process that called 66.Fn popen , 67unless this is altered by the command itself. 68Conversely, reading from a 69.Dq popened 70stream reads the command's standard output, and 71the command's standard input is the same as that of the process that called 72.Fn popen . 73.Pp 74Note that output 75.Fn popen 76streams are fully buffered by default. 77.Pp 78The 79.Fn pclose 80function waits for the associated process to terminate 81and returns the exit status of the command 82as returned by 83.Fn wait4 . 84.Sh RETURN VALUE 85The 86.Fn popen 87function returns 88.Dv NULL 89if the 90.Xr fork 2 91or 92.Xr pipe 2 93calls fail, 94or if it cannot allocate memory. 95.Pp 96The 97.Fn pclose 98function 99returns \-1 if 100.Fa stream 101is not associated with a 102.Dq popened 103command, if 104.Fa stream 105already 106.Dq pclosed , 107or if 108.Xr wait4 109returns an error. 110.Sh ERRORS 111The 112.Fn popen 113function does not reliably set 114.Va errno . 115.Sh SEE ALSO 116.Xr fork 2 , 117.Xr sh 1 , 118.Xr pipe 2 , 119.Xr wait4 2 , 120.Xr fflush 3 , 121.Xr fclose 3 , 122.Xr fopen 3 , 123.Xr stdio 3 , 124.Xr system 3 125.Sh BUGS 126Since the standard input of a command opened for reading 127shares its seek offset with the process that called 128.Fn popen , 129if the original process has done a buffered read, 130the command's input position may not be as expected. 131Similarly, the output from a command opened for writing 132may become intermingled with that of the original process. 133The latter can be avoided by calling 134.Xr fflush 3 135before 136.Fn popen . 137.Pp 138Failure to execute the shell 139is indistinguishable from the shell's failure to execute command, 140or an immediate exit of the command. 141The only hint is an exit status of 127. 142.Pp 143The 144.Fn popen 145argument 146always calls 147.Xr sh , 148never calls 149.Xr csh . 150.Sh HISTORY 151A 152.Fn popen 153and a 154.Fn pclose 155function appeared in 156.At v7 . 157