<ppdoc>
<copyright>
Copyright (c) 2001 by Addison Wesley Longman, Inc. This material may
be distributed only subject to the terms and conditions set forth in
the Open Publication License, v1.0 or later (the latest version is
presently available at http://www.opencontent.org/openpub/).
<p/>
Distribution of substantively modified versions of this document is
prohibited without the explicit permission of the copyright holder.
<p/>
Distribution of the work or derivative of the work in any standard
(paper) book form is prohibited unless prior permission is obtained
from the copyright holder.
</copyright>
<class name="Process" type="module" ref="xref-000001">
<p/>
  The <modulename>Process</modulename> module is a collection of methods used to manipulate 
  processes.
<p/>
  <constants>
<tr>
  <td><constant>
       <constname>PRIO_PGRP</constname>
       <constval>1</constval>
       <constdesc>Process Group priority.</constdesc>
     </constant>
<p/>
  <constant>
       <constname>PRIO_PROCESS</constname>
       <constval>0</constval>
       <constdesc>Process priority.</constdesc>
     </constant>
<p/>
  <constant>
       <constname>PRIO_USER</constname>
       <constval>2</constval>
       <constdesc>User priority.</constdesc>
     </constant>
<p/>
  <constant>
       <constname>WNOHANG</constname>
       <constval>1</constval>
       <constdesc>Do not block if no child has exited. Not
    available on all platforms.</constdesc>
     </constant>
<p/>
  <constant>
       <constname>WUNTRACED</constname>
       <constval>2</constval>
       <constdesc>Return stopped children as well. Not
    available on all platforms.</constdesc>
     </constant>
</td>
</tr>
</constants>
<p/>
  <methods type="class">
<p/>
        <method name="egid" ref="egid">
      <callseq>
        Process.egid 
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the effective group id for this process.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.egid
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.egid</tt></td>
  <td>&#187;</td>
  <td><tt>500</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="egid=" ref="egid_eq">
      <callseq>
        Process.egid= <obj>aFixnum</obj>
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
            Sets the effective group id for this process.
<p/>
      </desc>
    </method>
<p/>
        <method name="euid" ref="euid">
      <callseq>
        Process.euid 
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the effective user id for this process.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.euid
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.euid</tt></td>
  <td>&#187;</td>
  <td><tt>501</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="euid=" ref="euid_eq">
      <callseq>
        Process.euid= <obj>aFixnum</obj>
      </callseq>
      <desc>
<p/>
      Sets the effective user id for this process.  
      Not available on all platforms.
<p/>
      </desc>
    </method>
<p/>
        <method name="exit!" ref="exit_oh">
      <callseq>
        Process.exit!( <obj>aFixnum</obj>=-1 )
      </callseq>
      <desc>
<p/>
            Exits the process immediately.      
      No exit handlers are run.
      <obj>aFixnum</obj> is returned to the underlying system as the exit
      status. 
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        Process.exit!(0)
]]></fullcode>
Process.exit!(0)
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="fork" ref="fork">
      <callseq>
        Process.fork <opt><block>{ <blockbody>block</blockbody> }</block>
</opt>
        <returns><obj>aFixnum</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      See <mmm><file>kernel</file><front>Kernel</front><back>fork</back><mref>fork</mref></mmm> on page 416.
<p/>
      </desc>
    </method>
<p/>
        <method name="getpgid" ref="getpgid">
      <callseq>
        Process.getpgid( <obj>anInteger</obj> )
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the process group id for the given process id.
      Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.getpgid(Process.ppid())
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.getpgid(Process.ppid())</tt></td>
  <td>&#187;</td>
  <td><tt>32438</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="getpgrp" ref="getpgrp">
      <callseq>
        Process.getpgrp
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the process group id for this process.
      Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.getpgid(0)
        Process.getpgrp
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.getpgid(0)</tt></td>
  <td>&#187;</td>
  <td><tt>32438</tt></td>
</tr>
<tr>
  <td><tt>Process.getpgrp</tt></td>
  <td>&#187;</td>
  <td><tt>32438</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="getpriority" ref="getpriority">
      <callseq>
        Process.getpriority( <obj>aKind</obj>,
        <obj>anInteger</obj> ) <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Gets the      
      scheduling priority for specified process, process group, or
      user.  <obj>aKind</obj> indicates the kind of entity to find:
      one of <moduleconst><file>process</file><front>Process</front><back>PRIO_PGRP</back><mref>PRIO_PGRP</mref></moduleconst>,
      <moduleconst><file>process</file><front>Process</front><back>PRIO_USER</back><mref>PRIO_USER</mref></moduleconst>, or <moduleconst><file>process</file><front>Process</front><back>PRIO_PROCESS</back><mref>PRIO_PROCESS</mref></moduleconst>.
      <obj>anInteger</obj> is an id indicating the particular process,
      process group, or user (an id of 0 means <em>current</em>).
      Lower priorities are more favorable for
      scheduling.  Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.getpriority(Process::PRIO_USER, 0)
        Process.getpriority(Process::PRIO_PROCESS, 0)
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.getpriority(Process::PRIO_USER,<nbsp/>0)</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>Process.getpriority(Process::PRIO_PROCESS,<nbsp/>0)</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="gid" ref="gid">
      <callseq>
        Process.gid 
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the group id for this process.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.gid
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.gid</tt></td>
  <td>&#187;</td>
  <td><tt>500</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="gid=" ref="gid_eq">
      <callseq>
        Process.gid= <obj>aFixnum</obj>
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
            Sets the group id for this process.
