1*61111Sbostic.\" Copyright (c) 1991, 1993 2*61111Sbostic.\" The Regents of the University of California. All rights reserved. 320439Smckusick.\" 448879Scael.\" %sccs.include.redist.roff% 548879Scael.\" 6*61111Sbostic.\" @(#)popen.3 8.1 (Berkeley) 06/04/93 748879Scael.\" 848879Scael.Dd 948879Scael.Dt POPEN 3 1048879Scael.Os 1148879Scael.Sh NAME 1248879Scael.Nm popen , 1348879Scael.Nm pclose 1448879Scael.Nd process 1548879Scael.Tn I/O 1648879Scael.Sh SYNOPSIS 1748879Scael.Fd #include <stdio.h> 1848879Scael.Ft FILE * 1948879Scael.Fn popen "const char *command" "const char *type" 2048879Scael.Ft int 2148879Scael.Fn pclose "FILE *stream" 2248879Scael.Sh DESCRIPTION 2348879ScaelThe 2448879Scael.Fn popen 2548879Scaelfunction 2648879Scael.Dq opens 2748879Scaela process by creating a pipe, 2848879Scaelforking, 2948879Scaeland invoking the shell. 3048879ScaelSince a pipe is by definition unidirectional, the 3148879Scael.Fa type 3248879Scaelargument may specify only reading or writing, not both; 3348879Scaelthe resulting stream is correspondingly read-only or write-only. 3448879Scael.Pp 3548879ScaelThe 3648879Scael.Fa command 3748879Scaelargument is a pointer to a null-terminated string 3848879Scaelcontaining a shell command line. 3948879ScaelThis command is passed to 4048879Scael.Pa /bin/sh 4148879Scaelusing the 4248879Scael.Fl c 4348879Scaelflag; interpretation, if any, is performed by the shell. 4448879ScaelThe 4548879Scael.Fa mode 4648879Scaelargument is a pointer to a null-terminated string 4748879Scaelwhich must be either 4848879Scael.Ql r 4948879Scaelfor reading 5048879Scaelor 5148879Scael.Ql w 5248879Scaelfor writing. 5348879Scael.Pp 5448879ScaelThe return value from 5548879Scael.Fn popen 5648879Scaelis a normal standard 5748879Scael.Tn I/O 5848879Scaelstream in all respects 5948879Scaelsave that it must be closed with 6048879Scael.Fn pclose 6148879Scaelrather than 6248879Scael.Fn fclose . 6348879ScaelWriting to such a stream 6448879Scaelwrites to the standard input of the command; 6548879Scaelthe command's standard output is the same as that of the process that called 6648879Scael.Fn popen , 6748879Scaelunless this is altered by the command itself. 6848879ScaelConversely, reading from a 6948879Scael.Dq popened 7048879Scaelstream reads the command's standard output, and 7148879Scaelthe command's standard input is the same as that of the process that called 7248879Scael.Fn popen . 7348879Scael.Pp 7448879ScaelNote that output 7548879Scael.Fn popen 7648879Scaelstreams are fully buffered by default. 7748879Scael.Pp 7848879ScaelThe 7948879Scael.Fn pclose 8048879Scaelfunction waits for the associated process to terminate 8148879Scaeland returns the exit status of the command 8248879Scaelas returned by 8348879Scael.Fn wait4 . 8448879Scael.Sh RETURN VALUE 8548879ScaelThe 8648879Scael.Fn popen 8748879Scaelfunction returns 8848879Scael.Dv NULL 8948879Scaelif the 9048879Scael.Xr fork 2 9148879Scaelor 9248879Scael.Xr pipe 2 9348879Scaelcalls fail, 9448879Scaelor if it cannot allocate memory. 9548879Scael.Pp 9648879ScaelThe 9748879Scael.Fn pclose 9848879Scaelfunction 9920439Smckusickreturns \-1 if 10048879Scael.Fa stream 10148879Scaelis not associated with a 10248879Scael.Dq popened 10348879Scaelcommand, if 10448879Scael.Fa stream 10548879Scaelalready 10648879Scael.Dq pclosed , 10748879Scaelor if 10848879Scael.Xr wait4 10936310Sbosticreturns an error. 11048879Scael.Sh ERRORS 11148879ScaelThe 11248879Scael.Fn popen 11348879Scaelfunction does not reliably set 11448879Scael.Va errno . 11548879Scael.Sh SEE ALSO 11648879Scael.Xr fork 2 , 11748879Scael.Xr sh 1 , 11848879Scael.Xr pipe 2 , 11948879Scael.Xr wait4 2 , 12048879Scael.Xr fflush 3 , 12148879Scael.Xr fclose 3 , 12248879Scael.Xr fopen 3 , 12348879Scael.Xr stdio 3 , 12448879Scael.Xr system 3 12548879Scael.Sh BUGS 12648879ScaelSince the standard input of a command opened for reading 12748879Scaelshares its seek offset with the process that called 12848879Scael.Fn popen , 12948879Scaelif the original process has done a buffered read, 13048879Scaelthe command's input position may not be as expected. 13148879ScaelSimilarly, the output from a command opened for writing 13248879Scaelmay become intermingled with that of the original process. 13348879ScaelThe latter can be avoided by calling 13448879Scael.Xr fflush 3 13548879Scaelbefore 13648879Scael.Fn popen . 13748879Scael.Pp 13848879ScaelFailure to execute the shell 13948879Scaelis indistinguishable from the shell's failure to execute command, 14048879Scaelor an immediate exit of the command. 14148879ScaelThe only hint is an exit status of 127. 14248879Scael.Pp 14348879ScaelThe 14448879Scael.Fn popen 14548879Scaelargument 14620440Smckusickalways calls 14748879Scael.Xr sh , 14820440Smckusicknever calls 14948879Scael.Xr csh . 15048879Scael.Sh HISTORY 15148879ScaelA 15248879Scael.Fn popen 15348879Scaeland a 15448879Scael.Fn pclose 15548879Scaelfunction appeared in 15648879Scael.At v7 . 157