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 command argument consists of a shell command line.  The
     mode  argument is an I/O mode, either r for reading or w for
     writing. 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/bin/ksh", "ksh", "-c", command, (char *)0);

     otherwise, the child is invoked with the call:

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

     A stream opened by popen() should  be  closed  by  pclose(),
     which  closes the pipe, and waits for the associated process
     to terminate and returns the termination status of the  pro-
     cess  running  the command language interpreter. This is the
     value returned by   waitpid(2).  See  wstat(3XFN)  for  more
     information on termination status.

RETURN VALUES
     The popen() function returns a  null  pointer  if  files  or
     processes cannot be created.

     The pclose() function returns the termination status of  the
     command.   It  returns -1 if stream is not associated with a
     popen() command and sets errno to indicate the error.

SunOS 5.8           Last change: 25 Mar 1998                    1

Standard C Library Functions                            popen(3C)

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

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);
             return 0;
     }

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

SunOS 5.8           Last change: 25 Mar 1998                    2

Standard C Library Functions                            popen(3C)

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Unsafe                      |
    |_____________________________|_____________________________|

SEE ALSO
     ksh(1), pipe(2), wait(2), waitpid(2), fclose(3C), fopen(3C),
     stdio(3C),  system(3C),  attributes(5),  wstat(3XFN),  standards(5)
     

SunOS 5.8           Last change: 25 Mar 1998                    3