1*48879Scael.\" Copyright 1991 The Regents of the University of California. 2*48879Scael.\" All rights reserved. 320439Smckusick.\" 4*48879Scael.\" %sccs.include.redist.roff% 5*48879Scael.\" 6*48879Scael.\" @(#)popen.3 6.4 (Berkeley) 04/30/91 7*48879Scael.\" 8*48879Scael.Dd 9*48879Scael.Dt POPEN 3 10*48879Scael.Os 11*48879Scael.Sh NAME 12*48879Scael.Nm popen , 13*48879Scael.Nm pclose 14*48879Scael.Nd process 15*48879Scael.Tn I/O 16*48879Scael.Sh SYNOPSIS 17*48879Scael.Fd #include <stdio.h> 18*48879Scael.Ft FILE * 19*48879Scael.Fn popen "const char *command" "const char *type" 20*48879Scael.Ft int 21*48879Scael.Fn pclose "FILE *stream" 22*48879Scael.Sh DESCRIPTION 23*48879ScaelThe 24*48879Scael.Fn popen 25*48879Scaelfunction 26*48879Scael.Dq opens 27*48879Scaela process by creating a pipe, 28*48879Scaelforking, 29*48879Scaeland invoking the shell. 30*48879ScaelSince a pipe is by definition unidirectional, the 31*48879Scael.Fa type 32*48879Scaelargument may specify only reading or writing, not both; 33*48879Scaelthe resulting stream is correspondingly read-only or write-only. 34*48879Scael.Pp 35*48879ScaelThe 36*48879Scael.Fa command 37*48879Scaelargument is a pointer to a null-terminated string 38*48879Scaelcontaining a shell command line. 39*48879ScaelThis command is passed to 40*48879Scael.Pa /bin/sh 41*48879Scaelusing the 42*48879Scael.Fl c 43*48879Scaelflag; interpretation, if any, is performed by the shell. 44*48879ScaelThe 45*48879Scael.Fa mode 46*48879Scaelargument is a pointer to a null-terminated string 47*48879Scaelwhich must be either 48*48879Scael.Ql r 49*48879Scaelfor reading 50*48879Scaelor 51*48879Scael.Ql w 52*48879Scaelfor writing. 53*48879Scael.Pp 54*48879ScaelThe return value from 55*48879Scael.Fn popen 56*48879Scaelis a normal standard 57*48879Scael.Tn I/O 58*48879Scaelstream in all respects 59*48879Scaelsave that it must be closed with 60*48879Scael.Fn pclose 61*48879Scaelrather than 62*48879Scael.Fn fclose . 63*48879ScaelWriting to such a stream 64*48879Scaelwrites to the standard input of the command; 65*48879Scaelthe command's standard output is the same as that of the process that called 66*48879Scael.Fn popen , 67*48879Scaelunless this is altered by the command itself. 68*48879ScaelConversely, reading from a 69*48879Scael.Dq popened 70*48879Scaelstream reads the command's standard output, and 71*48879Scaelthe command's standard input is the same as that of the process that called 72*48879Scael.Fn popen . 73*48879Scael.Pp 74*48879ScaelNote that output 75*48879Scael.Fn popen 76*48879Scaelstreams are fully buffered by default. 77*48879Scael.Pp 78*48879ScaelThe 79*48879Scael.Fn pclose 80*48879Scaelfunction waits for the associated process to terminate 81*48879Scaeland returns the exit status of the command 82*48879Scaelas returned by 83*48879Scael.Fn wait4 . 84*48879Scael.Sh RETURN VALUE 85*48879ScaelThe 86*48879Scael.Fn popen 87*48879Scaelfunction returns 88*48879Scael.Dv NULL 89*48879Scaelif the 90*48879Scael.Xr fork 2 91*48879Scaelor 92*48879Scael.Xr pipe 2 93*48879Scaelcalls fail, 94*48879Scaelor if it cannot allocate memory. 95*48879Scael.Pp 96*48879ScaelThe 97*48879Scael.Fn pclose 98*48879Scaelfunction 9920439Smckusickreturns \-1 if 100*48879Scael.Fa stream 101*48879Scaelis not associated with a 102*48879Scael.Dq popened 103*48879Scaelcommand, if 104*48879Scael.Fa stream 105*48879Scaelalready 106*48879Scael.Dq pclosed , 107*48879Scaelor if 108*48879Scael.Xr wait4 10936310Sbosticreturns an error. 110*48879Scael.Sh ERRORS 111*48879ScaelThe 112*48879Scael.Fn popen 113*48879Scaelfunction does not reliably set 114*48879Scael.Va errno . 115*48879Scael.Sh SEE ALSO 116*48879Scael.Xr fork 2 , 117*48879Scael.Xr sh 1 , 118*48879Scael.Xr pipe 2 , 119*48879Scael.Xr wait4 2 , 120*48879Scael.Xr fflush 3 , 121*48879Scael.Xr fclose 3 , 122*48879Scael.Xr fopen 3 , 123*48879Scael.Xr stdio 3 , 124*48879Scael.Xr system 3 125*48879Scael.Sh BUGS 126*48879ScaelSince the standard input of a command opened for reading 127*48879Scaelshares its seek offset with the process that called 128*48879Scael.Fn popen , 129*48879Scaelif the original process has done a buffered read, 130*48879Scaelthe command's input position may not be as expected. 131*48879ScaelSimilarly, the output from a command opened for writing 132*48879Scaelmay become intermingled with that of the original process. 133*48879ScaelThe latter can be avoided by calling 134*48879Scael.Xr fflush 3 135*48879Scaelbefore 136*48879Scael.Fn popen . 137*48879Scael.Pp 138*48879ScaelFailure to execute the shell 139*48879Scaelis indistinguishable from the shell's failure to execute command, 140*48879Scaelor an immediate exit of the command. 141*48879ScaelThe only hint is an exit status of 127. 142*48879Scael.Pp 143*48879ScaelThe 144*48879Scael.Fn popen 145*48879Scaelargument 14620440Smckusickalways calls 147*48879Scael.Xr sh , 14820440Smckusicknever calls 149*48879Scael.Xr csh . 150*48879Scael.Sh HISTORY 151*48879ScaelA 152*48879Scael.Fn popen 153*48879Scaeland a 154*48879Scael.Fn pclose 155*48879Scaelfunction appeared in 156*48879Scael.At v7 . 157