<p/>
      </desc>
    </method>
<p/>
        <method name="kill" ref="kill">
      <callseq>
        Process.kill( <obj>aSignal</obj>, 
        <optn><obj>aPid</obj></optn> ) <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Sends the given signal to the specified process id(s),      
      or to the
      current process if <obj>aPid</obj> is zero.  <obj>aSignal</obj> may be an
      integer signal number or a POSIX signal name (either with or
      without a <tt>SIG</tt> prefix).  If <obj>aSignal</obj> is negative (or
      starts with a ``<tt>-</tt>'' sign), kills process groups instead
      of processes.  Not all signals are available on all platforms.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        trap("SIGHUP") { close_then_exit }
        Process.kill("SIGHUP", 0)
]]></fullcode>
trap("SIGHUP")<nbsp/>{<nbsp/>close_then_exit<nbsp/>}
Process.kill("SIGHUP",<nbsp/>0)
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="pid" ref="pid">
      <callseq>
        Process.pid <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the process id of this process.
      Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.pid
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.pid</tt></td>
  <td>&#187;</td>
  <td><tt>1488</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="ppid" ref="ppid">
      <callseq>
        Process.ppid <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the process id of the parent of this process.
      Always returns 0 on NT.
      Not available on all platforms.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        print "I am ", Process.pid, "\n"
        Process.fork { print "Dad is ", Process.ppid, "\n" }
