Standard C Library Functions                            popen(3C)


NAME
     popen, pclose - initiate a pipe to or from a process

SYNOPSIS
     #include <stdio.h>

     FILE *popen(const char *command, const char *mode);

     int pclose(FILE *stream);


DESCRIPTION
     The popen() function creates a pipe between the calling pro-
     gram  and  the  command  to  be  executed.  The arguments to
     popen() are pointers to null-terminated strings.   The  com-
     mand  argument  consists  of a shell command line.  The mode
     argument is an I/O mode, either r for reading or w for writ-
     ing.  The  value  returned is a stream pointer such that one
     can write to the standard input of the command, if  the  I/O
     mode is w, by writing to the file stream (see intro(3)); and
     one can read from the standard output of the command, if the
     I/O mode is r, by reading from the file stream. Because open
     files are shared, a type r command may be used as  an  input
     filter  and a type w as an output filter. A trailing F char-
     acter can also be included in the mode argument as described
     in fopen(3C) to enable extended FILE facility.



     The environment of the executed command  will  be  as  if  a
     child  process  were  created  within the popen() call using
     fork(2). If  the  application  is  standard-conforming  (see
     standards(5)), the child is created as if invoked with the call:



     execl("/usr/xpg4/bin/sh", "sh", "-c",command, (char *)0);



     otherwise, the child is created as if invoked with the call:



     execl("/usr/bin/sh", "sh", "-c",command, (char *)0);



     The pclose() function closes a stream opened by  popen()  by
     closing  the  pipe.  It  waits for the associated process to
     terminate and returns the termination status of the  process
     running  the command language interpreter. This is the value
     returned by waitpid(3C). See wait.h(3HEAD) for more informa-
     tion on termination status.



RETURN VALUES
     Upon successful completion, popen() returns a pointer to  an
     open  stream  that can be used to read or write to the pipe.
     Otherwise, it returns a null pointer and may  set  errno  to
     indicate the error.



     Upon successful completion, pclose() returns the termination
     status  of  the  command language interpreter as returned by
     waitpid().  Otherwise, it returns -1 and sets errno to indi-
     cate the error.



ERRORS
     The popen() function will fail if:



     EMFILE  There are currently FOPEN_MAX or STREAM_MAX  streams
             open in the calling process.




     EINVAL  The mode argument is invalid.




     The popen() function may also set errno values as  described
     by fork(2) or pipe(2).



     There are no defined errors for pclose().



USAGE
     If the original and popen() processes concurrently  read  or
     write  a common file, neither should use buffered I/O. Prob-
     lems with an output filter may  be  forestalled  by  careful
     buffer   flushing,   for   example,   with   fflush()   (see
     fclose(3C)). A security hole exists through the IFS and PATH
     environment  variables.   Full  pathnames should be used (or
     PATH reset) and IFS should be set to space and tab (" \t").



     Even if the process has established a signal handler for
     SIGCHLD, it will not be called when the command terminates.
     Even if another thread in the same process issues a wait(3C)
     call, it will not interfere with the return value of pclose().
     Even if the process's signal handler for SIGCHLD has been set
     to ignore the signal, there will be no effect on pclose().



EXAMPLES
     Example 1 popen() example


     The following program will print on the standard output (see
     stdio(3C))  the names of files in the current directory with
     a .c suffix.



       #include <stdio.h>
       #include <stdlib.h>
       main()
       {
              char *cmd = "/usr/bin/ls *.c";
              char buf[BUFSIZ];
              FILE *ptr;

              if ((ptr = popen(cmd, "r")) != NULL) {
                      while (fgets(buf, BUFSIZ, ptr) != NULL)
                              (void) printf("%s", buf);
                      (void) pclose(ptr);
	      }
              return 0;
       }

     Example 2 system() replacement


     The following function can be used in a  multithreaded  pro-
     cess  in  place  of  the  most  common  usage  of the Unsafe
     system(3C) function:



       int my_system(const char *cmd)
       {
              FILE *p;

              if ((p = popen(cmd, "w")) == NULL)
                      return (-1);
              return (pclose(p));
       }


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | See below.                  |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


     The F character in the mode argument of popen() is Evolving.
     In  all  other  respects  this  function  is  Standard.  The
     pclose() function is Standard.



SEE ALSO
     ksh(1), pipe(2), fclose(3C), fopen(3C), posix_spawn(3C),
     stdio(3C), system(3C), wait(3C), waitpid(3C), wait.h(3HEAD),
     attributes(5), standards(5)