using the return value of <CODE>sleep</CODE>, when nonzero, to call
<CODE>sleep</CODE> again.  This will work with a certain amount of accuracy as
long as signals arrive infrequently.  But each signal can cause the
eventual wakeup time to be off by an additional second or so.  Suppose a
few signals happen to arrive in rapid succession by bad luck--there is
no limit on how much this could shorten or lengthen the wait.
<P>
Instead, compute the time at which the program should stop waiting, and
keep trying to wait until that time.  This won't be off by more than a
second.  With just a little more work, you can use <CODE>select</CODE> and
make the waiting period quite accurate.  (Of course, heavy system load
can cause unavoidable additional delays--unless the machine is 
dedicated to one application, there is no way you can avoid this.)
<P>
On some systems, <CODE>sleep</CODE> can do strange things if your program uses
<CODE>SIGALRM</CODE> explicitly.  Even if <CODE>SIGALRM</CODE> signals are being
ignored or blocked when <CODE>sleep</CODE> is called, <CODE>sleep</CODE> might
return prematurely on delivery of a <CODE>SIGALRM</CODE> signal.  If you have
established a handler for <CODE>SIGALRM</CODE> signals and a <CODE>SIGALRM</CODE>
signal is delivered while the process is sleeping, the action taken
might be just to cause <CODE>sleep</CODE> to return instead of invoking your
handler.  And, if <CODE>sleep</CODE> is interrupted by delivery of a signal
whose handler requests an alarm or alters the handling of <CODE>SIGALRM</CODE>,
this handler and <CODE>sleep</CODE> will interfere.
<P>
On the GNU system, it is safe to use <CODE>sleep</CODE> and <CODE>SIGALRM</CODE> in
the same program, because <CODE>sleep</CODE> does not work by means of
<CODE>SIGALRM</CODE>.
<P>
<H2><A NAME="SEC323" HREF="library_toc.html#SEC323" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC323">Resource Usage</A></H2>
<A NAME="IDX1412"></A>
<P>
The function <CODE>getrusage</CODE> and the data type <CODE>struct rusage</CODE>
are used for examining the usage figures of a process.  They are declared
in <TT>`sys/resource.h'</TT>.
<P>
<A NAME="IDX1413"></A>
<U>Function:</U> int <B>getrusage</B> <I>(int <VAR>processes</VAR>, struct rusage *<VAR>rusage</VAR>)</I><P>
This function reports the usage totals for processes specified by
<VAR>processes</VAR>, storing the information in <CODE>*<VAR>rusage</VAR></CODE>.
<P>
In most systems, <VAR>processes</VAR> has only two valid values:
<P>
<DL COMPACT>
<DT><CODE>RUSAGE_SELF</CODE>
<DD>Just the current process.
<P>
<DT><CODE>RUSAGE_CHILDREN</CODE>
<DD>All child processes (direct and indirect) that have terminated already.
</DL>
<P>
In the GNU system, you can also inquire about a particular child process
by specifying its process ID.
<P>
The return value of <CODE>getrusage</CODE> is zero for success, and <CODE>-1</CODE>
for failure.
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The argument <VAR>processes</VAR> is not valid.
</DL>
<P>
One way of getting usage figures for a particular child process is with
the function <CODE>wait4</CODE>, which returns totals for a child when it
terminates.  See section <A HREF="library_23.html#SEC409" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC409">BSD Process Wait Functions</A>.
<P>
<A NAME="IDX1414"></A>
<U>Data Type:</U> <B>struct rusage</B><P>
This data type records a collection usage amounts for various sorts of
resources.  It has the following members, and possibly others:
<P>
<DL COMPACT>
<DT><CODE>struct timeval ru_utime</CODE>
<DD>User time used.
<P>
<DT><CODE>struct timeval ru_stime</CODE>
<DD>System time used.
<P>
<DT><CODE>long ru_majflt</CODE>
<DD>Number of page faults.
<P>
<DT><CODE>long ru_inblock</CODE>
<DD>Number of block input operations.
<P>
<DT><CODE>long ru_oublock</CODE>
<DD>Number of block output operations.
<P>
<DT><CODE>long ru_msgsnd</CODE>
<DD>Number of messages sent.
<P>
<DT><CODE>long ru_msgrcv</CODE>
<DD>Number of messages received.
<P>
<DT><CODE>long ru_nsignals</CODE>
<DD>Number of signals received.
</DL>
<P>
An additional historical function for examining usage figures,
<CODE>vtimes</CODE>, is supported but not documented here.  It is declared in
<TT>`sys/vtimes.h'</TT>.
<P>
<A NAME="IDX1415"></A>
<A NAME="IDX1416"></A>
<A NAME="IDX1417"></A>
<H2><A NAME="SEC324" HREF="library_toc.html#SEC324" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC324">Limiting Resource Usage</A></H2>
<P>
You can specify limits for the resource usage of a process.  When the
process tries to exceed a limit, it may get a signal, or the system call
by which it tried to do so may fail, depending on the limit.  Each
process initially inherits its limit values from its parent, but it can
subsequently change them.
<A NAME="IDX1418"></A>
<P>
The symbols in this section are defined in <TT>`sys/resource.h'</TT>.
<P>
<A NAME="IDX1419"></A>
<U>Function:</U> int <B>getrlimit</B> <I>(int <VAR>resource</VAR>, struct rlimit *<VAR>rlp</VAR>)</I><P>
Read the current value and the maximum value of resource <VAR>resource</VAR>
and store them in <CODE>*<VAR>rlp</VAR></CODE>.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
only possible <CODE>errno</CODE> error condition is <CODE>EFAULT</CODE>.
<P>
<A NAME="IDX1420"></A>
<U>Function:</U> int <B>setrlimit</B> <I>(int <VAR>resource</VAR>, struct rlimit *<VAR>rlp</VAR>)</I><P>
Store the current value and the maximum value of resource <VAR>resource</VAR>
in <CODE>*<VAR>rlp</VAR></CODE>.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error condition is possible:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>You tried to change the maximum permissible limit value,
but you don't have privileges to do so.
</DL>
<P>
<A NAME="IDX1421"></A>
<U>Data Type:</U> <B>struct rlimit</B><P>
This structure is used with <CODE>getrlimit</CODE> to receive limit values,
and with <CODE>setrlimit</CODE> to specify limit values.  It has two fields:
<P>
<DL COMPACT>
<DT><CODE>rlim_cur</CODE>
<DD>The current value of the limit in question.
<P>
<DT><CODE>rlim_max</CODE>
<DD>The maximum permissible value of the limit in question.  You cannot set
the current value of the limit to a larger number than this maximum.
Only the super user can change the maximum permissible value.
</DL>
<P>
In <CODE>getrlimit</CODE>, the structure is an output; it receives the current
values.  In <CODE>setrlimit</CODE>, it specifies the new values.
<P>
Here is a list of resources that you can specify a limit for.
Those that are sizes are measured in bytes.
<P>
<DL COMPACT>
<A NAME="IDX1422"></A>
<DT><CODE>RLIMIT_CPU</CODE>
<DD>The maximum amount of cpu time the process can use.  If it runs for
longer than this, it gets a signal: <CODE>SIGXCPU</CODE>.  The value is
measured in seconds.  See section <A HREF="library_21.html#SEC342" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC342">Nonstandard Signals</A>.
<P>
<A NAME="IDX1423"></A>
<DT><CODE>RLIMIT_FSIZE</CODE>
<DD>The maximum size of file the process can create.  Trying to write a
larger file causes a signal: <CODE>SIGXFSZ</CODE>.  See section <A HREF="library_21.html#SEC342" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC342">Nonstandard Signals</A>.
<P>
<A NAME="IDX1424"></A>
<DT><CODE>RLIMIT_DATA</CODE>
<DD>The maximum size of data memory for the process.  If the process tries
to allocate data memory beyond this amount, the allocation function
fails.
<P>
<A NAME="IDX1425"></A>
<DT><CODE>RLIMIT_STACK</CODE>
<DD>The maximum stack size for the process.  If the process tries to extend
its stack past this size, it gets a <CODE>SIGSEGV</CODE> signal.
See section <A HREF="library_21.html#SEC336" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC336">Program Error Signals</A>.
<P>
<A NAME="IDX1426"></A>
<DT><CODE>RLIMIT_CORE</CODE>
<DD>The maximum size core file that this process can create.  If the process
terminates and a core file is made, and this maximum size is not enough,
the core file is truncated.
<P>
<A NAME="IDX1427"></A>
<DT><CODE>RLIMIT_RSS</CODE>
<DD>The maximum amount of physical memory that this process should get.
This parameter is a guide for the system's scheduler and memory
allocator; the system may give the process more memory when there is a
surplus.
<P>
<A NAME="IDX1428"></A>
<DT><CODE>RLIMIT_OPEN_FILES</CODE>
<DD>The maximum number of files that the process can open.
If it tries to open more files than this, it gets error code
<CODE>EMFILE</CODE>.  See section <A HREF="library_2.html#SEC16" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_2.html#SEC16">Error Codes</A>.
<P>
<A NAME="IDX1429"></A>
<DT><CODE>RLIM_NLIMITS</CODE>
<DD>The number of different resource limits.  Any valid <VAR>resource</VAR>
operand must be less than <CODE>RLIM_NLIMITS</CODE>.
</DL>
<P>
<A NAME="IDX1430"></A>
<U>Constant:</U> <B>int</B> <I>RLIM_INFINITY</I><P>
This constant stands for a value of "infinity" when supplied as
the limit value in <CODE>setrlimit</CODE>.
<P>
Two historical functions for setting resource limits, <CODE>ulimit</CODE> and
<CODE>vlimit</CODE>, are not documented here.  The latter is declared in
<TT>`sys/vlimit.h'</TT> and comes from BSD.
<P>
<A NAME="IDX1431"></A>
<A NAME="IDX1432"></A>
<H2><A NAME="SEC325" HREF="library_toc.html#SEC325" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC325">Process Priority</A></H2>
<A NAME="IDX1433"></A>
<P>
When several processes try to run, their respective priorities determine
what share of the CPU each process gets.  This section describes how you
can read and set the priority of a process.  All these functions and
macros are declared in <TT>`sys/resource.h'</TT>.
<P>
The range of valid priority values depends on the operating system, but
typically it runs from <CODE>-20</CODE> to <CODE>20</CODE>.  A lower priority value
means the process runs more often.  These constants describe the range of
priority values:
<P>
<DL COMPACT>
<A NAME="IDX1434"></A>
<DT><CODE>PRIO_MIN</CODE>
<DD>The smallest valid priority value.
<P>
<A NAME="IDX1435"></A>
<DT><CODE>PRIO_MAX</CODE>
<DD>The smallest valid priority value.
</DL>
<P>
<A NAME="IDX1436"></A>
<U>Function:</U> int <B>getpriority</B> <I>(int <VAR>class</VAR>, int <VAR>id</VAR>)</I><P>
Read the priority of a class of processes; <VAR>class</VAR> and <VAR>id</VAR>
specify which ones (see below).
<P>
The return value is the priority value on success, and <CODE>-1</CODE> on
failure.  The following <CODE>errno</CODE> error condition are possible for
this function:
<P>
<DL COMPACT>
<DT><CODE>ESRCH</CODE>
<DD>The combination of <VAR>class</VAR> and <VAR>id</VAR> does not match any existing
process.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The value of <VAR>class</VAR> is not valid.
</DL>
<P>
When the return value is <CODE>-1</CODE>, it could indicate failure, or it
could be the priority value.  The only way to make certain is to set
<CODE>errno = 0</CODE> before calling <CODE>getpriority</CODE>, then use <CODE>errno
!= 0</CODE> afterward as the criterion for failure.
<P>
<A NAME="IDX1437"></A>
<U>Function:</U> int <B>setpriority</B> <I>(int <VAR>class</VAR>, int <VAR>id</VAR>, int <VAR>priority</VAR>)</I><P>
Read the priority of a class of processes; <VAR>class</VAR> and <VAR>id</VAR>
specify which ones (see below).
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error condition are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>ESRCH</CODE>
<DD>The combination of <VAR>class</VAR> and <VAR>id</VAR> does not match any existing
process.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The value of <VAR>class</VAR> is not valid.
<P>
<DT><CODE>EPERM</CODE>
<DD>You tried to set the priority of some other user's process, and you
don't have privileges for that.
<P>
<DT><CODE>EACCES</CODE>
<DD>You tried to lower the priority of a process, and you don't have
privileges for that.
</DL>
<P>
The arguments <VAR>class</VAR> and <VAR>id</VAR> together specify a set of
processes you are interested in.  These are the possible values for
<VAR>class</VAR>:
<P>
<DL COMPACT>
<A NAME="IDX1438"></A>
<DT><CODE>PRIO_PROCESS</CODE>
<DD>Read or set the priority of one process.  The argument <VAR>id</VAR> is a
process ID.
<P>
<A NAME="IDX1439"></A>
<DT><CODE>PRIO_PGRP</CODE>
<DD>Read or set the priority of one process group.  The argument <VAR>id</VAR> is
a process group ID.
<P>
<A NAME="IDX1440"></A>
<DT><CODE>PRIO_USER</CODE>
<DD>Read or set the priority of one user's processes.  The argument <VAR>id</VAR>
is a user ID.
</DL>
<P>
If the argument <VAR>id</VAR> is 0, it stands for the current process,
current process group, or the current user, according to <VAR>class</VAR>.
<P>
<A NAME="IDX1441"></A>
<U>Function:</U> int <B>nice</B> <I>(int <VAR>increment</VAR>)</I><P>
Increment the priority of the current process by <VAR>increment</VAR>.
The return value is not meaningful.
<P>
Here is an equivalent definition for <CODE>nice</CODE>:
<P>
<PRE>
int
nice (int increment)
{
  int old = getpriority (PRIO_PROCESS, 0);
  setpriority (PRIO_PROCESS, 0, old + increment);
}
</PRE>
<P>
<P>Go to the <A HREF="library_18.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_18.html">previous</A>, <A HREF="library_20.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_20.html">next</A> section.<P>