<?xml version="1.0" encoding="iso-8859-1"?>
 <reference id="ref.sockets">
  <title>Socket Funktionen</title>
  <titleabbrev>Sockets</titleabbrev>

  <partintro>
   &warn.experimental;
   <simpara>
    Die Socket-Erweiterung stellt eine hardwarenahe Schnittstelle
    zu den Datenaustauschfunktionen einer Socket-Verbindung zur
    Verfgung und bietet die Mglichkeit, entweder als Socket-Server
    oder als Client zu agieren.
   </simpara>
   <para>
    Die hier beschriebenen Socket Funktionen sind Teil einer PHP
    Erweiterung, die beim Kompilieren mit der Option<option
    role="configure">--enable-sockets</option> beim Befehl
    <command>configure</command> eingebunden werden mssen.
   </para>
   <para>
    Fr eine allgemeinere clientseitige Socket Schnittstelle siehe
    <function>fsockopen</function> und
    <function>pfsockopen</function>.
   </para>
   <para>
    Wenn man diese Funktionen benutzt, darf man nicht vergessen,
    dass, obwohl viele der Funktionen gleichlautende Namen wie ihre
    Entsprechungen in C haben, sie dennoch oft unterschiedliche
    Deklarationen haben. Bitte lesen Sie die Deklarationen, um
    Verwirrung zu vermeiden.
   </para>
   <para>
    Das heisst, wem Socketprogrammierung fremd ist, der findet eine
    grosse Menge ntzlicher Materialien in den entsprechenden Unix
    manpages und es gibt jede Menge von Tutorials und Informationen ber
    Socketprogrammierung in C im Internet. Vieles davon kann mit leichten
    nderungen fr die Socketprogrammierung mit PHP benutzt werden.
   </para>
   <para>
    <example>
     <title>Socket Beispiel: Einfacher TCP/IP Server</title>
     <para>
      Dieses Beispiel zeigt einen einfachen Echo-Server. Passen Sie
      die Variablen <varname>address</varname> und
      <varname>port</varname> an Ihre Systemumgebung an und fhren
      Sie das Skript aus. Dann knnen Sie sich mit einem Befehl wie:
      <command>telnet 192.168.1.53 10000</command> (bei dem adress
      und port an Ihre Umgebung angepasst ist) mit dem Server
      verbinden. Alles, was Sie eingeben, wird an den Server geschickt
      und von diesem wieder an Sie zurckgegeben. Um die Verbindung
      zu trennen, geben sie 'quit' ein.
     </para>
     <programlisting role="php">
&lt;?php
error_reporting (E_ALL);

/* Warten auf Verbindungen */
set_time_limit (0);

$address = '192.168.1.53';
$port = 10000;

if (($sock = socket (AF_INET, SOCK_STREAM, 0)) &lt; 0) {
    echo "socket() fehlgeschlagen: Grund: " . strerror ($sock) . "\n";
}

if (($ret = bind ($sock, $address, $port)) &lt; 0) {
    echo "bind() fehlgeschlagen: Grund: " . strerror ($ret) . "\n";
}

if (($ret = listen ($sock, 5)) &lt; 0) {
    echo "listen() fehlgeschlagen: Grund: " . strerror ($ret) . "\n";
}

do {
    if (($msgsock = accept_connect($sock)) &lt; 0) {
        echo "accept_connect() fehlgeschlagen: Grund: " . strerror ($msgsock) . "\n";
        break;
    }
    do {
        $buf = '';
        $ret = read ($msgsock, $buf, 2048);
        if ($ret &lt; 0) {
            echo "read() fehlgeschlagen: Grund: " . strerror ($ret) . "\n";
            break 2;
        }
        if ($ret == 0) {
            break 2;
        }
        $buf = trim ($buf);
        if ($buf == 'quit') {
            close ($msgsock);
            break 2;
        }
        $talkback = "PHP: Du sagtest '$buf'.\n";
        write ($msgsock, $talkback, strlen ($talkback));
        echo "$buf\n";
    } while (true);
    close ($msgsock);
} while (true);

close ($sock);
?>
     </programlisting>
    </example>
   </para>
   <para>
    <example>
     <title>Socket Beispiel: Einfacher TCP/IP Client</title>
     <para>
      Dieses Beispiel zeigt einen einfachen HTTP-Client. Er verbindet sich
      mit einer Seite, schickt einen HEAD-Request, gibt die Antwort zurueck
      und beendet das Skript.
     </para>
     <programlisting>
