<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.13 $ -->
 <reference id="ref.exec">
  <title>プログラム実行関数</title>
  <titleabbrev>プログラムの実行</titleabbrev>

  <partintro>
   <simpara>
    以下の関数は、システム自体の上でコマンドを実行したり、こうしたコマ
    ンドの安全に実行する手段を提供します。以下の関数は、
    <link linkend="language.operators.execution">backtick演算子</link>
    にも極めて深い関係があります。
   </simpara>
  </partintro>

  <refentry id="function.escapeshellarg">
   <refnamediv>
    <refname>escapeshellarg</refname>
    <refpurpose>シェル引数として使用される文字列をエスケープする</refpurpose>
   </refnamediv>
   <refsect1>
    <title>引数</title>
     <methodsynopsis>
      <type>string</type><methodname>escapeshellarg</methodname>
      <methodparam><type>string</type><parameter>arg</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>escapeshellarg</function> は、文字列をシングルクオート
     で括り、既存のシングルクオートを全てクオート/エスケープします。こ
     れにより、文字列を直接シェル関数に渡し、単一の安全な引数として処
     理することを可能にします。この関数は、ユーザー入力からの入力を
     シェル関数への引数として渡す際にエスケープするために使用する必要
     があります。シェル関数には、<function>exec</function>,
     <function>system</function>そして
     <link linkend="language.operators.execution">実行演算子</link>
     を含むシェル関数が含まれます。
     標準的な使用法は次のようになります。
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
system("ls ".escapeshellarg($dir));
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     <function>exec</function>, <function>popen</function>,
     <function>system</function>および<link
     linkend="language.operators.execution">実行演算子</link>
     も参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.escapeshellcmd">
   <refnamediv>
    <refname>escapeshellcmd</refname>
    <refpurpose>シェルのメタ文字をエスケープする</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>string</type><methodname>escapeshellcmd</methodname>
      <methodparam><type>string</type><parameter>command</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>escapeshellcmd</function>は、文字列中においてシェルコマ
     ンドをだまして勝手なコマンドを実行する可能性がある文字をエスケー
     プします。この関数は、ユーザに入力されたデータを関数
     <function>exec</function>または<function>system</function>または、
     <link linkend="language.operators.execution">backtick 演算子</link>
     に渡す前に全てエスケープを行う場合に使用するべきです。
     標準的な使い方は以下のようになるでしょう。
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
$e = escapeshellcmd($userinput);
system("echo $e"); // ここでは、$eにスペースがあるかは配慮していません
$f = escapeshellcmd($filename);
system("touch \"/tmp/$f\"; ls -l \"/tmp/$f\""); // こでは配慮し、クオートします
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     <function>escapeshellarg</function>,
     <function>exec</function>, <function>popen</function>,
     <function>system</function>, <link
      linkend="language.operators.execution">backtick 演算子</link>
      も参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.exec">
   <refnamediv>
    <refname>exec</refname>
    <refpurpose>外部プログラムを実行します</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>string</type><methodname>exec</methodname>
      <methodparam><type>string</type><parameter>command</parameter></methodparam>
      <methodparam><type>string</type><parameter>
	<replaceable><optional>array</optional></replaceable>
       </parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>return_var</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>exec</function>は指定された
     <parameter>command</parameter>を実行しますが、一切の出力はありま
     せん。ただ単に、コマンド結果の最後の行を返すだけです。コマンドを実行
     し、一切干渉を受けずに直接コマンドから全てのデータを受けとる必要が
     あるならば、<function>PassThru</function> 関数を使ってください。
    </para>
    <para>
     引数<parameter>array</parameter>が存在する場合、指定した配列は、
     コマンドからの出力の各行で埋められます。配列に既に何らかの要素が
     含まれる場合は、<function>exec</function>は配列の最後に追加される
     ことに注意してください。関数が要素を追加することを望まないのなら、
     それが <function>exec</function> に渡される前に、配列の
     <function>unset</function>を呼び出してください。
     引数<parameter>return_var</parameter>が、引数
     <parameter>array</parameter>と共に存在する場合、実行したコマンドの
     ステータスがこの変数に書かれます。
    </para>
    <para>
     ユーザ入力によるデータを、この関数に渡すことを許可したいのであれば、
     ユーザがシステムをだまして勝手なコマンドを実行できないように、
     <function>escapeshellcmd</function>を使うべきです。
    </para>
    <para>
     この関数を使用してプログラム実行を開始し、バックグラウンドで実行
     したままにしたい場合には、プログラムの出力をファイルまたは他の出
     力ストリームにリダイレクトする必要があることにも注意して下さい。
     さもないと、PHPはそのプログラムの実行が終了するまでハングします。
    </para>
    <para>
     <function>system</function>,<function>passthru</function>,
     <function>popen</function>,<function>escapeshellcmd</function>,
     <link linkend="language.operators.execution">backtick 演算子</link>
     も参照ください。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.passthru">
   <refnamediv>
    <refname>passthru</refname>
    <refpurpose>外部プログラムを実行し、未整形の出力を表示します</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>void</type><methodname>passthru</methodname>
      <methodparam><type>string</type><parameter>command</parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>return_var</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>passthru</function>関数は<function>exec</function>関数と同様、
     <parameter>command</parameter>を実行します。
     引数 <parameter>return_var</parameter> を指定した場合、
     Unix command のステータスで置換されます。
     この関数は Unix command からの出力がバイナリデータであり、
     ブラウザーへ直接返す必要がある場合、<function>exec</function>
     もしくは<function>system</function>の代わりに使用する必要があります。
     よく使うのは、直接画像ストリームを出力することができる pbmplus
     ユーティリティの様なものを実行する場合です。content-type を
     <emphasis>image/gif</emphasis>に設定して、gifを出力するpbmplus
     プログラムを呼び出すことにより、直接画像を出力する PHP スクリプトを作成
     することができます。
    </para>
    <para>
     この関数を使用してプログラム実行を開始し、バックグラウンドで実行
     したままにしたい場合には、プログラムの出力をファイルまたは他の出
     力ストリームにリダイレクトする必要があることにも注意して下さい。
     さもないと、PHPはそのプログラムの実行が終了するまでハングします。
    </para>
    <para>
     <function>exec</function>, 
     <function>system</function>, <function>popen</function>,
     <function>escapeshellcmd</function>, 
     <link linkend="language.operators.execution">backtick 演算子</link>
     も参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.system">
   <refnamediv>
    <refname>system</refname>
    <refpurpose>外部プログラムの実行と表示</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>string</type><methodname>system</methodname>
      <methodparam><type>string</type><parameter>command</parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>return_var</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>system</function>は、指定した
     <parameter>command</parameter>を実行し、結果を出力するC言語の
     system関数に似ています。2番目の引数として変数が指定された場合、実
     行したコマンドのステータスコードが、この変数に書き込まれます。
    </para>
    <warning>
     <para>
      ユーザが入力したデータをこの関数に渡そうとする場合、
      <function>escapeshellarg</function>または
      <function>escapeshellcmd</function>を使用して、ユーザがシステム
      をだまして、勝手なコマンドを実行することのないようにするべきです。
     </para>
    </warning>
    <note>
     <para>
      この関数を使用してプログラム実行を開始し、バックグラウンドで実行
      したままにしたい場合には、プログラムの出力をファイルまたは他の出
      力ストリームにリダイレクトする必要があることにも注意して下さい。
      さもないと、PHPはそのプログラムの実行が終了するまでハングします。
     </para>
    </note>
    <para>
     PHPをサーバモジュールとして実行している場合、
     <function>system</function>のコールにより、各行を出力した後、
     Webサーバの出力バッファが自動的にクリアされます。
    </para>
    <para>
     成功時にコマンド出力の最後の行が返され、失敗時に&false;が返されます。
    </para>
    <para>
     コマンドを実行し、何の加工もせずに全てのデータをコマンドから直接
    返す必要がある場合、<function>PassThru</function>関数をお使いくだ
    さい。
    </para>
    <para>
     <function>exec</function>, <function>PassThru</function>,
     <function>popen</function>,<function>EscapeShellCmd</function>, 
     <link linkend="language.operators.execution">backtick 演算子
     </link>を参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.shell-exec'>
   <refnamediv>
    <refname>shell_exec</refname>
    <refpurpose>
     シェルによりコマンドを実行し、文字列として出力全体を返す
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>string</type><methodname>shell_exec</methodname>
      <methodparam><type>string</type><parameter>cmd</parameter></methodparam>
     </methodsynopsis>
    <para>
     この演算子は、<link
     linkend="language.operators.execution">実行演算子</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:
-->