socket-get-option.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e50e79746736dbdfbabe9bd3566793b3ddf38f58 Maintainer: takagi Status: ready -->
<!-- Credits: mumumu -->
<refentry xml:id="function.socket-get-option" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>socket_get_option</refname>
  <refpurpose>ソケットのオプションを取得する</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>int</type><type>false</type></type><methodname>socket_get_option</methodname>
   <methodparam><type>Socket</type><parameter>socket</parameter></methodparam>
   <methodparam><type>int</type><parameter>level</parameter></methodparam>
   <methodparam><type>int</type><parameter>option</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>socket_get_option</function> 関数は、ソケット
   <parameter>socket</parameter> のオプション <parameter>option</parameter>
   の値を取得します。<function>socket_get_option</function> は、失敗した場合に
   &false; を返します。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>socket</parameter></term>
     <listitem>
      <para>
       <function>socket_create</function> あるいは <function>socket_accept</function>
       で作成した <classname>Socket</classname> クラスのインスタンス。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>level</parameter></term>
     <listitem>
      <para>
       <parameter>level</parameter> パラメータは、オプションのプロトコルレベルを指定します。
       例えば、オプションをソケットレベルで取得するには
       <parameter>level</parameter> パラメータに <constant>SOL_SOCKET</constant> を指定します。
       <constant>TCP</constant> のようなそれ以外のレベルの場合、そのレベルのプロトコル番号を指定します。
       プロトコル番号は <function>getprotobyname</function>
       関数を使用して取得可能です。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>option</parameter></term>
     <listitem>
      <table>
       <title>使用可能なソケットオプション</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>オプション</entry>
          <entry>説明</entry>
          <entry>型</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><constant>SO_DEBUG</constant></entry>
          <entry>
           デバッグ情報を記録するかどうかを報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_BROADCAST</constant></entry>
          <entry>
           ブロードキャストメッセージの送信がサポートされているかどうかを報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_REUSEADDR</constant></entry>
          <entry>
           ローカルアドレスが再利用可能かどうかを報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_REUSEPORT</constant></entry>
          <entry>
           ローカルポートが再利用可能かどうかを報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_KEEPALIVE</constant></entry>
          <entry>
           定期的なメッセージの送信によって接続がアクティブになっているかどうかを報告します。
           もしソケットがこれらのメッセージに応答できなかった場合、
           接続は崩壊し、ソケットへの書き込みを行うと SIGPIPE シグナルを受け取ります。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_LINGER</constant></entry>
          <entry>
           <para>
            データがまだ残っているうちに <function>socket_close</function>
            をコールした場合に、<parameter>socket</parameter> を残存させるかどうかを報告します。
            デフォルトでは、ソケットが閉じられる際には未送信のデータをすべて送信しようとします。
            接続ベースのソケットでは、
            <function>socket_close</function> は接続先がデータを認識するまで閉じるのを待ちます。
           </para>
           <para>
            <varname>l_onoff</varname> が非ゼロで
            <varname>l_linger</varname> がゼロの場合は、
            その時点で未送信のデータはすべて破棄されます。
            接続ベースのソケットの場合、接続先には RST (リセット)
            を送信します。
           </para>
           <para>
            一方 <varname>l_onoff</varname> が非ゼロで
            <varname>l_linger</varname> も非ゼロの場合は、
            <function>socket_close</function> は
            全データを送信し終えるか <varname>l_linger</varname>
            で指定した時間が経過するまで処理をブロックします。
            ソケットが非ブロックモードの場合は、
            <function>socket_close</function> は失敗してエラーを返します。
           </para>
          </entry>
          <entry>
           <type>array</type>。配列に含まれるキーは
           <varname>l_onoff</varname> および
           <varname>l_linger</varname> のふたつ。
          </entry>
         </row>
         <row>
          <entry><constant>SO_OOBINLINE</constant></entry>
          <entry>
           <parameter>socket</parameter>
           が帯域外のデータをインラインに残し続けるかを報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_SNDBUF</constant></entry>
          <entry>
           送信バッファのサイズを報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>          
         </row>
         <row>
          <entry><constant>SO_RCVBUF</constant></entry>
          <entry>
           受信バッファのサイズを報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>         
         </row>
         <row>
          <entry><constant>SO_ERROR</constant></entry>
          <entry>
           エラーステータスに関する情報を報告し、それをクリアします。
          </entry>
          <entry>
           <type>int</type> (<function>socket_set_option</function> で設定することはできません)
          </entry>
         </row>
         <row>
          <entry><constant>SO_TYPE</constant></entry>
          <entry>
           <parameter>socket</parameter> の型 (たとえば <constant>SOCK_STREAM</constant>) を報告します。
          </entry>
          <entry>
           <type>int</type> (<function>socket_set_option</function> で設定することはできません)
          </entry>
         </row>
         <row>
          <entry><constant>SO_DONTROUTE</constant></entry>
          <entry>
           送信メッセージがルータを越えるかどうかを報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_RCVLOWAT</constant></entry>
          <entry>
           <parameter>socket</parameter> の入力操作を行う際の最小バイト数を報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_RCVTIMEO</constant></entry>
          <entry>
           入力操作のタイムアウト値を報告します。
          </entry>
          <entry>
           <type>array</type>。配列に含まれるキーはふたつ。
           <varname>sec</varname> はタイムアウトの秒単位の部分で、
           <varname>usec</varname> はタイムアウトのマイクロ秒位の部分。
          </entry>
         </row>
         <row>
          <entry><constant>SO_SNDTIMEO</constant></entry>
          <entry>
           出力関数がフロー制御のためにブロックするタイムアウト値を報告します。
          </entry>
          <entry>
           <type>array</type>。配列に含まれるキーはふたつ。
           <varname>sec</varname> はタイムアウトの秒単位の部分で、
           <varname>usec</varname> はタイムアウトのマイクロ秒位の部分。
          </entry>
         </row>
         <row>
          <entry><constant>SO_SNDLOWAT</constant></entry>
          <entry>
           <parameter>socket</parameter>
           の出力操作を行う際の最小バイト数を報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_NODELAY</constant></entry>
          <entry>
           Nagle TCP アルゴリズムが無効になっているかどうかを報告します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_JOIN_GROUP</constant></entry>
          <entry>
           マルチキャストグループに参加します。
          </entry>
          <entry>
           二つのキー <literal>"group"</literal> と <literal>"interface"</literal>
           を含む配列。<literal>"group"</literal> には IPv4 あるいは IPv6
           のマルチキャストアドレスを文字列で指定します。
           <literal>"interface"</literal> には、インターフェイス番号 (整数値)
           あるいは <literal>"eth0"</literal> などのインターフェイス名 (文字列) を指定します。
           <literal>0</literal> を指定すると、ルーティングテーブルを使ってインターフェイスを選択します
           (<function>socket_set_option</function> でのみ利用可能)。
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_LEAVE_GROUP</constant></entry>
          <entry>
           マルチキャストグループから離れます。
          </entry>
          <entry>
           配列。詳細は <constant>MCAST_JOIN_GROUP</constant> を参照ください
           (<function>socket_set_option</function> でのみ利用可能)。
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_BLOCK_SOURCE</constant></entry>
          <entry>
           特定のソースから、そのマルチキャストグループにやってくるパケットをブロックします。
           そのマルチキャストグループに事前に参加しておく必要があります。
          </entry>
          <entry>
           <constant>MCAST_JOIN_GROUP</constant> と同じキーを含み、さらに追加でもうひとつのキーを含む配列。
           追加のキーは <literal>source</literal> で、
           ブロック対象となるソースの IPv4 アドレスあるいは IPv6 アドレスを文字列で指定します
           (<function>socket_set_option</function> でのみ利用可能)。
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_UNBLOCK_SOURCE</constant></entry>
          <entry>
           特定のソースから、そのマルチキャストグループにやってくるパケットのブロックを解除 (そして、受信を再開) します。
           そのマルチキャストグループに事前に参加しておく必要があります。
          </entry>
          <entry>
           <constant>MCAST_BLOCK_SOURCE</constant> と同じ形式の配列
           (<function>socket_set_option</function> でのみ利用可能)。
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_JOIN_SOURCE_GROUP</constant></entry>
          <entry>
           特定の値にマッチするソースアドレスからそのマルチキャストグループにやってきたパケットを受信します。
          </entry>
          <entry>
           <constant>MCAST_BLOCK_SOURCE</constant> と同じ形式の配列
           (<function>socket_set_option</function> でのみ利用可能)。
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_LEAVE_SOURCE_GROUP</constant></entry>
          <entry>
           特定の値にマッチするソースアドレスからそのマルチキャストグループにやってきたパケットの受信を停止します。
          </entry>
          <entry>
           <constant>MCAST_BLOCK_SOURCE</constant> と同じ形式の配列
           (<function>socket_set_option</function> でのみ利用可能)。
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_IF</constant></entry>
          <entry>
           IPv4 マルチキャストパケットの送信インターフェイス。
          </entry>
          <entry>
           インターフェイス番号を表す整数値か、インターフェイス名を表す
           <literal>eth0</literal> のような文字列。
           <type>0</type> を指定すると、ルーティングテーブルを使ってインターフェイスを選択します。
           <function>socket_get_option</function> 関数の戻り値は、インターフェイスのインデックスとなります。
           注意すべき点は、C の API とは違ってこのオプションには IP アドレスを渡せないということです。
           そのため、
           <constant>IP_MULTICAST_IF</constant> と
           <constant>IPV6_MULTICAST_IF</constant> のインターフェイスの相違はなくなります。
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_IF</constant></entry>
          <entry>
           IPv6 マルチキャストパケットの送信インターフェイス。
          </entry>
          <entry>
           <constant>IP_MULTICAST_IF</constant> と同じ。
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_LOOP</constant></entry>
          <entry>
           IPv4 パケットのマルチキャストループバックポリシー。
           これを有効にすると、以前に参加したグループに、
           マルチキャストのデータをループバックさせることができます。
           このオプションの効果は、unix で有効にするか
           Windows で有効にするかで異なります。
           前者は受信先のパスに影響するのに対し、
           後者では送信元のパスに影響します。
          </entry>
          <entry>
           整数値 (<literal>0</literal> あるいは
           <literal>1</literal>)。<function>socket_set_option</function>
           では任意の値を受け付けますが、通常の PHP のルールに従ってそれを
           boolean 値に変換します。
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_LOOP</constant></entry>
          <entry>
           <constant>IP_MULTICAST_LOOP</constant> の IPv6 版。
          </entry>
          <entry>
           整数値。<constant>IP_MULTICAST_LOOP</constant> を参照ください。
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_TTL</constant></entry>
          <entry>
           IPv4 送信パケットの有効期間。0 (このインターフェイスから離れない)
           から 255 までの値を指定しなければなりません。デフォルトは
           1 (ローカルネットワークにだけ到達する) です。
          </entry>
          <entry>
           0 から 255 までの整数値。
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_HOPS</constant></entry>
          <entry>
           <constant>IP_MULTICAST_TTL</constant> の IPv6 版。
           値として -1 を指定することもでき、これはデフォルトのルートを使うことを意味します。
          </entry>
          <entry>
           -1 から 255 までの整数値。
          </entry>
         </row>
         <row>
          <entry><constant>SO_MARK</constant></entry>
          <entry>
           Linux でパケットフィルタを行う目的で、
           ソケットの識別子を設定します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_ACCEPTFILTER</constant></entry>
          <entry>
           listen しているソケットに対し、accept filter を追加します (FreeBSD/NetBSD)。
           accept filter カーネルモジュールは、FreeBSD では前もってロードしておく必要があります
           (e.g. accf_http)。
          </entry>
          <entry>
           フィルタの名前を示す文字列 (最大15文字)
          </entry>
         </row>
         <row>
          <entry><constant>SO_USER_COOKIE</constant></entry>
          <entry>
           FreeBSD でパケットフィルタを行う目的で、
           ソケットの識別子を設定します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_RTABLE</constant></entry>
          <entry>
           OpenBSD でパケットフィルタを行う目的で、
           ソケットの識別子を設定します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_DONTTRUNC</constant></entry>
          <entry>
           未読のデータを保持します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_WANTMORE</constant></entry>
          <entry>
           さらにデータが読み取れる時にヒントを与えます。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_DEFER_ACCEPT</constant></entry>
          <entry>
           データが利用可能になるまでソケットに通知しません。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_INCOMING_CPU</constant></entry>
          <entry>
           ソケットの CPU affinity の情報を取得/設定します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_MEMINFO</constant></entry>
          <entry>
           ソケットの meminfo を全て取得します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_BPF_EXTENSIONS</constant></entry>
          <entry>
           ソケットにアタッチするための、
           kernel がサポートしている BPF 拡張を取得します。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_SETFIB</constant></entry>
          <entry>
           ソケットの route table (FIB) を設定します(FreeBSD のみ)
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SOL_FILTER</constant></entry>
          <entry>
           ソケットの属性をフィルタします(Solaris/Illumos のみ)
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPCNT</constant></entry>
          <entry>
           接続を切断する前に、TCP が送信すべき keepalive プローブの最大数を設定します
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPIDLE</constant></entry>
          <entry>
           接続がアイドル状態である必要がある、時間を設定します
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPINTVL</constant></entry>
          <entry>
           個別の keepalive プローブを送信する間隔を設定します
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPALIVE</constant></entry>
          <entry>
           接続がアイドル状態である必要がある、時間を設定します(macOS のみ)
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_NOTSENT_LOWAT</constant></entry>
          <entry>
           ソケットストリームの書き込みキュー中の、未送信のデータ数を制限します(Linuxのみ)
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   指定したオプションの値を返します。
   &return.falseforfailure;
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     &sockets.changelog.socket-param;
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>socket_get_option</function> の例</title>
    <programlisting role="php">
<![CDATA[
<?php
$socket = socket_create_listen(1223);

$linger = array('l_linger' => 1, 'l_onoff' => 1);
socket_set_option($socket, SOL_SOCKET, SO_LINGER, $linger);

var_dump(socket_get_option($socket, SOL_SOCKET, SO_REUSEADDR));
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>socket_create_listen</function></member>
    <member><function>socket_set_option</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- 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:"~/.phpdoc/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
-->