Debian Codegraph @

upstream/debian-trixie/man2/times.2

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