man2/times.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   4 .\"
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\"
  25 .\" Modified by Michael Haardt (michael@moria.de)
  26 .\" Modified Sat Jul 24 14:29:17 1993 by Rik Faith (faith@cs.unc.edu)
  27 .\" Modified 961203 and 001211 and 010326 by aeb@cwi.nl
  28 .\" Modified 001213 by Michael Haardt (michael@moria.de)
  29 .\" Modified 13 Jun 02, Michael Kerrisk <mtk-manpages@gmx.net>
  30 .\"     Added note on non-standard behaviour when SIGCHLD is ignored.
  31 .\" Modified 2004-11-16, mtk, Noted that the non-conformance when
  32 .\"     SIGCHLD is being ignored is fixed in 2.6.9; other minor changes
  33 .\" Modified 2004-12-08, mtk, in 2.6 times() return value changed
  34 .\"
  35 .TH TIMES 2 2002-06-14 "Linux" "Linux Programmer's Manual"
  36 .SH NAME
  37 times \- get process times
  38 .SH SYNOPSIS
  39 .B #include <sys/times.h>
  40 .sp
  41 .BI "clock_t times(struct tms *" buf );
  42 .SH DESCRIPTION
  43 .BR times ()
  44 stores the current process times in the
  45 .I "struct tms"
  46 that
  47 .IR buf
  48 points to.
  49 The
  50 .I struct tms
  51 is as defined in
  52 .IR <sys/times.h> :
  53 .sp
  54 .nf
  55 struct tms {
  56 .RS
  57 clock_t tms_utime;  /* user time */
  58 clock_t tms_stime;  /* system time */
  59 clock_t tms_cutime; /* user time of children */
  60 clock_t tms_cstime; /* system time of children */
  61 .RE
  62 };
  63 .fi
  64 .LP
  65 The
  66 .I tms_utime
  67 field contains the CPU time spent executing instructions
  68 of the calling process.
  69 The
  70 .I tms_stime
  71 field contains the CPU time spent in the system while
  72 executing tasks on behalf of the calling process.
  73 The
  74 .I tms_cutime
  75 field contains the sum of the
  76 .I tms_utime
  77 and
  78 .I tms_cutime
  79 values for all waited-for terminated children.
  80 The
  81 .I tms_cstime
  82 field contains the sum of the
  83 .I tms_stime
  84 and
  85 .I tms_cstime
  86 values for all waited-for terminated children.
  87 .LP
  88 Times for terminated children (and their descendants)
  89 is added in at the moment
  90 .BR wait (2)
  91 or
  92 .BR waitpid (2)
  93 returns their process ID. In particular, times of grandchildren
  94 that the children did not wait for are never seen.
  95 .LP
  96 All times reported are in clock ticks.
  97 .SH "RETURN VALUE"
  98 .BR times ()
  99 returns the number of clock ticks that have elapsed since
 100 an arbitrary point in the past.
 101 For Linux 2.4 and earlier this point is the moment the system was booted.
 102 Since Linux 2.6, this point is \fI(2^32/HZ) - 300\fP
 103 (i.e., about 429 million) seconds before system boot time.
 104 The return value may overflow the possible range of type
 105 .I clock_t.
 106 On error, \fI(clock_t) \-1\fP is returned, and
 107 .I errno
 108 is set appropriately.
 109 .SH NOTES
 110 The number of clock ticks per second can be obtained using
 111 .RS
 112 sysconf(_SC_CLK_TCK);
 113 .RE
 114 In POSIX-1996 the symbol CLK_TCK (defined in
 115 .IR <time.h> )
 116 is mentioned as obsolescent. It is obsolete now.
 117 .PP
 118 In Linux kernel versions before 2.6.9,
 119 if the disposition of
 120 .B SIGCHLD
 121 is set to
 122 .B SIG_IGN
 123 then the times of terminated children
 124 are automatically included in the
 125 .I tms_cstime
 126 and
 127 .I tms_cutime
 128 fields, although POSIX 1003.1-2001 says that this should only happen
 129 if the calling process
 130 .BR wait ()s
 131 on its children.
 132 This non-conformance is rectified in Linux 2.6.9 and later.
 133 .\" See the description of times() in XSH, which says:
 134 .\"     The times of a terminated child process are included... when wait()
 135 .\"     or waitpid() returns the process ID of this termianted child.
 136 .LP
 137 Note that
 138 .BR clock (3)
 139 returns values of type
 140 .I clock_t
 141 that are not measured in clock ticks
 142 but in
 143 .BR CLOCKS_PER_SEC .
 144 .SH "CONFORMING TO"
 145 SVr4, SVID, POSIX, X/OPEN, BSD 4.3
 146 .SH "HISTORICAL NOTES"
 147 SVr1-3 returns
 148 .I long
 149 and the struct members are of type
 150 .I time_t
 151 although they store clock ticks, not seconds since the epoch.  V7 used
 152 .I long
 153 for the struct members, because it had no type
 154 .I time_t
 155 yet.
 156 .PP
 157 On older systems the number of clock ticks per second is given
 158 by the variable HZ.
 159 .SH "SEE ALSO"
 160 .BR time (1),
 161 .BR getrusage (2),
 162 .BR wait (2),
 163 .BR clock (3),
 164 .BR sysconf (3)