!-          Process.wait
]]></fullcode>
print<nbsp/>"I<nbsp/>am<nbsp/>",<nbsp/>Process.pid,<nbsp/>"\n"
Process.fork<nbsp/>{<nbsp/>print<nbsp/>"Dad<nbsp/>is<nbsp/>",<nbsp/>Process.ppid,<nbsp/>"\n"<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
I<nbsp/>am<nbsp/>1490
Dad<nbsp/>is<nbsp/>1490
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="setpgid" ref="setpgid">
      <callseq>
        Process.setpgid( <obj>aPid</obj>, <obj>anInteger</obj> )
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
            Sets the process group id of <obj>aPid</obj> (0 indicates this
      process) to <obj>anInteger</obj>.
      Not available on all platforms.
<p/>
      </desc>
    </method>
<p/>
        <method name="setpgrp" ref="setpgrp">
      <callseq>
        Process.setpgrp
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
      Equivalent to <tt>setpgid(0,0)</tt>.
      Not available on all platforms.
<p/>
      </desc>
    </method>
<p/>
        <method name="setpriority" ref="setpriority">
      <callseq>
        Process.setpriority( <obj>kind</obj>,
        <obj>anInteger</obj>, <obj>anIntPriority</obj> )
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
      See <mim><file>process</file><front>Process</front><back>getpriority</back><mref>getpriority</mref></mim>.      
<p/>
<codefragment>
<fullcode><![CDATA[        Process.setpriority(Process::PRIO_USER, 0, 19)
        Process.setpriority(Process::PRIO_PROCESS, 0, 19)
        Process.getpriority(Process::PRIO_USER, 0)
        Process.getpriority(Process::PRIO_PROCESS, 0)
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.setpriority(Process::PRIO_USER,<nbsp/>0,<nbsp/>19)</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>Process.setpriority(Process::PRIO_PROCESS,<nbsp/>0,<nbsp/>19)</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>Process.getpriority(Process::PRIO_USER,<nbsp/>0)</tt></td>
  <td>&#187;</td>
  <td><tt>19</tt></td>
</tr>
<tr>
  <td><tt>Process.getpriority(Process::PRIO_PROCESS,<nbsp/>0)</tt></td>
  <td>&#187;</td>
  <td><tt>19</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="setsid" ref="setsid">
      <callseq>
        Process.setsid
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Establishes this process as a new session and process group      
      leader, with no controlling tty.
      Returns the session id.
      Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.setsid
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.setsid</tt></td>
  <td>&#187;</td>
  <td><tt>1495</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="uid" ref="uid">
      <callseq>
        Process.uid
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the user id of this process.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.uid
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.uid</tt></td>
  <td>&#187;</td>
  <td><tt>501</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="uid=" ref="uid_eq">
      <callseq>
        Process.uid= <obj>anInteger</obj>
        <returns><obj>aNumeric</obj></returns>
      </callseq>
      <desc>
<p/>
      Sets the (integer) user id for this process.
      Not available on all platforms.
<p/>
      </desc>
    </method>
<p/>
        <method name="wait" ref="wait">
      <callseq>
        Process.wait
        <returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Waits for any child process to exit and returns the process id
      of that child.      
      Raises a <exception>SystemError</exception> if there are no child processes.
      Not available on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.fork { exit 1; }
        Process.wait
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.fork<nbsp/>{<nbsp/>exit<nbsp/>1;<nbsp/>}</tt></td>
  <td>&#187;</td>
  <td><tt>1500</tt></td>
</tr>
<tr>
  <td><tt>Process.wait</tt></td>
  <td>&#187;</td>
  <td><tt>1500</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="wait2" ref="wait2">
      <callseq>
        Process.wait2
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Waits for any child process to exit and returns an array
      containing the process id and the exit status
      of that child.
      Raises a <exception>SystemError</exception> if there are no child processes.
<p/>
<codefragment>
<fullcode><![CDATA[        Process.fork { exit 1 }
        Process.wait2
]]></fullcode><rubycode>
<tr>
  <td><tt>Process.fork<nbsp/>{<nbsp/>exit<nbsp/>1<nbsp/>}</tt></td>
  <td>&#187;</td>
  <td><tt>1503</tt></td>
</tr>
<tr>
  <td><tt>Process.wait2</tt></td>
  <td>&#187;</td>
  <td><tt>[1503,<nbsp/>256]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="waitpid" ref="waitpid">
      <callseq>
        Process.waitpid( <obj>aPid</obj>,
        <obj>anInteger</obj>=0 )
        <returns><obj>aPid</obj></returns>
      </callseq>
      <desc>
<p/>
      Waits for the given child process to exit. <obj>anInteger</obj> may be 
      a logical or of the flag value
      <moduleconst><file>process</file><front>Process</front><back>WNOHANG</back><mref>WNOHANG</mref></moduleconst> (do not block if no child available)
      or <moduleconst><file>process</file><front>Process</front><back>WUNTRACED</back><mref>WUNTRACED</mref></moduleconst> (return stopped children that haven't 
      been reported).
      Not all flags are available on all platforms, but a flag value
      of zero will work on all platforms.
<p/>
<codefragment>
<fullcode><![CDATA[        include Process
        pid = fork { sleep 3 }
        Time.now
        waitpid(pid, Process::WNOHANG)
        Time.now
        waitpid(pid, 0)
        Time.now
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>include<nbsp/>Process</tt></td>
</tr>
<tr>
  <td><tt>pid<nbsp/>=<nbsp/>fork<nbsp/>{<nbsp/>sleep<nbsp/>3<nbsp/>}</tt></td>
  <td>&#187;</td>
  <td><tt>1506</tt></td>
</tr>
<tr>
  <td><tt>Time.now</tt></td>
  <td>&#187;</td>
  <td><tt>Sun<nbsp/>Jun<nbsp/>09<nbsp/>00:20:09<nbsp/>CDT<nbsp/>2002</tt></td>
</tr>
<tr>
  <td><tt>waitpid(pid,<nbsp/>Process::WNOHANG)</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>Time.now</tt></td>
  <td>&#187;</td>
  <td><tt>Sun<nbsp/>Jun<nbsp/>09<nbsp/>00:20:09<nbsp/>CDT<nbsp/>2002</tt></td>
</tr>
<tr>
  <td><tt>waitpid(pid,<nbsp/>0)</tt></td>
  <td>&#187;</td>
  <td><tt>1506</tt></td>
</tr>
<tr>
  <td><tt>Time.now</tt></td>
  <td>&#187;</td>
  <td><tt>Sun<nbsp/>Jun<nbsp/>09<nbsp/>00:20:12<nbsp/>CDT<nbsp/>2002</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="waitpid2" ref="waitpid2">
      <callseq>
        Process.waitpid2( <obj>aPid</obj>,
        <obj>anInteger</obj>=0 )
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Waits for the given child process to exit, returning that
      child's process id and exit status. <obj>anInteger</obj> may be 
      a logical or of the flag value
      <moduleconst><file>process</file><front>Process</front><back>WNOHANG</back><mref>WNOHANG</mref></moduleconst> (do not block if no child available)
      or <moduleconst><file>process</file><front>Process</front><back>WUNTRACED</back><mref>WUNTRACED</mref></moduleconst> (return stopped children that haven't 
      been reported).
      Not all flags are available on all platforms, but a flag value
      of zero will work on all platforms.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>
