socket-get-option.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e50e79746736dbdfbabe9bd3566793b3ddf38f58 Maintainer: songmeifeng Status: ready -->
<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> 参数指定的选项值。
  </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> 参数定义选项所在的协议级别。例如，在 socket 级别检索选项，将使用 <constant>SOL_SOCKET</constant> 
       作为 <parameter>level</parameter> 参数值。在其它级别，例如 TCP，可以使用该级别指定的协议号。协议号可以通过 <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>
            <parameter>socket</parameter> 执行 <function>socket_close</function> 
            时是否滞留残留数据。默认情况下，当关闭 socket 时，将尝试发送所有还未发送的数据。在面向连接的套接字中，<function>socket_close</function> 
            会等待对端确认接收数据。
           </para>
           <para>
            如果 <varname>l_onoff</varname> 不为零，且 <varname>l_linger</varname> 
            为零，对于面向连接的套接字，将丢弃所有未发送的数据，并发送给对端一个 RST（reset）报文。
           </para>
           <para>
            另外，如果 <varname>l_onoff</varname> 不为零，且 <varname>l_linger</varname> 
            不为零，<function>socket_close</function> 将阻塞，直到数据被发送完或者超过 <varname>l_linger</varname> 
            指定的时间。如果 socket 设置为非阻塞，<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>
           是否禁用 TCP Nagle 算法。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_JOIN_GROUP</constant></entry>
          <entry>
           加入多播组。
          </entry>
          <entry>
           <type>array</type> 包含 <literal>"group"</literal> 键，指定 <type>string</type> 
           类型的 IPv4 或 IPv6 多播地址；另一个键 <literal>"interface"</literal> 
           指定（<type>int</type> 类型）接口编号或是 <literal>string</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>
           <type>array</type>。详情见 <constant>MCAST_JOIN_GROUP</constant>。（仅在 <function>socket_set_option</function> 中使用）
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_BLOCK_SOURCE</constant></entry>
          <entry>
           在已加入的多播组上阻塞接收来自指定源的数据包。
          </entry>
          <entry>
           <type>array</type> 与 <constant>MCAST_JOIN_GROUP</constant> 
           有相同的键，额外增加 <type>string</type> 
           类型的 <literal>source</literal> 键，指定要阻塞的 IPv4 或 IPv6 源地址。（仅在 <function>socket_set_option</function> 中使用）
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_UNBLOCK_SOURCE</constant></entry>
          <entry>
           在已加入的多播组取消阻塞（继续接收）接收来自指定源的数据包。
          </entry>
          <entry>
           <type>array</type> 与 <constant>MCAST_BLOCK_SOURCE</constant> 格式相同。（仅在 <function>socket_set_option</function> 中使用）
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_JOIN_SOURCE_GROUP</constant></entry>
          <entry>
           接收源地址与指定多播组匹配的数据包。
          </entry>
          <entry>
           <type>array</type> 与 <constant>MCAST_BLOCK_SOURCE</constant> 格式相同。（仅在 <function>socket_set_option</function> 中使用）
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_LEAVE_SOURCE_GROUP</constant></entry>
          <entry>
           停止接收源地址与指定多播组匹配的数据包。
          </entry>
          <entry>
           <type>array</type> 与 <constant>MCAST_BLOCK_SOURCE</constant> 格式相同。（仅在 <function>socket_set_option</function> 中使用）
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_IF</constant></entry>
          <entry>
           IPv4 多播数据包的输出接口。
          </entry>
          <entry>
           使用 <type>int</type> 类型指定接口编号或使用 <type>string</type> 
           类型指定接口名，例如 <literal>eth0</literal>。<type>0</type> 
           表示选择接口时使用路由表。<function>socket_set_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>
           <type>int</type>（<literal>0</literal> 或 <literal>1</literal>）。<function>socket_get_option</function>
           可以接受任何值，并按照常规 PHP 规则转换为布尔值。
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_LOOP</constant></entry>
          <entry>
           与 <constant>IP_MULTICAST_LOOP</constant> 类似，但用于 IPv6。
          </entry>
          <entry>
           <type>int</type>。详情见 <constant>IP_MULTICAST_LOOP</constant>。
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_TTL</constant></entry>
          <entry>
           传出 IPv4 多播数据包的生存时间。这个值需要在 0（数据不传出）到 255 之间。默认值是 1（仅到达本地网络）。
          </entry>
          <entry>
           <type>int</type> 0 到 255 之间。
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_HOPS</constant></entry>
          <entry>
           与 <constant>IP_MULTICAST_TTL</constant> 类似，但用于 IPv6 数据包。-1 也可以被接受，表示使用默认路由。
          </entry>
          <entry>
           <type>int</type> -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>
           在（FreeBSD 或 NetBSD）监听套接字上添加接受过滤器。FreeBSD 中，需要预先加载接受过滤器内核模块（例如 accf_http）。
          </entry>
          <entry>
           <type>string</type> 过滤器名称（最大长度 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 亲和性。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_MEMINFO</constant></entry>
          <entry>
           获取套接字的内存信息。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_BPF_EXTENSIONS</constant></entry>
          <entry>
           为套接字附加内核支持的 BPF 扩展。
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_SETFIB</constant></entry>
          <entry>
           为套接字设置路由表（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 在断开连接前的最大保活探测次数。
          </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>
           设置各个保活探针的间隔时间。
          </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
-->