&lt;?php
error_reporting (E_ALL);

echo "&lt;h2>TCP/IP Verbindung&lt;/h2>\n";

/* Die Portnummer des WWW Service holen. */
$service_port = getservbyname ('www', 'tcp');

/* Die IP-Adresse des Zielhosts holen. */
$address = gethostbyname ('www.php.net');

/* Eine TCP/IP Socketverbindung aufbauen. */
$socket = socket (AF_INET, SOCK_STREAM, 0);
if ($socket &lt; 0) {
    echo "socket() fehlgeschlagen: Grund: " . strerror ($socket) . "\n";
} else {
    "socket() ausgefuehrt: " . strerror ($socket) . "\n";
}

echo "Verbindungsversuch mit '$address' on port '$service_port'...";
$result = connect ($socket, $address, $service_port);
if ($result &lt; 0) {
    echo "connect() fehlgeschlagen.\nGrund: ($result) " . strerror($result) . "\n";
} else {
    echo "OK.\n";
}

$in = "HEAD / HTTP/1.0\r\n\r\n";
$out = '';

echo "HTTP HEAD request senden...";
write ($socket, $in, strlen ($in));
echo "OK.\n";

echo "Antwort lesen:\n\n";
while (read ($socket, $out, 2048)) {
    echo $out;
}

