<?xml version="1.0" encoding="iso-8859-1"?>
<reference id="ref.shmop">
  <title>Shared Memory Funktionen (Gemeinsamer Speicher)</title>
  <titleabbrev>shmop</titleabbrev>

  <partintro>
   <para>
    Shmop ist eine Sammlung einfach anzuwendender PHP-Funktionen,
    mit denen man mit PHP UNIX shared-memory-Segmente beschreiben,
    auslesen und lschen kann. Die Funktionen knnen mit Windows nicht
    eingesetzt werden, weil Windows keinen gemeinsamen Speicher
    untersttzt.
    Um shmop zu nutzen, mssen Sie PHP mit der Option --enable-shmop
    in der Konfiguratinszeile kompilieren.
   </para>
   <note>
    <simpara>
     Die Funktionen, die in diesem Kapitel erklrt werden, beginnen
     in PHP 4.0.3 alle mit <function>shm_</function> , aber ab Version
     PHP 4.0.4 und grsser, wurden diese Namen gendert und beginnen
     nun mit <function>shmop_</function>.
    </simpara>
   </note>
   <para>
    <example>
     <title>Shared Memory Operationen - bersicht</title>
     <programlisting role="php">
&lt;?php

// Erstelle einen 100 Byte grossen gemeinsam genutzten Speicherblock
// mit mit der System_ID if 0xff3
$shm_id = shmop_open(0xff3, "c", 0644, 100);
if(!$shm_id) {
        echo "Konnte kein gemeinsames Speichersegment erstellen\n";
}

// Hole die Grsse des gemeinsamen Speicherblocks
$shm_size = shmop_size($shm_id);
echo "SHM Block mit: ".$shm_size. " Bytes wurde erstellt.\n";

// Teststring in den gemeinsamen Speicher schreiben
$shm_bytes_written = shmop_write($shm_id, "mein gemeinsamer Speicher", 0);
if($shm_bytes_written != strlen("mein gemeinsamer Speicher")) {
        echo "Konnte nicht ermitteln, wieviele Bytes geschrieben wurden\n";
}

// Den Teststring wieder auslesen
$my_string = shmop_read($shm_id, 0, $shm_size);
if(!$my_string) {
        echo "Konnte nicht aus dem gemeinsamen Speicher lesen\n";
}
echo "Die Daten im gemeinsamen Speicher waren: ".$my_string."\n";

// Den Speicherblock lschen und den gemeinsamen Speicher schliessen
if(!shmop_delete($shm_id)) {
        echo "Konnte den gemeinsamen Speicherblock nicht zum Lschen markieren.";
}
shmop_close($shm_id);

?&gt;
     </programlisting>
    </example>
   </para>
  </partintro>

  <refentry id="function.shmop_open">
   <refnamediv>
    <refname>shmop_open</refname>
    <refpurpose>Erstellt oder ffnet einen gemeinsamen Speicherblock</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>shmop_open</methodname>
      <methodparam><type>int</type><parameter>key</parameter></methodparam>
      <methodparam><type>string</type><parameter>flags</parameter></methodparam>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
      <methodparam><type>int</type><parameter>size</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>shmop_open</function> Kann einen gemeinsamen Speicherbereich erstellen oder ffnen
    </para>
    <para>
     <function>shmop_open</function> bentigt 4 Parameter: key, die System-ID
     des gemeinsam genutzten Speicherblocks, dieser Parameter kann als
     Dezimal- oder Hexadezimalzahl bergeben werden. Der zweite Parameter
     bezeichnet die Flags, die man benutzen kann:
     <itemizedlist>
      <listitem>
       <simpara>
        "a" zum Zugriff (access) auf einen gemeinsamen Speicherblock (setzt IPC_EXCL)
        Benutzen Sie dieses Flag, wenn Sie einen bestehenden gemeinsamen
        Speicherblock ffnen wollen.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        "c" zum Erstellen (create) eines gemeinsamen Speicherblocks (setzt IPC_CREATE)
        Benutzen Sie dieses Flag, wenn Sie einen gemeinsamen Speicherblock
        erstellen wollen.
       </simpara>
      </listitem>
     </itemizedlist>
     Der dritte Parameter ist der Modus, der die Zugriffsrechte, die Sie
     dem gemeinsamen Speicher zuweisen wollen, angibt. Das sind dieselben
     Zugriffsrechte wie fr Dateien. Zugriffsrechte mssen oktal angegeben
     werden, z.B. 0644. Der letzte Parameter gibt die Grsse des
     gemeinsamen Speichers, den Sie erstellen wollen, in Byte, an.
     <note><simpara>
      Beachten Sie: Der dritte und vierte Parameter muss als 0 angegeben
      werden, wenn Sie ein existierendes gemeinsames Speichersegment
      ffnen wollen. Bei Erfolg liefert die Funktion
      <function>shmop_open</function> eine ID zurck, die Sie zum Zugriff
      auf den erstellten gemeinsamen Speicher benutzen knnen.
     </simpara></note>
    </para>
    <para>
     <example>
      <title>Einen neuen gemeinsamen Speicherblock erstellen</title>
      <programlisting role="php">
