popen(S)                       6 January 1993                       popen(S)


 Name

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

 Syntax


    cc  . . .  -lc


    #include <stdio.h>

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

    int pclose (stream)
    FILE *stream;


 Description

    The popen function creates a pipe between the calling program and the
    command to be executed. The arguments to popen are pointers to null-
    terminated strings.  command consists of a shell command line.  type 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; and one can
    read from the standard output of the command, if the I/O mode is r, by
    reading from the file stream.

    A stream opened by popen should be closed by pclose, which waits for the
    associated process to terminate and returns the exit status of the com-
    mand.

    Because open files are shared, a type r command may be used as an input
    filter and a type w as an output filter.

 Example

    A typical call may be:


       char *cmd = "ls *.c";
       FILE *ptr;
       if ((ptr = popen(cmd, "r")) != NULL)
             while (fgets(buf, n, ptr) != NULL)
                     (void) printf("%s ",buf);


    This prints in stdout (see stdio(S)) all the file names in the current
    directory that have a ``.c'' suffix.

 Diagnostics

    The popen function returns a NULL pointer if files or processes cannot be
    created.

    The pclose function returns -1 if stream is not associated with a command
    opened with the popen routine.

 Warnings

    If the original and those processes opened with popen concurrently read
    or write a common file, neither should use buffered I/O.  Problems with
    an output filter may be forestalled by careful buffer flushing, for exam-
    ple, with fflush(S).

    On UNIX systems, pclose uses waitpid(S) to wait for the child process
    executing the command to terminate.  On XENIX systems, pclose uses
    wait(S).  If the function evaluated on receipt of a SIGCLD signal is set
    to SIGIGN, then the behavior of pclose depends on which type of system
    the process is running on.  On UNIX systems, pclose will return a status
    of -1, and set errno to ECHILD.  On XENIX systems, pclose will block the
    process until all child processed terminate, and then return a status of
    -1, and set errno to ECHILD.  However, a deadlock occurs because the
    child process that executed the command will not terminate until its
    parent receives its SIGCLD signal.

 See also

    fclose(S), fflush(S), fopen(S), pipe(S), wait(S), stdio(S), system(S)

 Standards conformance

    pclose and popen are conformant with:
    AT&T SVID Issue 2;
    and X/Open Portability Guide, Issue 3, 1989.