socket-get-option.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: eb1f12738221677a2d94d94e8dbddd88c6143c94 Maintainer: nobody Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: c0954ae4e632d2583118a7946681191a08c45eba Reviewer: samesch -->
<refentry xml:id="function.socket-get-option" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>socket_get_option</refname>
  <refpurpose>Liefert die Socket-Optionen für einen 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>
   <function>socket_get_option</function> gibt den Wert der Option zurück, die
   im Parameter <parameter>option</parameter> für den Socket
   <parameter>socket</parameter> angegeben wurde.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>socket</parameter></term>
     <listitem>
      <para>
       Eine <classname>Socket</classname>-Instanz, die mit der Funktion
       <function>socket_create</function> oder
       <function>socket_accept</function> erzeugt wurde.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>level</parameter></term>
     <listitem>
      <para>
       Der Parameter <parameter>level</parameter> enthält die Protokollebene,
       für die die Option gilt. Beispiel: Um Optionen auf der Socketebene
       abzufragen, würde <parameter>level</parameter> den Wert
       <constant>SOL_SOCKET</constant> enthalten. Andere Ebenen, etwa
       <constant>TCP</constant>, können abgefragt werden, indem man die
       Protokollnummer dieser Ebene angibt. Protokollnummern können mit einem
       Aufruf von <function>getprotobyname</function> ermittelt werden.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>option</parameter></term>
     <listitem>
      <table>
       <title>Mögliche Socket-Optionen</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>Option</entry>
          <entry>Beschreibung</entry>
          <entry>Typ</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><constant>SO_DEBUG</constant></entry>
          <entry>
           Gibt an, ob Debug-Informationen mitgeschrieben werden.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_BROADCAST</constant></entry>
          <entry>
           Gibt an, ob die Übermittlung von Rundsende-Nachrichten unterstützt
           wird.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_REUSEADDR</constant></entry>
          <entry>
           Gibt an, ob lokale Adressen wiederverwendet werden können.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_REUSEPORT</constant></entry>
          <entry>
           Gibt an, ob lokale Ports wiederverwendet werden können.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_KEEPALIVE</constant></entry>
          <entry>
           Gibt an, ob Verbindungen durch periodische Aussendungen von
           Nachrichten aufrecht erhalten werden. Falls der verbundene Socket
           nicht auf diese Nachrichten antwortet, wird die Verbindung
           unterbrochen und Prozesse, die auf diesen Socket schreiben,
           erhalten ein SIGPIPE-Signal.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_LINGER</constant></entry>
          <entry>
           <para>
            Gibt an, ob der <parameter>socket</parameter> einen Aufruf von
            <function>socket_close</function> verzögert, falls noch Daten
            vorhanden sind. In der Standardeinstellung versucht ein Socket vor
            dem Schließen, alle noch nicht gesendeten Daten zu übermitteln. Im
            Falle eines verbindungsorientierten Sockets wartet
            <function>socket_close</function> auf die Empfangsbestätigung
            seiner Gegenstelle.
           </para>
           <para>
            Falls <varname>l_onoff</varname> von 0 verschieden und
            <varname>l_linger</varname> gleich 0 ist, werden alle noch nicht
            gesendeten Daten verworfen und im Fall eines
            verbindungsorientierten Sockets das Signal RST (Reset) an die
            Gegenstelle gesendet.
           </para>
           <para>
            Andererseits, falls sowohl <varname>l_onoff</varname> als auch
            <varname>l_linger</varname> von 0 verschieden sind, blockiert der
            Aufruf von <function>socket_close</function> den Socket so lange,
            bis entweder alle Daten gesendet sind oder das Zeitlimit erreicht
            ist, das in <varname>l_linger</varname> gesetzt wurde. Wenn der
            Socket auf nicht-blockieren gesetzt ist, schlägt
            <function>socket_close</function> fehl und gibt einen Fehler
            zurück.
           </para>
          </entry>
          <entry>
           <type>array</type>. Das Array enthält zwei Schlüssel:
           <varname>l_onoff</varname> und
           <varname>l_linger</varname>.
          </entry>
         </row>
         <row>
          <entry><constant>SO_OOBINLINE</constant></entry>
          <entry>
           Gibt an, ob <parameter>socket</parameter> die Übertragung von
           bandexternen Daten in der Reihenfolge überträgt, wie sie auftreten.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_SNDBUF</constant></entry>
          <entry>
           Gibt die Größe des Sendepuffers zurück.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_RCVBUF</constant></entry>
          <entry>
           Gibt die Größe des Empfangspuffers zurück.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_ERROR</constant></entry>
          <entry>
           Gibt den Fehlerstatus zurück und löscht ihn.
          </entry>
          <entry>
           <type>int</type> (dieser Wert kann nicht von
           <function>socket_set_option</function> gesetzt werden.)
          </entry>
         </row>
         <row>
          <entry><constant>SO_TYPE</constant></entry>
          <entry>
           Gibt den Typ von <parameter>socket</parameter> zurück (&zb;
           <constant>SOCK_STREAM</constant>).
          </entry>
          <entry>
           <type>int</type> (dieser Wert kann nicht von
           <function>socket_set_option</function> gesetzt werden.)
          </entry>
         </row>
         <row>
          <entry><constant>SO_DONTROUTE</constant></entry>
          <entry>
           Gibt an, ob ausgehende Nachrichten das standardmäßige Routing
           umgehen.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_RCVLOWAT</constant></entry>
          <entry>
           Gibt die Mindestanzahl Bytes an, die <parameter>socket</parameter>
           bei einer Empfangsoperation verarbeiten soll.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_RCVTIMEO</constant></entry>
          <entry>
           Gibt bei Empfangsoperationen den Wert der Zeitspanne bis zu einer
           Zeitüberschreitung an.
          </entry>
          <entry>
           <type>array</type>. Das Array enthält zwei Schlüssel:
           <varname>sec</varname> ist der Sekunden-Anteil der Zeitspanne und
           <varname>usec</varname> der Mikrosekunden-Anteil der Zeitspanne bis
           zu einer Zeitüberschreitung.
          </entry>
         </row>
         <row>
          <entry><constant>SO_SNDTIMEO</constant></entry>
          <entry>
           Gibt die Zeitspanne an, nach der bei Sendeoperationen eine
           Zeitüberschreitung ausgelöst wird. Eine Ausgabefunktion darf
           während der angegebenen Zeitspanne blockieren, falls die
           Ablaufsteuerung den Versand der Daten verhindert.
          </entry>
          <entry>
           <type>array</type>. Das Array enthält zwei Schlüssel:
           <varname>sec</varname> ist der Sekunden-Anteil der Zeitspanne und
           <varname>usec</varname> der Mikrosekunden-Anteil der Zeitspanne bis
           zu einer Zeitüberschreitung.
          </entry>
         </row>
         <row>
          <entry><constant>SO_SNDLOWAT</constant></entry>
          <entry>
           Gibt die Mindestanzahl Bytes an, die <parameter>socket</parameter>
           bei einer Ausgabeoperation verarbeiten soll.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_NODELAY</constant></entry>
          <entry>
           Gibt an, ob der Nagle-TCP-Algorithmus deaktiviert ist.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_JOIN_GROUP</constant></entry>
          <entry>
           Tritt einer Multicast-Gruppe bei.
          </entry>
          <entry>
           <type>array</type> mit den Schlüsseln <literal>"group"</literal>,
           der eine IPv4 oder IPv6 Multicast-Adresse als <type>String</type>
           angibt, und <literal>"interface"</literal>, der entweder eine
           Schnittstellennummer als <type>Int</type> oder einen
           Schnittstellennamen als <literal>String</literal>, wie etwa
           <literal>"eth0"</literal>, angibt. <literal>0</literal> kann
           angegeben werden, um festzulegen, dass die Schnittstelle unter
           Verwendung von Routing-Regeln gewählt werden soll. (Dies kann nur
           für <function>socket_set_option</function> verwendet werden.)
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_LEAVE_GROUP</constant></entry>
          <entry>
           Verläßt eine Multicast-Gruppe.
          </entry>
          <entry>
           <type>array</type>. Siehe <constant>MCAST_JOIN_GROUP</constant> für
           weitere Information. (Dies kann nur für
           <function>socket_set_option</function> verwendet werden.)
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_BLOCK_SOURCE</constant></entry>
          <entry>
           Blockiert Pakete, die von einer bestimmten Quelle an eine bestimmte
           Multicast-Gruppe, der man zuvor beigetreten ist, gesendet wurden.
          </entry>
          <entry>
           <type>array</type> mit denselben Schlüsseln wie
           <constant>MCAST_JOIN_GROUP</constant>, plus einem zusätzlichen
           Schlüssel, <literal>source</literal>, der die IPv4- oder
           IPv6-Adresse der zu blockierenden Quelle als <type>String</type>
           angibt. (Dies kann nur für <function>socket_set_option</function>
           verwendet werden.)
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_UNBLOCK_SOURCE</constant></entry>
          <entry>
           Unblockiert Pakete, die von einer bestimmten Quelle an eine
           bestimmte Multicast-Gruppe, der man zuvor beigetreten ist, gesendet
           wurden; &dh; entsprechende Pakete werden wieder empfangen.
          </entry>
          <entry>
           <type>array</type> mit demselben Format wie
           <constant>MCAST_BLOCK_SOURCE</constant>. (Dies kann nur für
           <function>socket_set_option</function> verwendet werden.)
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_JOIN_SOURCE_GROUP</constant></entry>
          <entry>
           Empfange Pakete, die an eine bestimmte Multicast-Gruppe gesendet
           wurden, deren Quelladresse mit einem bestimmten Wert übereinstimmt.
          </entry>
          <entry>
           <type>array</type> mit demselben Format wie
           <constant>MCAST_BLOCK_SOURCE</constant>. (Dies kann nur für
           <function>socket_set_option</function> verwendet werden.)
          </entry>
         </row>
         <row>
          <entry><constant>MCAST_LEAVE_SOURCE_GROUP</constant></entry>
          <entry>
           Beende den Empfang von Paketen, die an eine bestimmte
           Multicast-Gruppe gesendet wurden, deren Quelladresse mit einem
           bestimmten Wert übereinstimmt.
          </entry>
          <entry>
           <type>array</type> mit demselben Format wie
           <constant>MCAST_BLOCK_SOURCE</constant>. (Dies kann nur für
           <function>socket_set_option</function> verwendet werden.)
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_IF</constant></entry>
          <entry>
           Die ausgehende Schnittstelle für IPv4 Multicast-Pakete.
          </entry>
          <entry>
           Entweder <type>int</type>, um die Schnittstellennummer anzugeben,
           oder ein <type>String</type> mit dem Schnittstellennamen, wie
           <literal>eth0</literal>. Der Wert <type>0</type> kann verwendet
           werden, um festzulegen, dass die Routingtabelle für die
           Schnittstellenauswahl genutzt werden soll. Die Funktion
           <function>socket_get_option</function> gibt einen
           Schnittstellenindex zurück. Es ist zu beachten, dass im Gegensatz
           zur C-API, diese Option KEINE IP-Adresse akzeptiert. Das beseitigt
           den Schnittstellenunterschied zwischen
           <constant>IP_MULTICAST_IF</constant> und
           <constant>IPV6_MULTICAST_IF</constant>.
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_IF</constant></entry>
          <entry>
           Die ausgehende Schnittstelle für IPv6-Multicast-Pakete.
          </entry>
          <entry>
           Identisch zu <constant>IP_MULTICAST_IF</constant>.
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_LOOP</constant></entry>
          <entry>
           Die Multicast-Loopback-Richtlinie für IPv4-Pakete aktiviert oder
           deaktiviert den Loopback von ausgehenden Multicasts, die zuvor
           verbunden worden sein müssen. Sie wirkt sich jedoch unterschiedlich
           aus, je nachdem, ob sie auf Unix oder Windows angewendet wird,
           wobei sie bei Ersterem den Empfangspfad betrifft und bei Letzterem
           den Sendepfad.
          </entry>
          <entry>
           <type>int</type> (entweder <literal>0</literal> oder
           <literal>1</literal>). Für <function>socket_set_option</function>
           wird jeder Wert akzeptiert und gemäß den übelichen PHP-Regeln in
           booleschen Wert konvertiert.
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_LOOP</constant></entry>
          <entry>
           Analog zu <constant>IP_MULTICAST_LOOP</constant>, aber für IPv6.
          </entry>
          <entry>
           <type>int</type>. Siehe <constant>IP_MULTICAST_LOOP</constant>.
          </entry>
         </row>
         <row>
          <entry><constant>IP_MULTICAST_TTL</constant></entry>
          <entry>
           Die Lebensdauer ausgehender IPv4-Multicast-Pakete. Dies sollte ein
           Wert zwischen 0 (verlasse nicht die Schnittstelle) und 255 sein.
           Der Vorgabewert ist 1 (nur das lokale Netzwerk wird erreicht).
          </entry>
          <entry>
           <type>int</type> zwischen 0 und 255.
          </entry>
         </row>
         <row>
          <entry><constant>IPV6_MULTICAST_HOPS</constant></entry>
          <entry>
           Analog zu <constant>IP_MULTICAST_TTL</constant>, aber für
           IPv6- Pakete. Der Wert -1 wird ebenfalls akzeptiert und bedeutet,
           dass die Vorgabewert der Route verwendet werden soll.
          </entry>
          <entry>
           <type>int</type> zwischen -1 und 255.
          </entry>
         </row>
         <row>
          <entry><constant>SO_MARK</constant></entry>
          <entry>
           Bestimmt unter Linux eine Kennung für die Paketfilterung auf dem
           Socket.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_ACCEPTFILTER</constant></entry>
          <entry>
           Fügt einen Accept-Filter auf dem überwachten Socket hinzu
           (FreeBSD/NetBSD). Unter FreeBSD muss vorher ein Kernelmodul für den
           Accept-Filter geladen werden (&zb; accf_http).
          </entry>
          <entry>
           Ein <type>&string;</type> mit dem Namen des Filters (maximale
           Länge: 15).
          </entry>
         </row>
         <row>
          <entry><constant>SO_USER_COOKIE</constant></entry>
          <entry>
           Bestimmt unter FreeBSD eine Kennung für die Paketfilterung auf dem
           Socket.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_RTABLE</constant></entry>
          <entry>
           Bestimmt unter OpenBSD eine Kennung für die Paketfilterung auf dem
           Socket.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_DONTTRUNC</constant></entry>
          <entry>
           Ungelesene Daten aufbewahren.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_WANTMORE</constant></entry>
          <entry>
           Einen Hinweis ausgeben, wenn weitere Daten verfügbar sind.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_DEFER_ACCEPT</constant></entry>
          <entry>
           Benachrichtigt einen überwachenden Socket erst, wenn die Daten
           vollständig sind.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_INCOMING_CPU</constant></entry>
          <entry>
           Ermittlelt/bestimmt die CPU-Zugehörigkeit eines Sockets.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_MEMINFO</constant></entry>
          <entry>
           Ermittelt die gesamte meminfo eines Sockets.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_BPF_EXTENSIONS</constant></entry>
          <entry>
           Ermittelt die vom Kernel unterstützten BPF-Erweiterungen, die an
           einen Socket angehängt werden können.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SO_SETFIB</constant></entry>
          <entry>
           Bestimmt die Route-Tabelle (FIB) eines Sockets (nur FreeBSD).
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>SOL_FILTER</constant></entry>
          <entry>
           Filtert die einem Socket zugeordneten Daten (nur Solaris/Illumos).
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPCNT</constant></entry>
          <entry>
           Bestimmt die maximale Anzahl von Keepalive-Tests, die TCP senden
           soll, bevor die Verbindung abgebrochen wird.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPIDLE</constant></entry>
          <entry>
           Bestimmt die Zeit, die die Verbindung im Leerlauf bleiben soll.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPINTVL</constant></entry>
          <entry>
           Bestimmt die Zeit zwischen den einzelnen Keepalive-Tests.
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_KEEPALIVE</constant></entry>
          <entry>
           Bestimmt die Zeit, die die Verbindung im Leerlauf bleiben soll (nur
           macOS).
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
         <row>
          <entry><constant>TCP_NOTSENT_LOWAT</constant></entry>
          <entry>
           Bestimmt die Höchstzahl der nicht gesendeten Daten in der
           Schreib-Warteschlange des Socket-Streams (nur Linux).
          </entry>
          <entry>
           <type>int</type>
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Gibt den Wert der angegebenen Option zurück. &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>-Beispiel</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
-->