<reference id="ref.sem">
  <title>Semaphore and shared memory functions</title>
  <titleabbrev>Semaphore</titleabbrev>
  <partintro>
  <para>
   This module provides semaphore functions using System V semaphores.
   Semaphores may be used to provide exclusive access to resources
   on the current machine, or to limit the number of processes that
   may simultaneously use a resource.
  <para>
   This module provides also shared memory functions using System V
   shared memory. Shared memory may be used to provide access to
   global variables. Different httpd-daemons and even other programs
   (such as Perl, C, ...) are able to access this data to provide a
   global data-exchange. Remember, that shared memory is NOT safe
   against simultaneous access. Use semaphores for synchronization.

    <table>
     <title>Limits of shared memory by the Unix OS</title>
     <tgroup cols="2">
      <tbody>
       <row>
	<entry>SHMMAX</entry> 
	<entry>max size of shared memory, normally 131072
	bytes</entry>
       </row>
       <row>
	<entry>SHMMIN</entry>
	<entry>minimum size of shared memory, normally 1 byte</entry>
       </row>
       <row>
	<entry>SHMMNI</entry> 
	<entry>max amount of shared memory segments, normally
	100</entry>
       </row>
       <row>
	<entry>SHMSEG</entry>
	<entry>max amount of shared memory per process, normally
	6</entry>
       </row>
      </tbody>
     </tgroup>
    </table>

  </partintro>

  <refentry id="function.sem-get">
   <refnamediv>
    <refname>sem_get</refname>
    <refpurpose>get a semaphore id</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>sem_get</function></funcdef>
     <paramdef>int <parameter>key</parameter></paramdef>
     <paramdef>int <parameter><optional>max_acquire</optional>
      </parameter></paramdef>
     <paramdef>int <parameter><optional>perm</optional>
      </parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns: A positive semaphore identifier on success, or false on
     error.
    <para>
     <function>sem_get</function> returns an id that can be used to
     access the System V semaphore with the given key.  The semaphore
     is created if necessary using the permission bits specified in
     perm (defaults to 0666).  The number of processes that can
     acquire the semaphore simultaneously is set to max_acquire
     (defaults to 1).  Actually this value is set only if the process
     finds it is the only process currently attached to the semaphore.
    <para>
     A second call to <function>sem_get</function> for the same key
     will return a different semaphore identifier, but both
     identifiers access the same underlying semaphore.  
    <para> 
     See also: <function>sem_acquire</function> and
     <function>sem_release</function>.
   </refsect1>
  </refentry>

  <refentry id="function.sem-acquire">
   <refnamediv>
    <refname>sem_acquire</refname>
    <refpurpose>acquire a semaphore</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>sem_acquire</function></funcdef>
     <paramdef>int <parameter>sem_identifier</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns: true on success, false on error
    <para>
     <function>sem_acquire</function> blocks (if necessary) until the
     semaphore can be acquired.  A process attempting to acquire a
     semaphore which it has already acquired will block forever
     if acquiring the semaphore would cause its max_acquire value to
     be exceeded.
    <para>
     After processing a request, any semaphores acquired by the
     process but not explicitly released will be released automatically
     and a warning will be generated.
    <para> 
     See also: <function>sem_get</function> and
               <function>sem_release</function>.
   </refsect1>
  </refentry>

  <refentry id="function.sem-release">
   <refnamediv>
    <refname>sem_release</refname>
    <refpurpose>release a semaphore</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>sem_release</function></funcdef>
     <paramdef>int <parameter>sem_identifier</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns: true on success, false on error
    <para>
     <function>sem_release</function> releases the semaphore if it
     is currently acquired by the calling process, otherwise
     a warning is generated.
    <para>
      After releasing the semaphore, <function>sem_acquire</function>
      may be called to re-acquire it.
    <para> 
     See also: <function>sem_get</function> and
               <function>sem_acquire</function>.
   </refsect1>
  </refentry>

  <refentry id="function.shm-attach">
   <refnamediv>
    <refname>shm_attach</refname>
    <refpurpose>Creates or open a shared memory segment</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>shm_attach</function></funcdef>
     <paramdef>int <parameter>key</parameter></paramdef> 
     <paramdef>int
     <parameter><optional>memsize</optional></parameter></paramdef>
     <paramdef>int
     <parameter><optional>perm</optional></parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>shm_attach</function> returns an id that that can be
     used to access the System V shared memory with the given key, the
     first call creates the shared memory segment with mem_size
     (default: sysvshm.init_mem in php3.ini, otherwise 10000 bytes)
     and the optional perm-bits (default: 666).
    <para>
     A second call to <function>shm_attach</function> for the same
     <parameter>key</parameter> will return a different shared memory
     identifier, but both identifiers access the same underlying
     shared memory. <parameter>memsize</parameter> and
     <parameter>perm</parameter> will be ignored.
   </refsect1>
  </refentry>

  <refentry id="function.shm-detach">
   <refnamediv>
    <refname>shm_detach</refname>
    <refpurpose>Disconnects from shared memory segment</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>shm_detach</function></funcdef>
     <paramdef>int <parameter>shm_identifier</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>shm_detach</function> disconnects from the shared
     memory given by the <parameter>shm_identifier</parameter> created
     by <function>shm_attach</function>. Remember, that shared memory
     still exist in the Unix system and the data is still present.
   </refsect1>
  </refentry>

  <refentry id="function.shm-remove">
   <refnamediv>
    <refname>shm_remove</refname> 
    <refpurpose>Removes shared memory from Unix systems</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>shm_remove</function></funcdef>
     <paramdef>int <parameter>shm_identifier</parameter></paramdef>
    </funcsynopsis>
    <para>
     Removes shared memory from Unix systems. All data will be
     destroyed.
   </refsect1>
  </refentry>

  <refentry id="function.shm-put-var">
   <refnamediv>
    <refname>shm_put_var</refname> 
    <refpurpose>Inserts or updates a variable in shared
     memory</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>shm_put_var</function></funcdef>
     <paramdef>int <parameter>shm_identifier</parameter></paramdef>
     <paramdef>int <parameter>variable_key</parameter></paramdef>
     <paramdef>mixed <parameter>variable</parameter></paramdef>
    </funcsynopsis>
    <para>
     Inserts or updates a <parameter>variable</parameter> with a given
     <parameter>variable_key</parameter>. All variable-types (double,
     int, string, array) are supported. 
   </refsect1>
  </refentry>

  <refentry id="function.shm-get-var">
   <refnamediv>
    <refname>shm_get_var</refname> 
    <refpurpose>Returns a variable from shared memory
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>mixed <function>shm_get_var</function></funcdef>
     <paramdef>int <parameter>id</parameter></paramdef>
     <paramdef>int <parameter>variable_key</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>shm_get_var</function> returns the variable with a given
     <parameter>variable_key</parameter>. The variable is still present
     in the shared memory.
   </refsect1>
  </refentry>

  <refentry id="function.shm-remove-var">
   <refnamediv>
    <refname>shm_remove_var</refname> 
    <refpurpose>Removes a variable from shared memory
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>shm_remove_var</function></funcdef>
     <paramdef>int <parameter>id</parameter></paramdef>
     <paramdef>int <parameter>variable_key</parameter></paramdef>
    </funcsynopsis>
    <para>
     Removes a variable with a given <parameter>variable_key</parameter>
     and frees the occupied memory.
   </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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->