echo "Socketverbindung schliessen...";
close ($socket);
echo "OK.\n\n";
?>
      </programlisting>
     </example>
    </para>
  </partintro>

  <refentry id="function.accept-connect">
   <refnamediv>
    <refname>accept_connect</refname>
    <refpurpose>Weist den Socket an, hereinkommende Verbindungen zu bearbeiten</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>accept_connect</methodname>
      <methodparam><type>int</type><parameter>socket</parameter></methodparam>
     </methodsynopsis>
       &warn.experimental.func;
    <para>
     Nachdem der Socket <parameter>socket</parameter>  mit der
     <function>socket</function> erzeugt wurde, mit
     <function>bind</function> mit einem Namen verknuepft wurde
     und mit <function>listen</function> angewiesen wurde, auf
     hereinkommende Verbindungsanforderungen zu horchen, wird der
     Socket mit dieser Funktion angewiesen, hereinkommende
     Verbindungsanforderungen zuzulassen und zu bearbeiten. Wenn ein
     Verbindungsaufbau erfolgreich war, wird ein neuer Socket-Deskriptot
     zurckgegeben, welcher zur Kommunikation benutzt werden kann.
     Wenn es mehrere Verbindungsanforderungen an diesem Socket gibt,
     werden diese in eine Warteschlange gestellt und die erste
     Verbindungsanforderung wird bedient.
     Falls es keine aktuellen Verbindungsanforderungen gibt, blockiert
     die Funktion <function>accept_connect</function> solange, bis eine
     Verbindungsanforderung kommt. Falls <parameter>socket</parameter>
     mit der Funktion <function>socket_set_blocking</function> oder mit
     <function>set_nonblock</function> auf 'nicht blockieren' gesetzt
     wurde, wird ein Fehlercode zurckgegeben.
    </para>
    <para>
     Der Socket-Deskriptor, der von <function>accept_connect</function>
     zurckgegeben wird, soll nicht dazu benutzt werden, um neue
     Verbindungsanforderungen zuzulassen. Der originre wartende Socket
     <parameter>socket</parameter> bleibt geffnet und kann wiederbenutzt
     werden.
    </para>
    <para>
     Gibt einen neuen Socket-Deskriptor zurck oder einen negativen
     Fehlercode, falls ein Fehler auftritt. Dieser Fehlercode kann an
     die Funktion <function>strerror</function> bergeben werden, um
     eine textuelle Beschreibung des Fehlers zu erhalten.
    </para>
    <para>
     Siehe auch:
     <function>bind</function>,
     <function>connect</function>,
     <function>listen</function>,
     <function>socket</function>,
     <function>socket_get_status</function>, und
     <function>strerror</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.bind">
   <refnamediv>
    <refname>bind</refname>
    <refpurpose>Verknpft einen Namen mit einem Socket</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>bind</methodname>
      <methodparam><type>int</type><parameter>socket</parameter></methodparam>
      <methodparam><type>string</type><parameter>address</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>port</parameter></methodparam>
     </methodsynopsis>
       &warn.experimental.func;
    <para>
     <function>bind</function> verknpft den Namen, der in
     <parameter>address</parameter> angegeben ist mit dem Socket, der
     durch <parameter>socket</parameter> bestimmt wird. Dies muss ein
     gltiger Socket-Deskriptor sein, der mit der Funktion
     <function>socket</function> erzeugt wurde.
    </para>
    <para>
     Der Parameter <parameter>address</parameter> ist entweder eine
     IP-Adresse, angegeben in Punktnotation
     (z.B. <literal>127.0.0.1</literal>), falls der Socket zur
     <constant>AF_INET</constant> -Familie gehrt; oder ein Pfadname
     eines Unix-domain socket, falls er zur <constant>AF_UNIX</constant> -
     Familie gehrt.
    </para>
    <para>
     Der Parameter <parameter>port</parameter> wird nur benutzt, wenn
     eine Verbindung zu einem <constant>AF_INET</constant> -Socket
     aufgebaut wird und bestimmt den Port des entfernten Hosts, zu dem
     die Verbindung hergestellt werden soll.
    </para>
    <para>
     Gibt bei Erfolg &null; zurck, ansonsten einen negativen Fehlercode.
     Dieser Fehlercode kann an die Funktion <function>strerror</function>
     bergeben werden, um eine textuelle Beschreibung des Fehlers zu erhalten.
    </para>
    <para>
     Siehe auch:
     <function>accept_connect</function>,
     <function>connect</function>,
     <function>listen</function>,
     <function>socket</function>,
     <function>socket_get_status</function>, und
     <function>strerror</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.close">
   <refnamediv>
    <refname>close</refname>
    <refpurpose>Schliesst einen Datei-Deskriptor</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>bool</type><methodname>close</methodname>
      <methodparam><type>int</type><parameter>socket</parameter></methodparam>
     </methodsynopsis>
      &warn.experimental.func;
    <para>
     <function>close</function> schliesst den Datei- (oder Socket-) Deskriptor,
     der durch <parameter>socket</parameter> gegeben ist.
    </para>
    <para>
     Beachten sie, dass <function>close</function> nicht mit PHP
     Dateideskriptoren, die mit <function>fopen</function>,
     <function>popen</function>, <function>fsockopen</function> oder
     <function>psockopen</function> erzeugt wurden, benutzt werden
     sollte, sondern nur fr Dateideskriptoren, die mit
     <function>socket</function> oder <function>accept_connect</function>
     erzeugt wurden.
    </para>
    <para>
     Gibt bei Erfolg &true; zurck oder, falls ein Fehler auftrat, &false;.
     (z.B. <parameter>socket</parameter> is invalid).
    </para>
    <para>
     Siehe auch: <function>bind</function>, <function>listen</function>,
     <function>socket</function>,
     <function>socket_get_status</function>, und
     <function>strerror</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.connect">
   <refnamediv>
    <refname>connect</refname>
    <refpurpose>Baut eine Verbindung zu einem Socket auf</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>connect</methodname>
      <methodparam><type>int</type><parameter>socket</parameter></methodparam>
      <methodparam><type>string</type><parameter>address</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>port</parameter></methodparam>
     </methodsynopsis>
      &warn.experimental.func;
    <para>
     Baut mit Hilfe eines gltigen Socket-Deskriptors
     <parameter>socket</parameter>, der von der Funktion
     <function>socket</function> zurckgegeben wurde,
     eine Verbindung zu dem Socket auf.
    </para>
    <para>
     Der Parameter <parameter>address</parameter> ist entweder
     eine IP-Adresse in Punktnotation (e.g. <literal>127.0.0.1</literal>),
     falls der Socket zur <constant>AF_INET</constant> -Familie gehrt,
     oder der Pfadname eines Unix-domain socket, falls der Socket zur
     <constant>AF_UNIX</constant> -Familie gehrt.
    </para>
    <para>
     Der Parameter <parameter>port</parameter> wird nur benutzt, falls
     eine Verbindung zu einem <constant>AF_INET</constant> Socket
     aufgebaut wird, und bestimmt den Port des entfernten Hosts, zu
     dem die Verbindung aufgebaut werden soll.
    </para>
    <para>
     Gibt bei Erfolg &null; zurck oder einen negativen Fehlercode, falls
     ein Fehler aufgetreten ist.Dieser Fehlercode kann an die Funktion
     <function>strerror</function> bergeben werden, um eine textuelle
     Beschreibung des Fehlers zu erhalten.
    </para>
    <para>
     Siehe auch:
     <function>bind</function>,
     <function>listen</function>,
     <function>socket</function>,
     <function>socket_get_status</function>, und
     <function>strerror</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.listen">
   <refnamediv>
    <refname>listen</refname>
    <refpurpose>Horcht auf eine Verbindungsanforderung an dem Socket</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>listen</methodname>
      <methodparam><type>int</type><parameter>socket</parameter></methodparam>
      <methodparam><type>int</type><parameter>backlog</parameter></methodparam>
     </methodsynopsis>
      &warn.experimental.func;
    <para>
     Nachdem der Socket <parameter>socket</parameter> mit
     <function>socket</function> erzeugt wurde und mit
     <function>bind</function> mit einem Namen verknpft wurde,
     wird er mit dieser Funktion angewiesen, am Socket
     <parameter>socket</parameter> auf hereinkommende
     Verbindungen zu horchen. <parameter>backlog</parameter> ist
     das Maximum an hereinkommenden Verbindungsanforderungen, die
     zur weiteren Verarbeitung in die Warteschlange gestellt werden
     knnen.
    </para>
    <para>
     <function>listen</function> kann nur mit Sockets vom Typ
     <literal>SOCK_STREAM</literal> oder <literal>SOCK_SEQPACKET</literal>
     verwendet werden.
    </para>
    <para>
     Gibt bei Erfolg &null; zurck oder einen negativen Fehlercode wenn
     die Funktion fehlschlgt. Dieser Fehlercode kann an die Funktion
     <function>strerror</function> bergeben werden, um eine textuelle
     Beschreibung des Fehlers zu erhalten.
    </para>
    <para>
     Siehe auch:
     <function>accept_connect</function>,
     <function>bind</function>,
     <function>connect</function>,
     <function>socket</function>,
     <function>socket_get_status</function>, und
     <function>strerror</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.read">
   <refnamediv>
    <refname>read</refname>
    <refpurpose>Liest vom Socket</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>read</methodname>
      <methodparam><type>int</type><parameter>socket_des</parameter></methodparam>
      <methodparam><type>string</type><parameter>&amp;buffer</parameter></methodparam>
      <methodparam><type>int</type><parameter>length</parameter></methodparam>
     </methodsynopsis>
      &warn.experimental.func;
    <para>
     Die Funktion <function>read</function> liest vom Socket
     <parameter>socket_des</parameter>, der von der Funktion
     <function>accept_connect</function> erzeugt wurde die Anzahl Bytes,
     die in dem Parameter <parameter>length</parameter> bergeben
     wurde in den Puffer <parameter>&amp;buffer</parameter>.
     Um das Lesen zu Beenden, kann man \n, \t oder \0 benutzen.
     Gibt die Anzahl der gelesenen Bytes zurck.
    </para>
    <para>
     Der optionale <parameter>type</parameter> ist eine benannte Konstante:
     <itemizedlist>
      <listitem>
       <simpara>
        PHP_BINARY_READ - benutzt die Systemfunktion
        <function>read</function> (Standard in PHP >= 4.1.0)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        PHP_NORMAL_READ - Beendet das Lesen mit \n or \r. (Standard in
        PHP &lt;= 4.0.6)
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Siehe auch:
     <function>accept_connect</function>,
     <function>bind</function>,
     <function>connect</function>,
     <function>listen</function>,
     <function>strerror</function>,
     <function>socket_get_status</function> und
     <function>write</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.socket">
   <refnamediv>
    <refname>socket</refname>
    <refpurpose>Erzeugt einen Socket (Endpunkt fr die Datenbertragung)</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>socket</methodname>
      <methodparam><type>int</type><parameter>domain</parameter></methodparam>
      <methodparam><type>int</type><parameter>type</parameter></methodparam>
      <methodparam><type>int</type><parameter>protocol</parameter></methodparam>
     </methodsynopsis>
      &warn.experimental.func;
    <para>
     Erzeugt eine Datenendeinrichtung zur Kommunikation (einen Socket)
     und gibt fr diesen Socket einen Deskriptor zurck.
    </para>
    <para>
     Der Parameter <parameter>domain</parameter> bestimmt die Domain.
     Momentan werden <constant>AF_INET</constant> und
     <constant>AF_UNIX</constant> untersttzt.
    </para>
    <para>
     Der Parameter <parameter>type</parameter> whlt den Socket-Typ.
     Das ist entweder <constant>SOCK_STREAM</constant>,
     <constant>SOCK_DGRAM</constant>,
     <constant>SOCK_SEQPACKET</constant>,
     <constant>SOCK_RAW</constant>, <constant>SOCK_RDM</constant>, oder
     <constant>SOCK_PACKET</constant>.
    </para>
    <para>
     <parameter>protocol</parameter> bestimmt das Protokoll.
    </para>
    <para>
     Gibt bei Erfolg einen gltigen Socket-Deskriptor zurck oder einen
     negativen Fehlercode, falls ein Fehler auftritt.Dieser Fehlercode
     kann an die Funktion <function>strerror</function> bergeben werden,
     um eine textuelle Beschreibung des Fehlers zu erhalten.
    </para>
    <para>
     Um mehr Informationen ber den Gebrauch der Funktion
     <function>socket</function> und die Bedeutung der verschiedenen
     Parameter zu erhalten , sei auf die Unix man page socket (2)
     verwiesen.
    </para>
    <para>
     Siehe auch:
     <function>accept_connect</function>,
     <function>bind</function>,
     <function>connect</function>,
     <function>listen</function>,
     <function>strerror</function>, und
     <function>socket_get_status</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.strerror">
   <refnamediv>
    <refname>strerror</refname>
    <refpurpose>Gibt einen String zurck, der einen Socket-Fehler beschreibt</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>string</type><methodname>strerror</methodname>
      <methodparam><type>int</type><parameter>errno</parameter></methodparam>
     </methodsynopsis>
      &warn.experimental.func;
    <para>
     <function>strerror</function> nimmt als Parameter
     <parameter>errno</parameter> den Rckgabewert einer Socket-Funktion
     und gibt seinerseits den entsprechenden Erklrungstext aus. Das macht
     die Fehlersuche ein wenig einfacher. Zum Beispiel, anstatt eine
     Include-Datei des Systems zu durchsuchen, was der Fehlercode -111
     bedeutet, kann man den Code an die Funktion <function>strerror</function>
     bergeben und erhlt Aufschluss ber die internen Ablufe.
    </para>
    <para>
     <example>
      <title><function>strerror</function> Beispiel: </title>
      <programlisting role="php">