&lt;?php
$shm_id = shmop_open(0x0fff, "c", 0644, 100);
?&gt;
      </programlisting>
     </example>
    </para>
    <para>
     In diesem Beispiel wurde ein gemeinsamer Speicherblock mit der
     System-ID 0x0fff erstellt.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.shmop_read">
   <refnamediv>
    <refname>shmop_read</refname>
    <refpurpose>Daten aus dem gemeinsamen Speicherblock auslesen</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>string</type><methodname>shmop_read</methodname>
      <methodparam><type>int</type><parameter>shmid</parameter></methodparam>
      <methodparam><type>int</type><parameter>start</parameter></methodparam>
      <methodparam><type>int</type><parameter>count</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>shmop_read</function> liest einen String aus dem gemeinsamen Speicher.
    </para>
    <para>
     <function>shmop_read</function> braucht 3 Parameter: shmid, die Kennung
     des gemeinsamen Speicherblocks, der mit <function>shmop_open</function>
     erzeugt wurde, start gibt den Offset an, von wo ab gelesen werden soll
     und count gibt die Anzahl der zu lesenden Bytes an.
    </para>
    <para>
     <example>
      <title>Aus dem gemeinsamen Speicher lesen</title>
      <programlisting role="php">
&lt;?php
$shm_data = shmop_read($shm_id, 0, 50);
?&gt;
      </programlisting>
     </example>
    </para>
    <para>
     In diesem Beispiel werden 50 Bytes aus dem gemeinsamen Speicherblock
     in die Variable <literal>$shm_data</literal> eingelesen.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.shmop_write">
   <refnamediv>
    <refname>shmop_write</refname>
     <refpurpose>Schreibt Daten in einen gemeinsamen Speicherblock</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Beschreibung</title>
      <methodsynopsis>
       <type>int</type><methodname>shmop_write</methodname>
       <methodparam><type>int</type><parameter>shmid</parameter></methodparam>
       <methodparam><type>string</type><parameter>data</parameter></methodparam>
       <methodparam><type>int</type><parameter>offset</parameter></methodparam>
      </methodsynopsis>
     <para>
      <function>shmop_write</function> schreibt Daten in einen gemeinsamen
      Speicherbereich.
     </para>
     <para>
      <function>shmop_write</function> braucht 3 Parameter:shmid, die Kennung
      des gemeinsamen Speicherblocks, der mit <function>shmop_open</function>
      erzeugt wurde, data, ein String, der in den gemeinsamen Speicher
      geschrieben werden soll und offset, der angibt, von wo ab in den
      gemeinsamen Speicherblock geschrieben werden soll.
     </para>
     <para>
      <example>
      <title>In den gemeinsamen Speicher schreiben</title>
      <programlisting role="php">
