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.

     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 invoked with the call:

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

     otherwise, the child is 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(2). See wstat(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 may fail if:

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

     EINVAL
           The mode argument is invalid.

     The pclose() function will fail if:

     ECHILD
           The status of the child process could not be obtained,
           as described above.

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


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").

     The signal handler for SIGCHLD should be set to default when
     using  popen().  If  the  process  has  established a signal
     handler for SIGCHLD, it will be called when the command ter-
     minates.   If  the  signal  handler or another thread in the
     same process issues a wait(2) call, it will  interfere  with
     the  return  value  of  pclose().  If  the  process's signal
     handler for SIGCHLD has  been  set  to  ignore  the  signal,
     pclose() will fail and errno will be set to ECHILD.


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 code fragment can be used in  a  multithreaded
     process in place of the MT-Unsafe system(3C) function:

     pclose(popen(cmd, "w"));


ATTRIBUTES

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO

     ksh(1), pipe(2), wait(2), waitpid(2), fclose(3C), fopen(3C),
     stdio(3C),  system(3C),  wstat(3HEAD),  attributes(5), stan-
     dards(5)


Man(1) output converted with man2html