<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
 <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>
   <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 on a system,
         normally 100
        </entry>
       </row>
       <row>
        <entry>SHMSEG</entry>
        <entry>
         max amount of shared memory segments per process, normally 6
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
   <note>
    <simpara>
     These functions do not work on Windows systems.
    </simpara>
   </note>
  </partintro>

  <refentry id="function.sem-get">
   <refnamediv>
    <refname>sem_get</refname>
    <refpurpose>Get a semaphore id</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>sem_get</methodname>
      <methodparam><type>int</type><parameter>key</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>max_acquire</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>perm</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns: A positive semaphore identifier on success, or &false; on
     error.
    </para>
    <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>
    <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>  
    <para> 
     See also: <function>sem_acquire</function> and
     <function>sem_release</function>.
    </para>
    <note>
     <simpara>
      This function does not work on Windows systems.
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.sem-acquire">
   <refnamediv>
    <refname>sem_acquire</refname>
    <refpurpose>Acquire a semaphore</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>sem_acquire</methodname>
      <methodparam><type>int</type><parameter>sem_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns: &true; on success, &false; on error.
    </para>
    <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>
    <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>
    <para> 
     See also: <function>sem_get</function> and
     <function>sem_release</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sem-release">
   <refnamediv>
    <refname>sem_release</refname>
    <refpurpose>Release a semaphore</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>sem_release</methodname>
      <methodparam><type>int</type><parameter>sem_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns: &true; on success, &false; on error.
    </para>
    <para>
     <function>sem_release</function> releases the semaphore if it
     is currently acquired by the calling process, otherwise
     a warning is generated.
    </para>
    <para>
      After releasing the semaphore, <function>sem_acquire</function>
      may be called to re-acquire it.
    </para>
    <para> 
     See also: <function>sem_get</function> and
     <function>sem_acquire</function>.
    </para>
    <note>
     <simpara>
      This function does not work on Windows systems.
     </simpara>
    </note>    
   </refsect1>
  </refentry>

  <refentry id="function.sem-remove">
   <refnamediv>
    <refname>sem_remove</refname>
    <refpurpose>Remove a semaphore</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>sem_remove</methodname>
      <methodparam><type>int</type><parameter>sem_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns: &true; on success, &false;
     on error.
    </para>
    <para>
     <function>sem_remove</function> removes the semaphore
     <parameter>sem_identifier</parameter> if it
     has been created by <function>sem_get</function>, 
     otherwise generates a warning.
    </para>
    <para>
      After removing the semaphore, it is no more accessible.
    </para>
    <para> 
     See also: <function>sem_get</function>,
     <function>sem_release</function> and
     <function>sem_acquire</function>.
    </para>
    <note>
     <simpara>
      This function does not work on Windows systems. It was added on
      PHP 4.1.0.
     </simpara>
    </note>    
   </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>
     <methodsynopsis>
      <type>int</type><methodname>shm_attach</methodname>
      <methodparam><type>int</type><parameter>key</parameter></methodparam> 
      <methodparam choice="opt"><type>int</type><parameter>memsize</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>perm</parameter></methodparam>
     </methodsynopsis>
    <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 the <link
     linkend="configuration.file">configuration file</link>, otherwise
     10000 bytes) and the optional perm-bits (default: 0666).
    </para>
    <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.
    </para>
    <note>
     <simpara>
      This function does not work on Windows systems.
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.shm-detach">
   <refnamediv>
    <refname>shm_detach</refname>
    <refpurpose>Disconnects from shared memory segment</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>shm_detach</methodname>
      <methodparam><type>int</type><parameter>shm_identifier</parameter></methodparam>
     </methodsynopsis>
    <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.
    </para>
   </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>
     <methodsynopsis>
      <type>int</type><methodname>shm_remove</methodname>
      <methodparam><type>int</type><parameter>shm_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Removes shared memory from Unix systems. All data will be
     destroyed.
    </para>
    <note>
     <simpara>
      This function does not work on Windows systems.
     </simpara>
    </note>
   </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>
     <methodsynopsis>
      <type>int</type><methodname>shm_put_var</methodname>
      <methodparam><type>int</type><parameter>shm_identifier</parameter></methodparam>
      <methodparam><type>int</type><parameter>variable_key</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>variable</parameter></methodparam>
     </methodsynopsis>
    <para>
     Inserts or updates a <parameter>variable</parameter> with a given
     <parameter>variable_key</parameter>. <link
     linkend="language.types">All variable-types</link> are supported.
    </para> 
    <note>
     <simpara>
      This function does not work on Windows systems.
     </simpara>
    </note>
   </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>
     <methodsynopsis>
      <type>mixed</type><methodname>shm_get_var</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>int</type><parameter>variable_key</parameter></methodparam>
     </methodsynopsis>
    <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.
    </para>
    <note>
     <simpara>
      This function does not work on Windows systems.
     </simpara>
    </note>
   </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>
     <methodsynopsis>
      <type>int</type><methodname>shm_remove_var</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>int</type><parameter>variable_key</parameter></methodparam>
     </methodsynopsis>
    <para>
     Removes a variable with a given <parameter>variable_key</parameter>
     and frees the occupied memory.
    </para>
    <note>
     <simpara>
      This function does not work on Windows systems.
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id='function.ftok'>
   <refnamediv>
    <refname>ftok</refname>
    <refpurpose>
     Convert a pathname and a project identifier to a System V IPC key
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ftok</methodname>
      <methodparam><type>string</type><parameter>pathname</parameter></methodparam>
      <methodparam><type>string</type><parameter>proj</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->