POPEN(3)                       Library Routines                       POPEN(3)

NAME

       popen, pclose - process I/O

SYNOPSIS

       #include <stdio.h>

       FILE *popen (const char *command, const char *type);
       int pclose (FILE *stream);

DESCRIPTION

       The popen function opens a process by creating a pipe, forking, and in‐
       voking the shell.  Since a pipe is by  definition  unidirectional,  the
       type  argument  may  specify only reading or writing, not both; the re‐
       sulting stream is correspondingly read-only or write-only.

       The command argument is a pointer to a null-terminated string  contain‐
       ing  a shell command line.  This command is passed to /bin/sh using the
       -c flag; interpretation, if any, is performed by the shell.   The  mode
       argument  is a pointer to a null-terminated string which must be either
       r for reading or w for writing.

       The return value from popen is a normal standard I/O stream in all  re‐
       spects  save  that  it  must  be closed with pclose rather than fclose.
       Writing to such a stream writes to the standard input of  the  command;
       the  command's  standard output is the same as that of the process that
       called popen, unless this is  altered  by  the  command  itself.   Con‐
       versely,  reading  from  a  popened stream reads the command's standard
       output, and the command's standard input is the same  as  that  of  the
       process that called popen.

       Note that output popen streams are fully buffered by default.

       The  pclose  function waits for the associated process to terminate and
       returns the exit status of the command as returned by waitpid.

RETURN VALUE

       The popen function returns NULL if the fork(2) or pipe(2)  calls  fail,
       or if it cannot allocate memory.

       The  pclose  function  returns  -1  if  stream is not associated with a
       popened command, if stream already pclosed, or if  waitpid  returns  an
       error.

ERRORS

       The popen function does not reliably set errno.

BUGS

       Since  the  standard  input  of a command opened for reading shares its
       seek offset with the process that called popen, if the original process
       has  done  a  buffered read, the command's input position may not be as
       expected.  Similarly, the output from a command opened for writing  may
       become  intermingled with that of the original process.  The latter can
       be avoided by calling fflush(3) before popen.

       Failure to execute the shell  is  indistinguishable  from  the  shell's
       failure  to  execute command, or an immediate exit of the command.  The
       only hint is an exit status of 127.

       The popen argument always calls sh(1), never calls csh(1).  (Because of
       a  lack of available sh(1), the current GNO implementation always calls
       gsh(1).)

       This implementation makes use of waitpid(2).  Because  waitpid  is  not
       currently  provided  by  the GNO kernel, pclose is affected by the same
       bug as is waitpid; other child processes' exit  status  may  be  caught
       (and discarded) while waiting for the process created by popen.  Conse‐
       quently, if the parent processes is doing any other waitpid calls  (ei‐
       ther directly or indirectly), pclose may never return.

       Under  GNO,  the memory region pointed to by command must be able to be
       referenced up to the point that the child process  does  its  execl(2).
       This implies that if command is allocated on the stack and the function
       which allocated it returns before the program calls pclose (or  if  the
       parent exits and makes its child into a zombie), there is a chance that
       the forked child of popen may try to execl an  arbitrary  command,  the
       results of which are undefined.

       gsh(1)  appears  to  hang on occasion when executing popen's arguments.
       The symptom is that the pclose never returns,  and  the  process  table
       (see  ps(1))  shows that the forked gsh's user time is forever increas‐
       ing.

SEE ALSO

       gsh(1), sh(1),  fork(2),  pipe(2),  waitpid(2),  fclose(3),  fflush(3),
       fopen(3), stdio(3), system(3)

HISTORY

       A popen and a pclose function appeared in Version 7 AT&T UNIX.



GNO                            23 February 1997                       POPEN(3)