summaryrefslogtreecommitdiffstats
path: root/man/man2/times.2
diff options
context:
space:
mode:
Diffstat (limited to 'man/man2/times.2')
-rw-r--r--man/man2/times.2222
1 files changed, 222 insertions, 0 deletions
diff --git a/man/man2/times.2 b/man/man2/times.2
new file mode 100644
index 0000000..c2b8b09
--- /dev/null
+++ b/man/man2/times.2
@@ -0,0 +1,222 @@
+.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 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 nonstandard behavior when SIGCHLD is ignored.
+.\" Modified 2004-11-16, mtk, Noted that the nonconformance when
+.\" SIGCHLD is being ignored is fixed in Linux 2.6.9; other minor changes
+.\" Modified 2004-12-08, mtk, in Linux 2.6 times() return value changed
+.\" 2005-04-13, mtk
+.\" Added notes on nonstandard behavior: Linux allows 'buf' to
+.\" be NULL, but POSIX.1 doesn't specify this and it's nonportable.
+.\"
+.TH times 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+times \- get process times
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/times.h>
+.P
+.BI "clock_t times(struct tms *" buf );
+.fi
+.SH DESCRIPTION
+.BR times ()
+stores the current process times in the
+.I "struct tms"
+that
+.I buf
+points to.
+The
+.I struct tms
+is as defined in
+.IR <sys/times.h> :
+.P
+.in +4n
+.EX
+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 */
+};
+.EE
+.in
+.P
+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 executing inside the kernel
+while performing tasks on behalf of the calling process.
+.P
+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.
+.P
+Times for terminated children (and their descendants)
+are 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.
+.P
+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.
+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 to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+.I tms
+points outside the process's address space.
+.SH VERSIONS
+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 .
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001,
+SVr4,
+4.3BSD.
+.P
+In POSIX.1-1996 the symbol \fBCLK_TCK\fP (defined in
+.IR <time.h> )
+is mentioned as obsolescent.
+It is obsolete now.
+.P
+Before Linux 2.6.9,
+if the disposition of
+.B SIGCHLD
+is set to
+.BR 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 happen
+only if the calling process
+.BR wait (2)s
+on its children.
+This nonconformance 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.
+.P
+On Linux,
+the \[lq]arbitrary point in the past\[rq]
+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\[ha]32/HZ) \- 300\fP
+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 clock_gettime (2)
+instead.
+.\" .P
+.\" On older systems the number of clock ticks per second is given
+.\" by the variable HZ.
+.P
+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 NOTES
+The number of clock ticks per second can be obtained using:
+.P
+.in +4n
+.EX
+sysconf(_SC_CLK_TCK);
+.EE
+.in
+.P
+Note that
+.BR clock (3)
+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
+.BR times ().
+.SH 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
+.BR 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
+.BR clock_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
+.SH SEE ALSO
+.BR time (1),
+.BR getrusage (2),
+.BR wait (2),
+.BR clock (3),
+.BR sysconf (3),
+.BR time (7)