mirror of https://github.com/mkerrisk/man-pages
184 lines
5.2 KiB
Groff
184 lines
5.2 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" Modified by Michael Haardt (michael@moria.de)
|
|
.\" Modified Sat Jul 24 14:29:17 1993 by Rik Faith (faith@cs.unc.edu)
|
|
.\" Modified 961203 and 001211 and 010326 by aeb@cwi.nl
|
|
.\" Modified 001213 by Michael Haardt (michael@moria.de)
|
|
.\" Modified 13 Jun 02, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Added note on non-standard behavior when SIGCHLD is ignored.
|
|
.\" Modified 2004-11-16, mtk, Noted that the non-conformance when
|
|
.\" SIGCHLD is being ignored is fixed in 2.6.9; other minor changes
|
|
.\" Modified 2004-12-08, mtk, in 2.6 times() return value changed
|
|
.\" 2005-04-13, mtk
|
|
.\" Added notes on non-standard behavior: Linux allows 'buf' to
|
|
.\" be NULL, but POSIX.1 doesn't specify this and it's non-portable.
|
|
.\"
|
|
.TH TIMES 2 2002-06-14 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
times \- get process times
|
|
.SH SYNOPSIS
|
|
.B #include <sys/times.h>
|
|
.sp
|
|
.BI "clock_t times(struct tms *" buf );
|
|
.SH DESCRIPTION
|
|
.BR times ()
|
|
stores the current process times in the
|
|
.I "struct tms"
|
|
that
|
|
.IR buf
|
|
points to.
|
|
The
|
|
.I struct tms
|
|
is as defined in
|
|
.IR <sys/times.h> :
|
|
.sp
|
|
.in +0.5i
|
|
.nf
|
|
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 */
|
|
};
|
|
.fi
|
|
.in
|
|
.LP
|
|
The
|
|
.I tms_utime
|
|
field contains the CPU time spent executing instructions
|
|
of the calling process.
|
|
The
|
|
.I tms_stime
|
|
field contains the CPU time spent in the system while
|
|
executing tasks on behalf of the calling process.
|
|
The
|
|
.I tms_cutime
|
|
field contains the sum of the
|
|
.I tms_utime
|
|
and
|
|
.I tms_cutime
|
|
values for all waited-for terminated children.
|
|
The
|
|
.I tms_cstime
|
|
field contains the sum of the
|
|
.I tms_stime
|
|
and
|
|
.I tms_cstime
|
|
values for all waited-for terminated children.
|
|
.LP
|
|
Times for terminated children (and their descendants)
|
|
is added in at the moment
|
|
.BR wait (2)
|
|
or
|
|
.BR waitpid (2)
|
|
returns their process ID.
|
|
In particular, times of grandchildren
|
|
that the children did not wait for are never seen.
|
|
.LP
|
|
All times reported are in clock ticks.
|
|
.SH "RETURN VALUE"
|
|
.BR times ()
|
|
returns the number of clock ticks that have elapsed since
|
|
an arbitrary point in the past.
|
|
For Linux 2.4 and earlier this point is the moment the system was booted.
|
|
Since Linux 2.6, this point is \fI(2^32/HZ) \- 300\fP
|
|
(i.e., about 429 million) seconds before system boot time.
|
|
The return value may overflow the possible range of type
|
|
.IR clock_t .
|
|
On error, \fI(clock_t) \-1\fP is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.\" The only possible error is EFAULT.
|
|
.SH "CONFORMING TO"
|
|
SVr4, 4.3BSD, POSIX.1-2001.
|
|
.SH NOTES
|
|
The number of clock ticks per second can be obtained using:
|
|
.RS
|
|
|
|
sysconf(_SC_CLK_TCK);
|
|
.RE
|
|
.PP
|
|
In POSIX.1-1996 the symbol \fBCLK_TCK\fP (defined in
|
|
.IR <time.h> )
|
|
is mentioned as obsolescent.
|
|
It is obsolete now.
|
|
.PP
|
|
In Linux kernel versions before 2.6.9,
|
|
if the disposition of
|
|
.B SIGCHLD
|
|
is set to
|
|
.B SIG_IGN
|
|
then the times of terminated children
|
|
are automatically included in the
|
|
.I tms_cstime
|
|
and
|
|
.I tms_cutime
|
|
fields, although POSIX.1-2001 says that this should only happen
|
|
if the calling process
|
|
.BR wait (2)s
|
|
on its children.
|
|
This non-conformance is rectified in Linux 2.6.9 and later.
|
|
.\" See the description of times() in XSH, which says:
|
|
.\" The times of a terminated child process are included... when wait()
|
|
.\" or waitpid() returns the process ID of this terminated child.
|
|
|
|
On Linux, the
|
|
.I buf
|
|
argument can be specified as NULL, with the result that
|
|
.BR times ()
|
|
just returns a function result.
|
|
However, POSIX does not specify this behavior, and most
|
|
other Unix implementations require a non-NULL value for
|
|
.IR buf .
|
|
.LP
|
|
Note that
|
|
.BR clock (3)
|
|
returns values of type
|
|
.I clock_t
|
|
that are not measured in clock ticks
|
|
but in
|
|
.BR CLOCKS_PER_SEC .
|
|
.PP
|
|
On older systems the number of clock ticks per second is given
|
|
by the variable HZ.
|
|
.SS "Historical"
|
|
SVr1-3 returns
|
|
.I long
|
|
and the struct members are of type
|
|
.I time_t
|
|
although they store clock ticks, not seconds since the epoch.
|
|
V7 used
|
|
.I long
|
|
for the struct members, because it had no type
|
|
.I time_t
|
|
yet.
|
|
.SH "SEE ALSO"
|
|
.BR time (1),
|
|
.BR getrusage (2),
|
|
.BR wait (2),
|
|
.BR clock (3),
|
|
.BR sysconf (3),
|
|
.BR time (7)
|