PROC_OPEN(3)								 1							      PROC_OPEN(3)

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

SYNOPSIS

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

DESCRIPTION

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

PARAMETERS

	      o $cmd
		- The command to execute

	      o $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.	Each element can be:

		     oAn array describing the pipe to pass to the process. The first element is the descriptor type and the second element  is	an
		     option for the given type. Valid types are
		       pipe  (the second element is either r to pass the read end of the pipe to the process, or w to pass the write end) and file
		       (the second element is a filename).

		     o A stream resource representing a real file descriptor (e.g. opened file, a socket,
		       STDIN).

	       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.

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

	      o $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)

	      o $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

	      o $other_options
		- Allows you to specify additional options. Currently supported options include:

		     o suppress_errors (windows only): suppresses errors generated by this function when it's set to TRUE

		     o bypass_shell (windows only): bypass cmd.exe shell when set to TRUE

RETURN VALUES

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

CHANGELOG

       +--------+---------------------------------------------------+
       |Version |						    |
       |	|						    |
       |	|		     Description		    |
       |	|						    |
       +--------+---------------------------------------------------+
       | 5.2.1	|						    |
       |	|						    |
       |	|  Added   the	 bypass_shell	option	  to	the |
       |	| $other_options parameter.			    |
       |	|						    |
       +--------+---------------------------------------------------+
EXAMPLES

       Example #1

	      A proc_open(3) 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
";
	      }
	      ?>

	      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(3) instead, as it is much easier to use.

SEE ALSO

       popen(3), exec(3), system(3), passthru(3), stream_select(3), The backtick operator.

PHP Documentation Group 													      PROC_OPEN(3)