&lt;?php
if (($socket = socket (AF_INET, SOCK_STREAM, 0)) &lt; 0) {
   echo "socket() fehlgeschlagen: Grund: " . strerror ($socket) . "\n";
}

if (($ret = bind ($socket, '127.0.0.1', 80)) &lt; 0) {
   echo "bind() fehlgeschlagen: Grund: " . strerror ($ret) . "\n";
}
?>
      </programlisting>
      <para>
       Die erwartete Ausgabe des obigen Beispiels (vorausgesetzt, das Skript
       wird nicht mit root- Benutzerrrechten ausgefhrt) ist:
       <screen>
        bind() fehlgeschlagen: Grund: Permission denied
       </screen>
      </para>
     </example>
    </para>
    <para>
     Siehe auch:
     <function>accept_connect</function>,
     <function>bind</function>,
     <function>connect</function>,
     <function>listen</function>,
     <function>socket</function>, und
     <function>socket_get_status</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.write">
   <refnamediv>
    <refname>write</refname>
    <refpurpose>Schreibt in den Socket</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>write</methodname>
      <methodparam><type>int</type><parameter>socket_des</parameter></methodparam>
      <methodparam><type>string</type><parameter>&amp;buffer</parameter></methodparam>
      <methodparam><type>int</type><parameter>length</parameter></methodparam>
     </methodsynopsis>
      &warn.experimental.func;
    <para>
     Die Funktion <function>write</function> schreibt aus dem
     Puffer <parameter>&amp;buffer</parameter> die Anzahl Bytes, die mit
     <parameter>length</parameter> angegeben wurde, in den Socket mit
     dem Socket Deskriptor <parameter>socket_des</parameter>.
    </para>
    <para>
     Siehe auch:
     <function>accept_connect</function>,
     <function>bind</function>,
     <function>connect</function>,
     <function>listen</function>,
     <function>read</function>,
     <function>strerror</function>, und
     <function>socket_get_status</function>.
    </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:
-->