mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 17:08:54 +00:00
7839d91186
removing the others git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@78562 c90b9560-bf6c-de11-be94-00142212c4b1
455 lines
17 KiB
XML
455 lines
17 KiB
XML
<!-- D O N O T E D I T T H I S F I L E ! ! !
|
|
|
|
it is still here for historical reasons only
|
|
(as translators may need to check old revision diffs)
|
|
|
|
if you want to change things documented in this file
|
|
you should now edit the files found under en/reference
|
|
instead -->
|
|
|
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.30 $ -->
|
|
<reference id="ref.exec">
|
|
<title>Program Execution functions</title>
|
|
<titleabbrev>Program Execution</titleabbrev>
|
|
|
|
<partintro>
|
|
<simpara>
|
|
Those functions provides means to executes commands on the
|
|
system itself, and means secure such commands. Those functions
|
|
are also closely related to the
|
|
<link linkend="language.operators.execution">backtick operator</link>.
|
|
</simpara>
|
|
</partintro>
|
|
|
|
<refentry id="function.escapeshellarg">
|
|
<refnamediv>
|
|
<refname>escapeshellarg</refname>
|
|
<refpurpose>escape a string to be used as a shell argument</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>escapeshellarg</methodname>
|
|
<methodparam><type>string</type><parameter>arg</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>escapeshellarg</function> adds single quotes around a string
|
|
and quotes/escapes any existing single quotes allowing you to pass a
|
|
string directly to a shell function and having it be treated as a single
|
|
safe argument. This function should be used to escape individual
|
|
arguments to shell functions coming from user input. The shell functions
|
|
include <function>exec</function>, <function>system</function> and the
|
|
<link linkend="language.operators.execution">backtick operator</link>.
|
|
A standard use would be:</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
system("ls ".escapeshellarg($dir));
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
See also <function>exec</function>, <function>popen</function>,
|
|
<function>system</function>, and the <link
|
|
linkend="language.operators.execution">backtick operator</link>.
|
|
</para>
|
|
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.escapeshellcmd">
|
|
<refnamediv>
|
|
<refname>escapeshellcmd</refname>
|
|
<refpurpose>escape shell metacharacters</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>escapeshellcmd</methodname>
|
|
<methodparam><type>string</type><parameter>command</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>escapeshellcmd</function> escapes any characters in a
|
|
string that might be used to trick a shell command into executing
|
|
arbitrary commands. This function should be used to make sure
|
|
that any data coming from user input is escaped before this data
|
|
is passed to the <function>exec</function> or
|
|
<function>system</function> functions, or to the <link
|
|
linkend="language.operators.execution">backtick
|
|
operator</link>. A standard use would be:</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$e = escapeshellcmd($userinput);
|
|
system("echo $e"); // here we don't care if $e has spaces
|
|
$f = escapeshellcmd($filename);
|
|
system("touch \"/tmp/$f\"; ls -l \"/tmp/$f\""); // and here we do, so we use quotes
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
See also <function>escapeshellarg</function>, <function>exec</function>,
|
|
<function>popen</function>, <function>system</function>, and the <link
|
|
linkend="language.operators.execution">backtick operator</link>.
|
|
</para>
|
|
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.exec">
|
|
<refnamediv>
|
|
<refname>exec</refname>
|
|
<refpurpose>Execute an external program</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>exec</methodname>
|
|
<methodparam><type>string</type><parameter>command</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>array
|
|
</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>return_var</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>exec</function> executes the given
|
|
<parameter>command</parameter>, however it does not output
|
|
anything. It simply returns the last line from the result of the
|
|
command. If you need to execute a command and have all the data
|
|
from the command passed directly back without any interference,
|
|
use the <function>passthru</function> function.
|
|
</para>
|
|
<para>
|
|
If the <parameter>array</parameter> argument is present, then the
|
|
specified array will be filled with every line of output from the
|
|
command. Note that if the array already contains some elements,
|
|
<function>exec</function> will append to the end of the array.
|
|
If you do not want the function to append elements, call
|
|
<function>unset</function> on the array before passing it to
|
|
<function>exec</function>.
|
|
</para>
|
|
<para>
|
|
If the <parameter>return_var</parameter> argument is present
|
|
along with the <parameter>array</parameter> argument, then the
|
|
return status of the executed command will be written to this
|
|
variable.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
If you are going to allow data coming from user input to be passed to
|
|
this function, then you should be using
|
|
<function>escapeshellarg</function> or
|
|
<function>escapeshellcmd</function> to make sure that users cannot trick
|
|
the system into executing arbitrary commands.
|
|
</para>
|
|
</warning>
|
|
<note>
|
|
<para>
|
|
If you start a program using this function and want to leave it running
|
|
in the background, you have to make sure that the output of that program
|
|
is redirected to a file or some other output stream or else PHP will
|
|
hang until the execution of the program ends.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
See also <function>system</function>,
|
|
<function>passthru</function>, <function>popen</function>,
|
|
<function>escapeshellcmd</function>, and the <link
|
|
linkend="language.operators.execution">backtick operator</link>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.passthru">
|
|
<refnamediv>
|
|
<refname>passthru</refname>
|
|
<refpurpose>
|
|
Execute an external program and display raw output
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>passthru</methodname>
|
|
<methodparam><type>string</type><parameter>command</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>return_var</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
The <function>passthru</function> function is similar to the
|
|
<function>exec</function> function in that it executes a
|
|
<parameter>command</parameter>. If the
|
|
<parameter>return_var</parameter> argument is present, the return
|
|
status of the Unix command will be placed here. This function
|
|
should be used in place of <function>exec</function> or
|
|
<function>system</function> when the output from the Unix command
|
|
is binary data which needs to be passed directly back to the
|
|
browser. A common use for this is to execute something like the
|
|
pbmplus utilities that can output an image stream directly. By
|
|
setting the Content-type to <emphasis>image/gif</emphasis> and
|
|
then calling a pbmplus program to output a gif, you can create
|
|
PHP scripts that output images directly.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
If you are going to allow data coming from user input to be passed to
|
|
this function, then you should be using
|
|
<function>escapeshellarg</function> or
|
|
<function>escapeshellcmd</function> to make sure that users cannot trick
|
|
the system into executing arbitrary commands.
|
|
</para>
|
|
</warning>
|
|
<note>
|
|
<para>
|
|
If you start a program using this function and want to leave it running
|
|
in the background, you have to make sure that the output of that program
|
|
is redirected to a file or some other output stream or else PHP will
|
|
hang until the execution of the program ends.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
See also <function>exec</function>, <function>system</function>,
|
|
<function>popen</function>, <function>escapeshellcmd</function>,
|
|
and the <link linkend="language.operators.execution">backtick
|
|
operator</link>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id='function.proc-close'>
|
|
<refnamediv>
|
|
<refname>proc_close</refname>
|
|
<refpurpose>
|
|
Close a process opened by proc_open and return the exit code of that
|
|
process.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>proc_close</methodname>
|
|
<methodparam><type>resource</type><parameter>process</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>proc_close</function> is similar to <function>popen</function>
|
|
except that it only works on processes opened by
|
|
<function>proc_open</function>.
|
|
<function>proc_close</function> waits for the process to terminate, and
|
|
returns it's exit code. If you have open pipes to that process, you
|
|
should <function>fclose</function> them prior to calling this function in
|
|
order to avoid a deadlock - the child process may not be able to exit
|
|
while the pipes are open.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id='function.proc-open'>
|
|
<refnamediv>
|
|
<refname>proc_open</refname>
|
|
<refpurpose>
|
|
Execute a command and open file pointers for input/output
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>resource</type><methodname>proc_open</methodname>
|
|
<methodparam><type>string</type><parameter>cmd</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>descriptorspec</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>pipes</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>proc_open</function> is similar to <function>popen</function>
|
|
but provides a much greater degree of control over the program execution.
|
|
<parameter>cmd</parameter> is the command to be executed by the shell.
|
|
<parameter>descriptorspec</parameter> 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.
|
|
<parameter>pipes</parameter> 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 <function>proc_close</function> when you are finished
|
|
with it.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$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";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
The file descriptor numbers in <parameter>descriptorspec</parameter> 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.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
This function was introduced in PHP 4.3.0.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
If you only need a uni-directional (one-way) process pipe, use
|
|
<function>popen</function> instead, as it is much easier to use.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
See also <function>exec</function>, <function>system</function>,
|
|
<function>passthru</function>, <function>popen</function>,
|
|
<function>escapeshellcmd</function>, and the <link
|
|
linkend="language.operators.execution">backtick operator</link>.
|
|
</para>
|
|
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
|
|
<refentry id="function.system">
|
|
<refnamediv>
|
|
<refname>system</refname>
|
|
<refpurpose>Execute an external program and display output</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>system</methodname>
|
|
<methodparam><type>string</type><parameter>command</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>return_var</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>system</function> is just like the C version of the
|
|
function in that it executes the given
|
|
<parameter>command</parameter> and outputs the result. If a
|
|
variable is provided as the second argument, then the return
|
|
status code of the executed command will be written to this
|
|
variable.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
If you are going to allow data coming from user input to be passed to
|
|
this function, then you should be using
|
|
<function>escapeshellarg</function> or
|
|
<function>escapeshellcmd</function> to make sure that users cannot trick
|
|
the system into executing arbitrary commands.
|
|
</para>
|
|
</warning>
|
|
<note>
|
|
<para>
|
|
If you start a program using this function and want to leave it running
|
|
in the background, you have to make sure that the output of that program
|
|
is redirected to a file or some other output stream or else PHP will
|
|
hang until the execution of the program ends.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
The <function>system</function> call also tries to automatically
|
|
flush the web server's output buffer after each line of output if
|
|
PHP is running as a server module.
|
|
</para>
|
|
<para>
|
|
Returns the last line of the command output on success, and &false;
|
|
on failure.
|
|
</para>
|
|
<para>
|
|
If you need to execute a command and have all the data from the
|
|
command passed directly back without any interference, use the
|
|
<function>passthru</function> function.
|
|
</para>
|
|
<para>
|
|
See also <function>exec</function>,
|
|
<function>passthru</function>, <function>popen</function>,
|
|
<function>escapeshellcmd</function>, and the <link
|
|
linkend="language.operators.execution">backtick operator</link>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id='function.shell-exec'>
|
|
<refnamediv>
|
|
<refname>shell_exec</refname>
|
|
<refpurpose>
|
|
Execute command via shell and return complete output as string
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>shell_exec</methodname>
|
|
<methodparam><type>string</type><parameter>cmd</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function is identical to the <link
|
|
linkend="language.operators.execution">backtick operator</link>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
</reference>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|
|
|