socket-get-option.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.socket-get-option" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>socket_get_option</refname>
  <refpurpose>Gets socket options for the socket </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>
   The <function>socket_get_option</function> function retrieves the value for
   the option specified by the <parameter>option</parameter> parameter for the
   specified <parameter>socket</parameter>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>socket</parameter></term>
     <listitem>
      <para>
       A <classname>Socket</classname> instance created with <function>socket_create</function>
       or <function>socket_accept</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>level</parameter></term>
     <listitem>
      <para>
       The <parameter>level</parameter> parameter specifies the protocol
       level at which the option resides. For example, to retrieve options at
       the socket level, a <parameter>level</parameter> parameter of
       <constant>SOL_SOCKET</constant> would be used. Other levels, such as
       <constant>TCP</constant>, can be used by
       specifying the protocol number of that level. Protocol numbers can be
       found by using the <function>getprotobyname</function> function.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>option</parameter></term>
     <listitem>
      <table>
       <title>Available Socket Options</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>Option</entry>
          <entry>Description</entry>
          <entry>Type</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><constant>SO_DEBUG</constant></entry>
          <entry>
           Reports whether debugging information is being recorded.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_BROADCAST</constant></entry>
          <entry>
           Reports whether transmission of broadcast messages is supported.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_REUSEADDR</constant></entry>
          <entry>
           Reports whether local addresses can be reused.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_REUSEPORT</constant></entry>
          <entry>
           Reports whether local ports can be reused.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_KEEPALIVE</constant></entry>
          <entry>
           Reports whether connections are kept active with periodic transmission
           of messages. If the connected socket fails to respond to these messages,
           the connection is broken and processes writing to that socket are notified
           with a SIGPIPE signal.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_LINGER</constant></entry>
          <entry>
           <para>
            Reports whether the <parameter>socket</parameter> lingers on 
            <function>socket_close</function> if data is present. By default, 
            when the socket is closed, it attempts to send all unsent data.
            In the case of a connection-oriented socket, 
            <function>socket_close</function> will wait for its peer to
            acknowledge the data. 
           </para>
           <para>
            If <varname>l_onoff</varname> is non-zero and 
            <varname>l_linger</varname> is zero, all the 
            unsent data will be discarded and RST (reset) is sent to the 
            peer in the case of a connection-oriented socket. 
           </para>
           <para>
            On the other hand, if <varname>l_onoff</varname> is 
            non-zero and <varname>l_linger</varname> is non-zero,
            <function>socket_close</function> will block until all the data 
            is sent or the time specified in <varname>l_linger</varname>
            elapses. If the socket is non-blocking, 
            <function>socket_close</function> will fail and return an error.
           </para>
          </entry>
          <entry>
           <type>array</type>. The array will contain two keys:
           <varname>l_onoff</varname> and 
           <varname>l_linger</varname>. 
          </entry>
         </row>
         <row>
          <entry><constant>SO_OOBINLINE</constant></entry>
          <entry>
           Reports whether the <parameter>socket</parameter> leaves out-of-band data inline.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_SNDBUF</constant></entry>
          <entry>
           Reports the size of the send buffer.
          </entry>
          <entry>
           <type>int</type>
          </entry>          
         </row>
         <row>
          <entry><constant>SO_RCVBUF</constant></entry>
          <entry>
           Reports the size of the receive buffer.
          </entry>
          <entry>
           <type>int</type>
          </entry>         
         </row>
         <row>
          <entry><constant>SO_ERROR</constant></entry>
          <entry>
           Reports information about error status and clears it.
          </entry>
          <entry>
           <type>int</type> (cannot be set by <function>socket_set_option</function>)
          </entry>
         </row>
         <row>
          <entry><constant>SO_TYPE</constant></entry>
          <entry>
           Reports the <parameter>socket</parameter> type (e.g. 
           <constant>SOCK_STREAM</constant>).
          </entry>
          <entry>
           <type>int</type> (cannot be set by <function>socket_set_option</function>)
          </entry>
         </row>
         <row>
          <entry><constant>SO_DONTROUTE</constant></entry>
          <entry>
           Reports whether outgoing messages bypass the standard routing facilities.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_RCVLOWAT</constant></entry>
          <entry>
           Reports the minimum number of bytes to process for <parameter>socket</parameter> 
           input operations.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_RCVTIMEO</constant></entry>
          <entry>
           Reports the timeout value for input operations.
          </entry>
          <entry>
           <type>array</type>. The array will contain two keys:
           <varname>sec</varname> which is the seconds part on the timeout
           value and <varname>usec</varname> which is the microsecond part 
           of the timeout value. 
          </entry>
         </row>
         <row>
          <entry><constant>SO_SNDTIMEO</constant></entry>
          <entry>
           Reports the timeout value specifying the amount of time that an output
           function blocks because flow control prevents data from being sent.
          </entry>
          <entry>
           <type>array</type>. The array will contain two keys:
           <varname>sec</varname> which is the seconds part on the timeout
           value and <varname>usec</varname> which is the microsecond part 
           of the timeout value. 
          </entry>
         </row>
         <row>
          <entry><constant>SO_SNDLOWAT</constant></entry>
          <entry>
           Reports the minimum number of bytes to process for <parameter>socket</parameter> output operations.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_NODELAY</constant></entry>
          <entry>
           Reports whether the Nagle TCP algorithm is disabled.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_JOIN_GROUP</constant></entry>
          <entry>
           Joins a multicast group.
          </entry>
          <entry>
           <type>array</type> with keys <literal>"group"</literal>, specifying
           a <type>string</type> with an IPv4 or IPv6 multicast address and
           <literal>"interface"</literal>, specifying either an interface
           number (type <type>int</type>) or a <literal>string</literal> with
           the interface name, like <literal>"eth0"</literal>.
           <literal>0</literal> can be specified to indicate the interface
           should be selected using routing rules. (can only be used in
           <function>socket_set_option</function>)
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_LEAVE_GROUP</constant></entry>
          <entry>
           Leaves a multicast group.
          </entry>
          <entry>
           <type>array</type>. See <constant>MCAST_JOIN_GROUP</constant> for
           more information. (can only be used in
           <function>socket_set_option</function>)
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_BLOCK_SOURCE</constant></entry>
          <entry>
           Blocks packets arriving from a specific source to a specific
           multicast group, which must have been previously joined.
          </entry>
          <entry>
           <type>array</type> with the same keys as
           <constant>MCAST_JOIN_GROUP</constant>, plus one extra key,
           <literal>source</literal>, which maps to a <type>string</type>
           specifying an IPv4 or IPv6 address of the source to be blocked.
           (can only be used in <function>socket_set_option</function>)
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_UNBLOCK_SOURCE</constant></entry>
          <entry>
           Unblocks (start receiving again) packets arriving from a specific
           source address to a specific multicast group, which must have been
           previously joined.
          </entry>
          <entry>
           <type>array</type> with the same format as
           <constant>MCAST_BLOCK_SOURCE</constant>.
           (can only be used in <function>socket_set_option</function>)
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_JOIN_SOURCE_GROUP</constant></entry>
          <entry>
           Receive packets destined to a specific multicast group whose source
           address matches a specific value.
          </entry>
          <entry>
           <type>array</type> with the same format as
           <constant>MCAST_BLOCK_SOURCE</constant>.
           (can only be used in <function>socket_set_option</function>)
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_LEAVE_SOURCE_GROUP</constant></entry>
          <entry>
           Stop receiving packets destined to a specific multicast group whose
           source address matches a specific value.
          </entry>
          <entry>
           <type>array</type> with the same format as
           <constant>MCAST_BLOCK_SOURCE</constant>.
           (can only be used in <function>socket_set_option</function>)
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_IF</constant></entry>
          <entry>
           The outgoing interface for IPv4 multicast packets.
          </entry>
          <entry>
           Either <type>int</type> specifying the interface number or a
           <type>string</type> with an interface name, like
           <literal>eth0</literal>. The value <type>0</type> can be used to
           indicate the routing table is to used in the interface selection.
           The function <function>socket_get_option</function> returns an
           interface index.
           Note that, unlike the C API, this option does NOT take an IP
           address. This eliminates the interface difference between
           <constant>IP_MULTICAST_IF</constant> and
           <constant>IPV6_MULTICAST_IF</constant>.
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_IF</constant></entry>
          <entry>
           The outgoing interface for IPv6 multicast packets.
          </entry>
          <entry>
           The same as <constant>IP_MULTICAST_IF</constant>.
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_LOOP</constant></entry>
          <entry>
           The multicast loopback policy for IPv4 packets enables or disables
           loopback of outgoing multicasts, which must have been previously joined.
           The effect differs, however, whether it applies on unixes or Windows,
           the former being on the receive path whereas the latter being
           on the send path.
          </entry>
          <entry>
           <type>int</type> (either <literal>0</literal> or
           <literal>1</literal>). For <function>socket_set_option</function>
           any value will be accepted and will be converted to a boolean
           following the usual PHP rules.
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_LOOP</constant></entry>
          <entry>
           Analogous to <constant>IP_MULTICAST_LOOP</constant>, but for IPv6.
          </entry>
          <entry>
           <type>int</type>. See <constant>IP_MULTICAST_LOOP</constant>.
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_TTL</constant></entry>
          <entry>
           The time-to-live of outgoing IPv4 multicast packets. This should be
           a value between 0 (don't leave the interface) and 255. The default
           value is 1 (only the local network is reached).
          </entry>
          <entry>
           <type>int</type> between 0 and 255.
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_HOPS</constant></entry>
          <entry>
           Analogous to <constant>IP_MULTICAST_TTL</constant>, but for IPv6
           packets. The value -1 is also accepted, meaning the route default
           should be used.
          </entry>
          <entry>
           <type>int</type> between -1 and 255.
          </entry>
         </row>
         <row>
          <entry><constant>SO_MARK</constant></entry>
          <entry>
           Sets an identifier on the socket for packet filtering
           purpose on Linux.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_ACCEPTFILTER</constant></entry>
          <entry>
           Adds an accept filter on the listened socket (FreeBSD/NetBSD).
           An accept filter kernel module needs to be loaded beforehand
           on FreeBSD (e.g. accf_http).
          </entry>
          <entry>
           <type>string</type> name of the filter (length 15 max).
          </entry>
         </row>
         <row>
          <entry><constant>SO_USER_COOKIE</constant></entry>
          <entry>
           Sets an identifier on the socket for packet filtering
           purpose on FreeBSD.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_RTABLE</constant></entry>
          <entry>
           Sets an identifier on the socket for packet filtering
           purpose on OpenBSD.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_DONTTRUNC</constant></entry>
          <entry>
           Retain unread data.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_WANTMORE</constant></entry>
          <entry>
           Give a hint when more data is ready.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_DEFER_ACCEPT</constant></entry>
          <entry>
           Don't notify a listening socket until data is ready.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_INCOMING_CPU</constant></entry>
          <entry>
           Gets/Sets the cpu affinity of a socket.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_MEMINFO</constant></entry>
          <entry>
           Gets all the meminfo of a socket.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_BPF_EXTENSIONS</constant></entry>
          <entry>
           Gets the supported BPF extensions by the kernel to attach to a socket.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_SETFIB</constant></entry>
          <entry>
           Sets the route table (FIB) of a socket. (FreeBSD only)
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SOL_FILTER</constant></entry>
          <entry>
           Filters attributed to a socket. (Solaris/Illumos only)
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPCNT</constant></entry>
          <entry>
           Sets the maximum number of keepalive probes TCP should send before dropping the connection.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPIDLE</constant></entry>
          <entry>
           Sets the time the connection needs to remain idle.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPINTVL</constant></entry>
          <entry>
           Sets the time between individual keepalive probes.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPALIVE</constant></entry>
          <entry>
           Sets the time the connection needs to remain idle. (macOS only)
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_NOTSENT_LOWAT</constant></entry>
          <entry>
           Sets the limit number of unsent data in write queue by the socket stream. (Linux only)
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the value of the given option, &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> example</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
-->