PHP Manual
Prev |  | Next

# proc_open

(PHP 4 CVS only)

proc_open -- Execute a command and open file pointers for input/output

## Description

resource proc_open ( string cmd, array descriptorspec, array pipes)

proc_open() is similar to popen() but provides a much greater degree of control over the program execution. `cmd` is the command to be executed by the shell. `descriptorspec` is an indexed array where the key represents the descriptor number and the value represents how PHP will pass that descriptor to the child process. `pipes` will be set to an indexed array of file pointers that correspond to PHP's end of any pipes that are created. The return value is a resource representing the process; you should free it using proc_close() when you are finished with it.

    $descriptorspec = array(
       0 => array("pipe", "r"),  // stdin is a pipe that the child will read from
       1 => array("pipe", "w"),  // stdout is a pipe that the child will write to
       2 => array("file", "/tmp/error-output.txt", "a"), // stderr is a file to write to
    );
    $process = proc_open("php", $descriptorspec, $pipes);
    if (is_resource($process)) {
        // $pipes now looks like this:
        // 0 => writeable handle connected to child stdin
        // 1 => readable handle connected to child stdout
        // Any error output will be appended to /tmp/error-output.txt

        fwrite($pipes[0], "<?php echo \"Hello World!\"; ?>");
        fclose($pipes[0]);

        while(!feof($pipes[1])) {
            echo fgets($pipes[1], 1024);
        }
        fclose($pipes[1]);
        // It is important that you close any pipes before calling
        // proc_close in order to avoid a deadlock
        $return_value = proc_close($process);

        echo "command returned $return_value\n";
    }

The file descriptor numbers in `descriptorspec` are not limited to 0, 1 and 2 - you may specify any valid file descriptor number and it will be passed to the child process. This allows your script to interoperate with other scripts that run as "co-processes". In particular, this is useful for passing passphrases to programs like PGP, GPG and openssl in a more secure manner. It is also useful for reading status information provided by those programs on auxillary file descriptors.

> Note: Windows compatibility: Descriptors beyond 2 (stderr) are made available to the child process as inheritable handles, but since the Windows architecture does not associate file descriptor numbers with low-level handles, the child process does not (yet) have a means of accessing those handles. Stdin, stdout and stderr work as expected.

> Note: This function was introduced in PHP 4.3.0.

> Note: If you only need a uni-directional (one-way) process pipe, use popen() instead, as it is much easier to use.

See also exec(), system(), passthru(), popen(), escapeshellcmd(), and the backtick operator.

Prev | Home | Next
proc_close | Up | shell_exec