&lt;?php
$shm_bytes_written = shmop_write($shm_id, $my_string, 0);
?&gt;
      </programlisting>
     </example>
    </para>
    <para>
     In diesem Beispiel werden die Daten der Variablen <literal>$my_string</literal>
     in den gemeinsamen Speicherblock geschrieben. Die Variable
     <literal>$shm_bytes_written</literal> enthlt die Anzahl der geschriebenen Bytes.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.size">
  <refnamediv>
   <refname>shmop_size</refname>
   <refpurpose>Liefert die Grsse des gemeinsamen Speicherblocks</refpurpose>
  </refnamediv>
  <refsect1>
   <title>Beschreibung</title>
    <methodsynopsis>
     <type>int</type><methodname>shmop_size</methodname>
     <methodparam><type>int</type><parameter>shmid</parameter></methodparam>
    </methodsynopsis>
    <para>
     <function>shmop_size</function> wird benutzt, um die Grsse eines gemeinsamen
     Speicherblocks in Byte zu ermitteln.
    </para>
    <para>
     <function>shmop_size</function> bentigt shmid, die Kennung
     des gemeinsamen Speicherblocks, der mit <function>shmop_open</function>
     erzeugt wurde. Die Funktion liefert einen Integerwert zurck, welcher
     angibt, wieviele Bytes von dem gemeinsamen Speicher belegt werden.
    </para>
    <para>
     <example>
      <title>Die Grsse des gemeinsamen Speicherblocks ermitteln</title>
      <programlisting role="php">
&lt;?php
$shm_size = shmop_size($shm_id);
?&gt;
      </programlisting>
     </example>
    </para>
    <para>
     In dem Beispiel erhlt die Variable <literal>$shm_size</literal>
     die Grsse des durch <literal>$shm_id</literal> bezeichneten
     gemeinsamen Speicherblocks in Byte.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.shmop_delete">
   <refnamediv>
    <refname>shmop_delete</refname>
    <refpurpose>Einen gemeinsamen Speicherblock lschen</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>shmop_delete</methodname>
      <methodparam><type>int</type><parameter>shmid</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>shmop_delete</function> wird benutzt, um einen gemeinsamen
     Speicherbereich zu lschen.
    </para>
    <para>
     <function>shmop_delete</function> bentigt shmid, die Kennung
     des gemeinsamen Speicherblocks, der mit <function>shmop_open</function>
     erzeugt wurde. Bei Erfolg wird 1 zurckgegeben, bei Scheitern 0.
    </para>
    <para>
     <example>
      <title>einen gemeinsamen Speicherblock lschen</title>
      <programlisting role="php">
&lt;?php
shmop_delete($shm_id);
?&gt;
      </programlisting>
     </example>
    </para>
    <para>
     In diesem Beispiel wird der gemeinsame Speicherblock mit dem
     Bezeichner <literal>$shm_id</literal> gelscht.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.shmop_close">
   <refnamediv>
    <refname>shmop_close</refname>
    <refpurpose>Schliesst einen gemeinsamen Speicherblock</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>shmop_close</methodname>
      <methodparam><type>int</type><parameter>shmid</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>shmop_close</function> wird benutzt, um einen gemeinsamen
     Speicherblock zu schliessen.
    </para>
    <para>
     <function>shmop_close</function> bentigt shmid, die Kennung
     des gemeinsamen Speicherblocks, der mit <function>shmop_open</function>
     erzeugt wurde.
    </para>
    <para>
     <example>
      <title>Einen gemeinsamen Speicherblock schliessen</title>
      <programlisting role="php">
&lt;?php
shmop_close($shm_id);
?&gt;
      </programlisting>
     </example>
    </para>
    <para>
     In diesem Beispiel wird der gemeinsame Speicherblock mit dem Bezeichner
     <literal>$shm_id</literal> geschlossen.
    </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:
-->