Manpage of TIMES

TIMES

NAME

SYNOPSIS

DESCRIPTION

times()
stores the current process times in the
struct tmsthat
bufpoints to.
The
struct tmsis as defined in
<sys/times.h>:

struct tms {
clock_t tms_utime; /* user time */
clock_t tms_stime; /* system time */
clock_t tms_cutime; /* user time of children */
clock_t tms_cstime; /* system time of children */
};

The
tms_utimefield contains the CPU time spent executing instructions
of the calling process.
The
tms_stimefield contains the CPU time spent in the system while
executing tasks on behalf of the calling process.
The
tms_cutimefield contains the sum of the
tms_utimeand
tms_cutimevalues for all waited-for terminated children.
The
tms_cstimefield contains the sum of the
tms_stimeand
tms_cstimevalues for all waited-for terminated children.

Times for terminated children (and their descendants)
are added in at the moment
wait(2)
or
waitpid(2)
returns their process ID.
In particular, times of grandchildren
that the children did not wait for are never seen.

All times reported are in clock ticks.

RETURN VALUE

times()
returns the number of clock ticks that have elapsed since
an arbitrary point in the past.
The return value may overflow the possible range of type
clock_t.
On error, (clock_t) -1 is returned, and
errnois set appropriately.

ERRORS

EFAULT

tmspoints outside the process's address space.

CONFORMING TO

POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.

NOTES

The number of clock ticks per second can be obtained using:

sysconf(_SC_CLK_TCK);

In POSIX.1-1996 the symbol CLK_TCK (defined in
<time.h>)
is mentioned as obsolescent.
It is obsolete now.

In Linux kernel versions before 2.6.9,
if the disposition of
SIGCHLDis set to
SIG_IGN,
then the times of terminated children
are automatically included in the
tms_cstimeand
tms_cutimefields, although POSIX.1-2001 says that this should happen
only if the calling process
wait(2)s
on its children.
This nonconformance is rectified in Linux 2.6.9 and later.

On Linux, the
bufargument can be specified as NULL, with the result that
times()
just returns a function result.
However, POSIX does not specify this behavior, and most
other UNIX implementations require a non-NULL value for
buf.

Note that
clock(3)
also returns a value of type
clock_t,
but this value is measured in units of
CLOCKS_PER_SEC,
not the clock ticks used by
times().

On Linux, the "arbitrary point in the past" from which the return value of
times()
is measured has varied across kernel versions.
On Linux 2.4 and earlier, this point is the moment the system was booted.
Since Linux 2.6, this point is (2^32/HZ) - 300seconds before system boot time.
This variability across kernel versions (and across UNIX implementations),
combined with the fact that the returned value may overflow the range of
clock_t,
means that a portable application would be wise to avoid using this value.
To measure changes in elapsed time, use
clock_gettime(2)
instead.

Historical

SVr1-3 returns
longand the struct members are of type
time_talthough they store clock ticks, not seconds since the Epoch.
V7 used
longfor the struct members, because it had no type
time_tyet.

BUGS

A limitation of the Linux system call conventions on some architectures
(notably i386) means that on Linux 2.6 there is a small time window
(41 seconds) soon after boot when
times()
can return -1, falsely indicating that an error occurred.
The same problem can occur when the return value wraps past
the maximum value that can be stored in
clock_t.