proc_nice
proc_terminate
Program Execution Functions
PHP Manual

# proc_open

(PHP 4 >= 4.3.0, PHP 5)

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

### Description

resource proc_open ( string `$cmd` , array `$descriptorspec` , array `&$pipes` [, string `$cwd` [, array `$env` [, array `$other_options` ]]] )

proc_open() is similar to popen() but provides a much greater degree of control over the program execution.

### Parameters

`cmd`

  The command to execute

`descriptorspec`

  An indexed array where the key represents the descriptor number and the value represents how PHP will pass that descriptor to the child process. 0 is stdin, 1 is stdout, while 2 is stderr.

  The currently supported pipe types are file and pipe .

  The file descriptor numbers 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 auxiliary file descriptors.

`pipes`

  Will be set to an indexed array of file pointers that correspond to PHP's end of any pipes that are created.

`cwd`

  The initial working dir for the command. This must be an absolute directory path, or `NULL` if you want to use the default value (the working dir of the current PHP process)

`env`

  An array with the environment variables for the command that will be run, or `NULL` to use the same environment as the current PHP process

`other_options`

  Allows you to specify additional options. Currently supported options include:

  - suppress_errors (windows only): suppresses errors generated by this function when it's set to `TRUE`
  - bypass_shell (windows only): bypass cmd.exe shell when set to `TRUE`
  - context: stream context used when opening files (created with stream_context_create())
  - binary_pipes: open pipes in binary mode, instead of using the usual stream_encoding

### Return Values

Returns a resource representing the process, which should be freed using proc_close() when you are finished with it. On failure returns `FALSE`.

### ChangeLog

Version | Description
--- | ---
6.0.0 | Added the context and binary_pipes options to the `other_options` parameter.
5.2.1 | Added the bypass_shell option to the `other_options` parameter.
5.0.0 | Added the `cwd` , `env` and `other_options` parameters.

### Examples

Example#1 A proc_open() example

`<?php
$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
);
$cwd = '/tmp';
$env = array('some_option' => 'aeiou');
$process = proc_open('php', $descriptorspec, $pipes, $cwd, $env);
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 print_r($_ENV); ?>');
fclose($pipes[0]);
echo stream_get_contents($pipes[1]);
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 above example will output something similar to:

    Array
    (
        [some_option] => aeiou
        [PWD] => /tmp
        [SHLVL] => 1
        [_] => /usr/local/bin/php
    )
    command returned 0

### Notes

> 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: If you only need a uni-directional (one-way) process pipe, use popen() instead, as it is much easier to use.

### See Also

- popen()
- exec()
- system()
- passthru()
- stream_select()
- The backtick operator

proc_nice
proc_terminate
Program Execution Functions
PHP Manual