<?xml version="1.0" encoding="utf-8"?>
 <reference id="ref.posix">
  <title>POSIX functions</title>
  <titleabbrev>POSIX</titleabbrev>

  <partintro>
   <para>
    This module contains an interface to those functions defined in the
    IEEE 1003.1 (POSIX.1) standards document which are not accessible
    through other means. POSIX.1 for example defined the open(), read(),
    write() and close() functions, too, which traditionally have been
    part of PHP 3 for a long time. Some more system specific functions
    have not been available before, though, and this module tries to
    remedy this by providing easy access to these functions.
   </para>
  </partintro>


  <refentry id="function.posix-kill">
   <refnamediv>
    <refname>posix_kill</refname>
    <refpurpose>Send a signal to a process</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>posix_kill</methodname>
      <methodparam><type>int</type><parameter>pid</parameter></methodparam>
      <methodparam><type>int</type><parameter>sig</parameter></methodparam>
     </methodsynopsis>
    <para>
     Send the signal <parameter>sig</parameter> to the process
     with the process identifier <parameter>pid</parameter>.
     Returns &false;, if unable to send the signal, &true; otherwise.</para>
    <para>
     See also the kill(2) manual page of your POSIX system, which
     contains additional information about negative process
     identifiers, the special pid 0, the special pid -1, and the
     signal number 0.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getpid">
   <refnamediv>
    <refname>posix_getpid</refname>
    <refpurpose>Return the current process identifier</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_getpid</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Return the process identifier of the current process.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getppid">
   <refnamediv>
    <refname>posix_getppid</refname>
    <refpurpose>Return the parent process identifier</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_getppid</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Return the process identifier of the parent process of the current
     process.
	</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getuid">
   <refnamediv>
    <refname>posix_getuid</refname>
    <refpurpose>
     Return the real user ID of the current process
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_getuid</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Return the numeric real user ID of the current process. See also
     <function>posix_getpwuid</function> for information on how to
     convert this into a useable username.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-geteuid">
   <refnamediv>
    <refname>posix_geteuid</refname>
    <refpurpose>
     Return the effective user ID of the current process
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_geteuid</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Return the numeric effective user ID of the current process. See
     also <function>posix_getpwuid</function> for information on how
     to convert this into a useable username.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getgid">
   <refnamediv>
    <refname>posix_getgid</refname>
    <refpurpose>
     Return the real group ID of the current process
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_getgid</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Return the numeric real group ID of the current process. See also
     <function>posix_getgrgid</function> for information on how to
     convert this into a useable group name.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getegid">
   <refnamediv>
    <refname>posix_getegid</refname>
    <refpurpose>
     Return the effective group ID of the current process
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_getegid</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Return the numeric effective group ID of the current process. See
     also <function>posix_getgrgid</function> for information on how
     to convert this into a useable group name.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-setuid">
   <refnamediv>
    <refname>posix_setuid</refname> 
    <refpurpose>
     Set the effective UID of the current process
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>posix_setuid</methodname>
      <methodparam><type>int</type><parameter>uid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Set the real user ID of the current process. This is a privileged
     function and you need appropriate privileges (usually root) on
     your system to be able to perform this function.</para>
    <para>
     Returns &true; on success, &false; otherwise. See also
     <function>posix_setgid</function>.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-setgid">
   <refnamediv>
    <refname>posix_setgid</refname> 
    <refpurpose>
     Set the effective GID of the current process
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>posix_setgid</methodname>
      <methodparam><type>int</type><parameter>gid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Set the real group ID of the current process. This is a
     privileged function and you need appropriate privileges (usually
     root) on your system to be able to perform this function. The
     appropriate order of function calls is
     <function>posix_setgid</function> first,
     <function>posix_setuid</function> last.</para>
    <para>
     Returns &true; on success, &false; otherwise.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getgroups">
   <refnamediv>
    <refname>posix_getgroups</refname>
    <refpurpose>
     Return the group set of the current process
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>posix_getgroups</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Returns an array of integers containing the numeric group ids of
     the group set of the current process. See also
     <function>posix_getgrgid</function> for information on how to
     convert this into useable group names.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getlogin">
   <refnamediv>
    <refname>posix_getlogin</refname>
    <refpurpose>Return login name</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>posix_getlogin</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Returns the login name of the user owning the current process.
     See <function>posix_getpwnam</function> for information how to
     get more information about this user.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getpgrp">
   <refnamediv>
    <refname>posix_getpgrp</refname>
    <refpurpose>
     Return the current process group identifier
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_getpgrp</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Return the process group identifier of the current process. See
     POSIX.1 and the getpgrp(2) manual page on your POSIX system for
     more information on process groups.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-setsid">
   <refnamediv>
    <refname>posix_setsid</refname>
    <refpurpose>Make the current process a session leader</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_setsid</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Make the current process a session leader. See POSIX.1 and
     the setsid(2) manual page on your POSIX system for more
     informations on process groups and job control. Returns 
     the session id.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-setpgid">
   <refnamediv>
    <refname>posix_setpgid</refname>
    <refpurpose>set process group id for job control</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_setpgid</methodname>
      <methodparam><type>int</type><parameter>pid</parameter></methodparam>
      <methodparam><type>int</type><parameter>pgid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Let the process <parameter>pid</parameter> join the process
     group <parameter>pgid</parameter>. See POSIX.1 and
     the setsid(2) manual page on your POSIX system for more
     informations on process groups and job control. Returns
     &true; on success, &false; otherwise.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getpgid">
   <refnamediv>
    <refname>posix_getpgid</refname>
    <refpurpose>Get process group id for job control</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_getpgid</methodname>
      <methodparam><type>int</type><parameter>pid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the process group identifier of the process
     <parameter>pid</parameter>.</para>
    <para>
     This is not a POSIX function, but is common on BSD and System V
     systems. If your system does not support this function at system
     level, this PHP function will always return &false;.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getsid">
   <refnamediv>
    <refname>posix_getsid</refname>
    <refpurpose>Get the current sid of the process</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>posix_getsid</methodname>
      <methodparam><type>int</type><parameter>pid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Return the sid of the process <parameter>pid</parameter>.
     If <parameter>pid</parameter> is 0, the sid of the
     current process is returned.</para>
    <para>
     This is not a POSIX function, but is common on System V
     systems. If your system does not support this function at system
     level, this PHP function will always return &false;.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-uname">
   <refnamediv>
    <refname>posix_uname</refname>
    <refpurpose>Get system name</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>posix_uname</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Returns a hash of strings with information about the
     system. The indices of the hash are
     <itemizedlist>
      <listitem><simpara>
        sysname - operating system name (e.g. Linux)
       </simpara></listitem>
      <listitem><simpara>
        nodename - system name (e.g. valiant)
       </simpara></listitem>
      <listitem><simpara>
        release - operating system release (e.g. 2.2.10)
       </simpara></listitem>
      <listitem><simpara>
        version - operating system version (e.g. #4 Tue Jul 20
        17:01:36 MEST 1999)
       </simpara></listitem>
      <listitem><simpara>
        machine - system architecture (e.g. i586)
       </simpara></listitem>
      <listitem><simpara>
        domainname - DNS domainname (e.g. php.net)
       </simpara></listitem>
     </itemizedlist>
    </para>
    <para>
     domainname is a GNU extension and not part of POSIX.1, so this
     field is only available on GNU systems or when using the GNU libc.
    </para>
    <para>
     Posix requires that you must not make any assumptions about the
     format of the values, e.g. you cannot rely on three digit version
     numbers or anything else returned by this function.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-times">
   <refnamediv>
    <refname>posix_times</refname>
    <refpurpose>Get process times</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>posix_times</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Returns a hash of strings with information about the
     current process CPU usage. The indices of the hash are
     <itemizedlist>
      <listitem><simpara>
        ticks - the number of clock ticks that have elapsed since
        reboot.
       </simpara></listitem>
      <listitem><simpara>
        utime - user time used by the current process.
       </simpara></listitem>
      <listitem><simpara>
        stime - system time used by the current process.
       </simpara></listitem>
      <listitem><simpara>
        cutime - user time used by current process and children.
       </simpara></listitem>
      <listitem><simpara>
        cstime - system time used by current process and children.
       </simpara></listitem>
     </itemizedlist></para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-ctermid">
   <refnamediv>
    <refname>posix_ctermid</refname>
    <refpurpose>Get path name of controlling terminal</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>posix_ctermid</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Needs to be written.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-ttyname">
   <refnamediv>
    <refname>posix_ttyname</refname>
    <refpurpose>Determine terminal device name</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>posix_ttyname</methodname>
      <methodparam><type>int</type><parameter>fd</parameter></methodparam>
     </methodsynopsis>
    <para>
     Needs to be written.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-isatty">
   <refnamediv>
    <refname>posix_isatty</refname>
    <refpurpose>
     Determine if a file descriptor is an interactive terminal
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>posix_isatty</methodname>
      <methodparam><type>int</type><parameter>fd</parameter></methodparam>
     </methodsynopsis>
    <para>
     Needs to be written.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getcwd">
   <refnamediv>
    <refname>posix_getcwd</refname>
    <refpurpose>Pathname of current directory</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>posix_getcwd</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Needs to be written ASAP.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-mkfifo">
   <refnamediv>
    <refname>posix_mkfifo</refname>
    <refpurpose>
     Create a fifo special file (a named pipe)
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>posix_getcwd</methodname>
      <methodparam><type>string</type><parameter>pathname</parameter></methodparam>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Needs to be written ASAP..</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getgrnam">
   <refnamediv>
    <refname>posix_getgrnam</refname>
    <refpurpose>Return info about a group by name</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>posix_getgrnam</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
     </methodsynopsis>
    <para>
     Needs to be written.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getgrgid">
   <refnamediv>
    <refname>posix_getgrgid</refname>
    <refpurpose>Return info about a group by group id</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>posix_getgrgid</methodname>
      <methodparam><type>int</type><parameter>gid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Needs to be written.</para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getpwnam">
   <refnamediv>
    <refname>posix_getpwnam</refname>
    <refpurpose>Return info about a user by username</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>posix_getpwnam</methodname>
      <methodparam><type>string</type><parameter>username</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns an associative array containing information about a
     user referenced by an alphanumeric username, passed in the
     <parameter>username</parameter> parameter.
    </para>
    <para>
     The array elements returned are:
     <table>
      <title>The user information array</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Element</entry>
         <entry>Description</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>name</entry>
         <entry>
          The name element contains the username of the user. This is
          a short, usually less than 16 character "handle" of the user,
          not her real, full name. This should be the same as the
          <parameter>username</parameter> parameter used when calling the
          function, and hence redundant.
         </entry>
        </row>
        <row>
         <entry>passwd</entry>
         <entry>
          The passwd element contains the user's password in an encrypted
          format. Often, for example on a system employing "shadow"
          passwords, an asterisk is returned instead.
         </entry>
        </row>
        <row>
         <entry>uid</entry>
         <entry>
          User ID of the user in numeric form.
         </entry>
        </row>
        <row>
         <entry>gid</entry>
         <entry>
          The group ID of the user. Use the function
          <function>posix_getgrgid</function> to resolve the
          group name and a list of its members.
         </entry>
        </row>
        <row>
         <entry>gecos</entry>
         <entry>
          GECOS is an obsolete term that refers to the finger information
          field on a Honeywell batch processing system. The field, however,
          lives on, and its contents have been formalized by POSIX. The
          field contains a comma separated list containing the user's full
          name, office phone, office number, and home phone number. On most
          systems, only the user's full name is available.
         </entry>
        </row>
        <row>
         <entry>dir</entry>
         <entry>
          This element contains the absolute path to the
          home directory of the user.
         </entry>
        </row>
        <row>
         <entry>shell</entry>
         <entry>
          The shell element contains the absolute path to the executable of
          the user's default shell.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>    
   </refsect1>
  </refentry>
  
  <refentry id="function.posix-getpwuid">
   <refnamediv>
    <refname>posix_getpwuid</refname>
    <refpurpose>Return info about a user by user id</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>posix_getpwuid</methodname>
      <methodparam><type>int</type><parameter>uid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns an associative array containing information about a
     user referenced by a numeric user ID, passed in the
     <parameter>uid</parameter> parameter.
    </para>
    <para>
     The array elements returned are:
     <table>
      <title>The user information array</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Element</entry>
         <entry>Description</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>name</entry>
         <entry>
          The name element contains the username of the user. This is
          a short, usually less than 16 character "handle" of the user,
          not her real, full name. 
         </entry>
        </row>
        <row>
         <entry>passwd</entry>
         <entry>
          The passwd element contains the user's password in an encrypted
          format. Often, for example on a system employing "shadow"
          passwords, an asterisk is returned instead.
         </entry>
        </row>
        <row>
         <entry>uid</entry>
         <entry>
          User ID, should be the same as the <parameter>uid</parameter>
          parameter used when calling the function, and hence redundant.
         </entry>
        </row>
        <row>
         <entry>gid</entry>
         <entry>
          The group ID of the user. Use the function
          <function>posix_getgrgid</function> to resolve the
          group name and a list of its members.
         </entry>
        </row>
        <row>
         <entry>gecos</entry>
         <entry>
          GECOS is an obsolete term that refers to the finger information
          field on a Honeywell batch processing system. The field, however,
          lives on, and its contents have been formalized by POSIX. The
          field contains a comma separated list containing the user's full
          name, office phone, office number, and home phone number. On most
          systems, only the user's full name is available.
         </entry>
        </row>
        <row>
         <entry>dir</entry>
         <entry>
          This element contains the absolute path to the
          home directory of the user.
         </entry>
        </row>
        <row>
         <entry>shell</entry>
         <entry>
          The shell element contains the absolute path to the executable of
          the user's default shell.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.posix-getrlimit">
   <refnamediv>
    <refname>posix_getrlimit</refname>
    <refpurpose>Return info about system ressource limits</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>posix_getrlimit</methodname>
      <methodparam><type>void</type><parameter/></methodparam>
     </methodsynopsis>
    <para>
     Needs to be written ASAP.</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:
-->