socket-create.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: a871ef72edf436c59422dedd538594db2541d5f1 Maintainer: nobody Status: ready -->
<!-- Reviewed: yes Maintainer: samesch -->
<refentry xml:id="function.socket-create" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>socket_create</refname>
  <refpurpose>Erzeugt einen Socket (Endpunkt für die Kommunikation)</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>Socket</type><type>false</type></type><methodname>socket_create</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>
  <para>
   Erzeugt eine <classname>Socket</classname>-Instanz (auch als
   Kommunikations-Endpunkt bezeichnet) und gibt sie zurück. Eine typische
   Netzwerkverbindung besteht aus zwei Sockets, von denen der eine die Rolle
   des Clients und der andere die Rolle des Servers übernimmt.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>domain</parameter></term>
     <listitem>
      <para>
       Der <parameter>domain</parameter>-Parameter legt die Protokollfamilie
       fest, die für die Kommunikation vom Socket benutzt wird.
      </para>
      <table>
       <title>Folgende Adressen/Protokollfamilien sind verfügbar:</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Domain</entry>
          <entry>Beschreibung</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><constant>AF_INET</constant></entry>
          <entry>
           IPv4-basierte Internet-Protokolle. TCP und UDP sind allgemein
           gebräuchliche Protokolle dieser Familie.
          </entry>
         </row>
         <row>
          <entry><constant>AF_INET6</constant></entry>
          <entry>
           IPv6-basierte Internet-Protokolle. TCP und UDP sind allgemein
           gebräuchliche Protokolle dieser Familie.
          </entry>
         </row>
         <row>
          <entry><constant>AF_UNIX</constant></entry>
          <entry>
           Protokollfamilie für die lokale Kommunikation. Hohe Effizienz und
           ein geringer Overhead machen sie zur ersten Wahl für die IPC
           (Inter-Process Communication).
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>type</parameter></term>
     <listitem>
      <para>
       Der Parameter <parameter>type</parameter> bestimmt den
       Kommunikationstyp, den der Socket verwenden soll.
      </para>
      <table>
       <title>Mögliche Socket-Typen</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Typ</entry>
          <entry>Beschreibung</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><constant>SOCK_STREAM</constant></entry>
          <entry>
           Stellt zuverlässige, sequentielle verbindungsorientierte
           Byte-Streams im Vollduplexmodus zur Verfügung. Auch bandexterne
           Mechanismen zur Datenübertragung können unterstützt werden. Das
           TCP-Protokoll beruht auf diesem Socket-Typ.
          </entry>
         </row>
         <row>
          <entry><constant>SOCK_DGRAM</constant></entry>
          <entry>
           Unterstützt Datagramme (verbindunglos, Nachrichten vorgegebener
           Maximallänge, deren Übertragung nicht zuverlässig ist). Das
           UDP-Protokoll beruht auf diesem Socket-Typ.
          </entry>
         </row>
         <row>
          <entry><constant>SOCK_SEQPACKET</constant></entry>
          <entry>
           Stellt einen zuverlässigen, sequentiellen, bidirektionalen,
           verbindungsorientierten Übertragungsweg für Datagramme vorgegebener
           Maximallänge zur Verfügung. Ein Empfänger muss bei jeder
           Leseanforderung das gesamte Datenpaket lesen.
          </entry>
         </row>
         <row>
          <entry><constant>SOCK_RAW</constant></entry>
          <entry>
           Stellt einen Zugang mit einem nicht bestimmten Netzwerkprotokoll
           zur Verfügung. Dieser spezielle Socket-Typ kann dazu benutzt
           werden, um manuell ein Protokoll eines beliebigen Typs zu
           erstellen. Solche Sockets werden üblicherweise benutzt, um
           ICMP-Requests zu senden (wie etwa bei ping).
          </entry>
         </row>
         <row>
          <entry><constant>SOCK_RDM</constant></entry>
          <entry>
           Stellt eine zuverlässige Schicht für Datagramme zur Verfügung, in
           der die Reihenfolge der Datagramme nicht garantiert wird. Dies ist
           in den meisten Betriebssytemen nicht implementiert.
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>protocol</parameter></term>
     <listitem>
      <para>
       Der Parameter <parameter>protocol</parameter> setzt das spezifische
       Protokoll innerhalb der angegebenen <parameter>domain</parameter>, das
       vom zurückgegebenen Socket für die Kommunikation benutzt wird. Der
       passende Wert kann ermittelt werden, indem der Name des Protokolls an
       die Funktion <function>getprotobyname</function> übergeben wird. Wenn
       TCP oder UDP gewünscht werden, können auch die entsprechenden
       Konstanten <constant>SOL_TCP</constant> und
       <constant>SOL_UDP</constant> benutzt werden.
      </para>
      <table>
       <title>Gebräuchliche Protokolle</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Name</entry>
          <entry>Beschreibung</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>icmp</entry>
          <entry>
           Das Internet Control Message Protocol wird hauptsächlich von
           Gateways und Hosts benutzt, um Kommunikationsfehler bei Datagrammen
           zu melden. Das Kommando "ping" (das in den meisten modernen
           Betriebssystemen enthalten ist) ist ein Beispiel für eine Anwendung
           von ICMP.
          </entry>
         </row>
         <row>
          <entry>udp</entry>
          <entry>
           Das User Datagram Protocol ist ein verbindungsloses, unzuverlässiges
           Protokoll, mit dem Datensätze fester Länge versendet werden können.
           Aufgrund dieser geringen Anforderungen braucht UDP nur einen
           minimalen Protokoll-Overhead.
          </entry>
         </row>
         <row>
          <entry>tcp</entry>
          <entry>
           Das Transmission Control Protocol ist ein zuverlässiges,
           verbindungsorientiertes, Stream-orientiertes Protokoll für den
           Vollduplex-Betrieb. Bei TCP ist garantiert, dass alle Datenpakete
           in derselben Reihenfolge empfangen werden, in der sie gesendet
           wurden. Falls während der Übertragung ein Datenpaket verlorengeht,
           wird es von TCP erneut versendet, und zwar solange, bis der
           Empfängerhost den Eingang dieses Paktes zurückmeldet. Aus Gründen
           der Zuverlässigkeit und Leistung ist TCP so implementiert, dass es
           eigenständig die Oktet-Grenzen der darunterliegenden
           Datagramm-Kommunikationschicht bestimmen kann. Aus diesem Grund
           müssen TCP Anwendungen in der Lage sein, auch Teilübertragungen
           empfangen zu können.
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Bei Erfolg gibt <function>socket_create</function> eine
   <classname>Socket</classname>-Instanz zurück, bei einem Fehler wird &false;
   zurückgegeben. Der aktuelle Fehlercode kann mit
   <function>socket_last_error</function> ermittelt und an die Funktion
   <function>socket_strerror</function> übergeben werden, um eine textuelle
   Beschreibing des Fehlers zu erhalten.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
   <para>
    Falls eine ungültige <parameter>domain</parameter> oder ein ungültiger
    <parameter>type</parameter> angegbeben wird, fällt
    <function>socket_create</function> auf seine Standardeinstellungen
    <constant>AF_INET</constant> bzw. <constant>SOCK_STREAM</constant> zurück,
    und gibt zusätzlich eine <constant>E_WARNING</constant>-Meldung aus.
   </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Bei Erfolg gibt diese Funktion nun eine
       <classname>Socket</classname>-Instanz zurück; zuvor wurde eine
       <type>&resource;</type> zurückgegeben.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>socket_accept</function></member>
    <member><function>socket_bind</function></member>
    <member><function>socket_connect</function></member>
    <member><function>socket_listen</function></member>
    <member><function>socket_last_error</function></member>
    <member><function>socket_strerror</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
-->