2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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)
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Modified 13 Jun 02, Michael Kerrisk <mtk.manpages@gmail.com>
|
accept.2, execve.2, futimesat.2, getresuid.2, getrlimit.2, madvise.2, mq_getsetattr.2, msgctl.2, nice.2, open.2, poll.2, setresuid.2, shmctl.2, sigaction.2, times.2, utimensat.2, __setfpucw.3, atoi.3, endian.3, err.3, euidaccess.3, fenv.3, fopencookie.3, fpurge.3, getgrouplist.3, getutmp.3, j0.3, lgamma.3, netlink.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_cleanup_push_defer_np.3, pthread_getattr_np.3, pthread_kill_other_threads_np.3, pthread_setaffinity_np.3, pthread_tryjoin_np.3, pthread_yield.3, random_r.3, readdir.3, rtnetlink.3, scanf.3, setenv.3, significand.3, sigsetops.3, strerror.3, strstr.3, sysv_signal.3, termios.3, timegm.3, unlocked_stdio.3, y0.3, locale.5, bootparam.7, feature_test_macros.7, ip.7, locale.7, pthreads.7, rtld-audit.7, nscd.8: Global fix: s/non-standard/nonstandard/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:37:52 +00:00
|
|
|
.\" Added note on nonstandard behavior when SIGCHLD is ignored.
|
2010-01-16 16:48:00 +00:00
|
|
|
.\" Modified 2004-11-16, mtk, Noted that the nonconformance when
|
2004-11-16 17:08:25 +00:00
|
|
|
.\" SIGCHLD is being ignored is fixed in 2.6.9; other minor changes
|
2004-12-08 09:26:32 +00:00
|
|
|
.\" Modified 2004-12-08, mtk, in 2.6 times() return value changed
|
2005-04-04 15:34:13 +00:00
|
|
|
.\" 2005-04-13, mtk
|
accept.2, execve.2, futimesat.2, getresuid.2, getrlimit.2, madvise.2, mq_getsetattr.2, msgctl.2, nice.2, open.2, poll.2, setresuid.2, shmctl.2, sigaction.2, times.2, utimensat.2, __setfpucw.3, atoi.3, endian.3, err.3, euidaccess.3, fenv.3, fopencookie.3, fpurge.3, getgrouplist.3, getutmp.3, j0.3, lgamma.3, netlink.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_cleanup_push_defer_np.3, pthread_getattr_np.3, pthread_kill_other_threads_np.3, pthread_setaffinity_np.3, pthread_tryjoin_np.3, pthread_yield.3, random_r.3, readdir.3, rtnetlink.3, scanf.3, setenv.3, significand.3, sigsetops.3, strerror.3, strstr.3, sysv_signal.3, termios.3, timegm.3, unlocked_stdio.3, y0.3, locale.5, bootparam.7, feature_test_macros.7, ip.7, locale.7, pthreads.7, rtld-audit.7, nscd.8: Global fix: s/non-standard/nonstandard/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:37:52 +00:00
|
|
|
.\" Added notes on nonstandard behavior: Linux allows 'buf' to
|
execve.2, fallocate.2, futex.2, sched_rr_get_interval.2, select_tut.2, shmget.2, timer_getoverrun.2, times.2, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_cleanup_push_defer_np.3, pthread_getattr_np.3, pthread_self.3, pthread_setaffinity_np.3, pthread_tryjoin_np.3, sem_open.3, stdin.3, rtc.4, tty_ioctl.4, unix.7: Global fix: s/non-portable/nonportable/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:46:09 +00:00
|
|
|
.\" be NULL, but POSIX.1 doesn't specify this and it's nonportable.
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2008-06-24 14:57:45 +00:00
|
|
|
.TH TIMES 2 2008-06-25 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.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 ()
|
2004-11-16 17:08:25 +00:00
|
|
|
stores the current process times in the
|
|
|
|
.I "struct tms"
|
2004-11-03 13:51:07 +00:00
|
|
|
that
|
2007-09-20 16:26:31 +00:00
|
|
|
.I buf
|
2004-11-03 13:51:07 +00:00
|
|
|
points to.
|
|
|
|
The
|
|
|
|
.I struct tms
|
|
|
|
is as defined in
|
|
|
|
.IR <sys/times.h> :
|
|
|
|
.sp
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
|
|
|
struct tms {
|
2007-05-16 02:30:46 +00:00
|
|
|
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 */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
2007-05-16 02:31:26 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.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)
|
2008-06-24 12:42:33 +00:00
|
|
|
are added in at the moment
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR wait (2)
|
|
|
|
or
|
|
|
|
.BR waitpid (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
returns their process ID.
|
|
|
|
In particular, times of grandchildren
|
2004-11-03 13:51:07 +00:00
|
|
|
that the children did not wait for are never seen.
|
|
|
|
.LP
|
|
|
|
All times reported are in clock ticks.
|
|
|
|
.SH "RETURN VALUE"
|
2004-11-16 17:08:25 +00:00
|
|
|
.BR times ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returns the number of clock ticks that have elapsed since
|
2004-12-08 09:26:32 +00:00
|
|
|
an arbitrary point in the past.
|
|
|
|
The return value may overflow the possible range of type
|
2005-07-19 15:36:19 +00:00
|
|
|
.IR clock_t .
|
2007-11-29 18:15:54 +00:00
|
|
|
On error, \fI(clock_t)\ \-1\fP is returned, and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
2007-05-26 12:47:10 +00:00
|
|
|
.\" The only possible error is EFAULT.
|
2007-05-18 16:30:46 +00:00
|
|
|
.SH "CONFORMING TO"
|
|
|
|
SVr4, 4.3BSD, POSIX.1-2001.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
2007-07-10 19:50:57 +00:00
|
|
|
The number of clock ticks per second can be obtained using:
|
2007-12-19 07:19:23 +00:00
|
|
|
.in +4n
|
2007-07-10 19:50:57 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
sysconf(_SC_CLK_TCK);
|
2007-12-19 07:19:23 +00:00
|
|
|
.in
|
2007-07-10 19:50:57 +00:00
|
|
|
.PP
|
|
|
|
In POSIX.1-1996 the symbol \fBCLK_TCK\fP (defined in
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR <time.h> )
|
2007-04-12 22:42:49 +00:00
|
|
|
is mentioned as obsolescent.
|
|
|
|
It is obsolete now.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2004-11-16 16:59:09 +00:00
|
|
|
In Linux kernel versions before 2.6.9,
|
2004-11-16 17:08:25 +00:00
|
|
|
if the disposition of
|
|
|
|
.B SIGCHLD
|
|
|
|
is set to
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SIG_IGN
|
|
|
|
then the times of terminated children
|
|
|
|
are automatically included in the
|
|
|
|
.I tms_cstime
|
|
|
|
and
|
|
|
|
.I tms_cutime
|
2006-08-03 13:57:17 +00:00
|
|
|
fields, although POSIX.1-2001 says that this should only happen
|
2004-11-03 13:51:07 +00:00
|
|
|
if the calling process
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR wait (2)s
|
2004-11-03 13:51:07 +00:00
|
|
|
on its children.
|
2010-01-16 16:48:00 +00:00
|
|
|
This nonconformance is rectified in Linux 2.6.9 and later.
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" See the description of times() in XSH, which says:
|
|
|
|
.\" The times of a terminated child process are included... when wait()
|
2005-04-18 13:35:29 +00:00
|
|
|
.\" or waitpid() returns the process ID of this terminated child.
|
2005-04-04 15:34:13 +00:00
|
|
|
|
|
|
|
On Linux, the
|
|
|
|
.I buf
|
|
|
|
argument can be specified as NULL, with the result that
|
|
|
|
.BR times ()
|
|
|
|
just returns a function result.
|
2007-06-08 09:56:56 +00:00
|
|
|
However, POSIX does not specify this behavior, and most
|
2005-04-04 15:34:13 +00:00
|
|
|
other Unix implementations require a non-NULL value for
|
|
|
|
.IR buf .
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
|
|
|
Note that
|
|
|
|
.BR clock (3)
|
2007-12-18 15:36:00 +00:00
|
|
|
also returns a value of type
|
|
|
|
.IR clock_t ,
|
|
|
|
but this value is measured in units of
|
|
|
|
.BR CLOCKS_PER_SEC ,
|
|
|
|
not the clock ticks used by
|
2007-12-28 08:11:15 +00:00
|
|
|
.BR times ().
|
2007-12-18 15:36:00 +00:00
|
|
|
|
|
|
|
On Linux, the "arbitrary point in the past" from which the return value of
|
|
|
|
.BR 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 \fI(2^32/HZ) \- 300\fP
|
|
|
|
(i.e., about 429 million) seconds 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
|
|
|
|
.IR clock_t ,
|
|
|
|
means that a portable application would be wise to avoid using this value.
|
|
|
|
To measure changes in elapsed time, use
|
|
|
|
.BR gettimeofday (2)
|
|
|
|
instead.
|
|
|
|
.\" .PP
|
|
|
|
.\" On older systems the number of clock ticks per second is given
|
|
|
|
.\" by the variable HZ.
|
2007-05-16 02:45:55 +00:00
|
|
|
.SS "Historical"
|
2004-11-03 13:51:07 +00:00
|
|
|
SVr1-3 returns
|
2004-11-16 17:08:25 +00:00
|
|
|
.I long
|
2004-11-03 13:51:07 +00:00
|
|
|
and the struct members are of type
|
2004-11-16 17:08:25 +00:00
|
|
|
.I time_t
|
2007-12-18 15:37:46 +00:00
|
|
|
although they store clock ticks, not seconds since the Epoch.
|
2007-04-12 22:42:49 +00:00
|
|
|
V7 used
|
2004-11-16 17:08:25 +00:00
|
|
|
.I long
|
2004-11-03 13:51:07 +00:00
|
|
|
for the struct members, because it had no type
|
2004-11-16 17:08:25 +00:00
|
|
|
.I time_t
|
2004-11-03 13:51:07 +00:00
|
|
|
yet.
|
2007-12-18 15:36:00 +00:00
|
|
|
.SH BUGS
|
|
|
|
A limitation of the Linux system call conventions on some architectures
|
2007-12-24 17:31:35 +00:00
|
|
|
(notably i386) means that on Linux 2.6 there is a small time window
|
2007-12-18 15:36:00 +00:00
|
|
|
(41 seconds) soon after boot when
|
2007-12-28 08:11:15 +00:00
|
|
|
.BR times ()
|
2007-12-18 15:36:00 +00:00
|
|
|
can return \-1, falsely indicating that an error occurred.
|
|
|
|
The same problem can occur when the return value wraps passed
|
|
|
|
the maximum value that can be stored in
|
|
|
|
.BR clockid_t .
|
|
|
|
.\" The problem is that a syscall return of -4095 to -1
|
|
|
|
.\" is interpreted by glibc as an error, and the wrapper converts
|
|
|
|
.\" the return value to -1.
|
|
|
|
.\" http://marc.info/?l=linux-kernel&m=119447727031225&w=2
|
|
|
|
.\" "compat_sys_times() bogus until jiffies >= 0"
|
|
|
|
.\" November 2007
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR time (1),
|
|
|
|
.BR getrusage (2),
|
|
|
|
.BR wait (2),
|
|
|
|
.BR clock (3),
|
2006-04-26 07:26:36 +00:00
|
|
|
.BR sysconf (3),
|
|
|
|
.BR time (7)
|