Debian Codegraph @

upstream/debian-unstable/man2/times.2

raw
1 .\" Copyright 1992, Drew Eckhardt <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH times 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 times \- get process times
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/times.h>
15 .P
16 .BI "clock_t times(struct tms *" buf );
17 .fi
18 .SH DESCRIPTION
19 .BR times ()
20 stores the current process times in the
21 .I "struct tms"
22 that
23 .I buf
24 points to.
25 The
26 .I struct tms
27 is as defined in
28 .IR <sys/times.h> :
29 .P
30 .in +4n
31 .EX
32 struct tms {
33 clock_t tms_utime; /* user time */
34 clock_t tms_stime; /* system time */
35 clock_t tms_cutime; /* user time of children */
36 clock_t tms_cstime; /* system time of children */
37 };
38 .EE
39 .in
40 .P
41 The
42 .I tms_utime
43 field contains the CPU time spent executing instructions
44 of the calling process.
45 The
46 .I tms_stime
47 field contains the CPU time spent executing inside the kernel
48 while performing tasks on behalf of the calling process.
49 .P
50 The
51 .I tms_cutime
52 field contains the sum of the
53 .I tms_utime
54 and
55 .I tms_cutime
56 values for all waited-for terminated children.
57 The
58 .I tms_cstime
59 field contains the sum of the
60 .I tms_stime
61 and
62 .I tms_cstime
63 values for all waited-for terminated children.
64 .P
65 Times for terminated children (and their descendants)
66 are added in at the moment
67 .BR wait (2)
68 or
69 .BR waitpid (2)
70 returns their process ID.
71 In particular,
72 times of grandchildren
73 that the children did not wait for are never seen.
74 .P
75 All times reported are in clock ticks.
76 .SH RETURN VALUE
77 .BR times ()
78 returns the number of clock ticks that have elapsed since
79 an arbitrary point in the past.
80 The return value may overflow the possible range of type
81 .IR clock_t .
82 On error,
83 .I (clock_t)\ \-1
84 is returned,
85 and
86 .I errno
87 is set to indicate the error.
88 .SH ERRORS
89 .TP
90 .B EFAULT
91 .I tms
92 points outside the process's address space.
93 .SH VERSIONS
94 On Linux,
95 the
96 .I buf
97 argument can be specified as NULL,
98 with the result that
99 .BR times ()
100 just returns a function result.
101 However,
102 POSIX does not specify this behavior,
103 and most
104 other UNIX implementations require a non-NULL value for
105 .IR buf .
106 .SH STANDARDS
107 POSIX.1-2024.
108 .SH HISTORY
109 POSIX.1-2001,
110 SVr4,
111 4.3BSD.
112 .P
113 In POSIX.1-1996 the symbol
114 .B CLK_TCK
115 (defined in
116 .IR <time.h> )
117 is mentioned as obsolescent.
118 It is obsolete now.
119 .P
120 Before Linux 2.6.9,
121 if the disposition of
122 .B SIGCHLD
123 is set to
124 .BR SIG_IGN ,
125 then the times of terminated children
126 are automatically included in the
127 .I tms_cstime
128 and
129 .I tms_cutime
130 fields,
131 although POSIX.1-2001 says that this should happen
132 only if the calling process
133 .BR wait (2)s
134 on its children.
135 This nonconformance is rectified in Linux 2.6.9 and later.
136 .\" See the description of times() in XSH, which says:
137 .\" The times of a terminated child process are included [...] when wait()
138 .\" or waitpid() returns the process ID of this terminated child.
139 .P
140 On Linux,
141 the \[lq]arbitrary point in the past\[rq]
142 from which the return value of
143 .BR times ()
144 is measured has varied across kernel versions.
145 On Linux 2.4 and earlier,
146 this point is the moment the system was booted.
147 Since Linux 2.6,
148 this point is
149 .I (2\[ha]32/HZ)\ \-\ 300
150 seconds before system boot time.
151 This variability across kernel versions (and across UNIX implementations),
152 combined with the fact that the returned value may overflow the range of
153 .IR clock_t ,
154 means that a portable application would be wise to avoid using this value.
155 To measure changes in elapsed time,
156 use
157 .BR clock_gettime (2)
158 instead.
159 .\" .P
160 .\" On older systems the number of clock ticks per second is given
161 .\" by the variable HZ.
162 .P
163 SVr1-3 returns
164 .I long
165 and the struct members are of type
166 .I time_t
167 although they store clock ticks,
168 not seconds since the Epoch.
169 V7 used
170 .I long
171 for the struct members,
172 because it had no type
173 .I time_t
174 yet.
175 .SH NOTES
176 The number of clock ticks per second can be obtained using:
177 .P
178 .in +4n
179 .EX
180 sysconf(_SC_CLK_TCK);
181 .EE
182 .in
183 .P
184 Note that
185 .BR clock (3)
186 also returns a value of type
187 .IR clock_t ,
188 but this value is measured in units of
189 .BR CLOCKS_PER_SEC ,
190 not the clock ticks used by
191 .BR times ().
192 .SH BUGS
193 A limitation of the Linux system call conventions on some architectures
194 (notably i386) means that on Linux 2.6 there is a small time window
195 (41 seconds) soon after boot when
196 .BR times ()
197 can return \-1,
198 falsely indicating that an error occurred.
199 The same problem can occur when the return value wraps past
200 the maximum value that can be stored in
201 .BR clock_t .
202 .\" The problem is that a syscall return of -4095 to -1
203 .\" is interpreted by glibc as an error, and the wrapper converts
204 .\" the return value to -1.
205 .\" http://marc.info/?l=linux-kernel&m=119447727031225&w=2
206 .\" "compat_sys_times() bogus until jiffies >= 0"
207 .\" November 2007
208 .SH SEE ALSO
209 .BR time (1),
210 .BR getrusage (2),
211 .BR wait (2),
212 .BR clock (3),
213 .BR sysconf (3),
214 .BR time (7)