Debian Codegraph @

upstream/debian-unstable/man3/clock.3

raw
1 '\" t
2 .\" Copyright 1993, Thomas Koenig <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH clock 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 clock \- determine processor time
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <time.h>
16 .P
17 .B clock_t clock(void);
18 .fi
19 .SH DESCRIPTION
20 The
21 .BR clock ()
22 function returns an approximation of processor time used by the program.
23 .SH RETURN VALUE
24 The value returned is the CPU time used so far as a
25 .IR clock_t ;
26 to get the number of seconds used, divide by
27 .BR CLOCKS_PER_SEC .
28 If the processor time used is not available or its value cannot
29 be represented, the function returns the value
30 .IR (clock_t)\ \-1 .
31 .SH ATTRIBUTES
32 For an explanation of the terms used in this section, see
33 .BR attributes (7).
34 .TS
35 allbox;
36 lbx lb lb
37 l l l.
38 Interface Attribute Value
39 T{
40 .na
41 .nh
42 .BR clock ()
43 T} Thread safety MT-Safe
44 .TE
45 .SH VERSIONS
46 XSI requires that
47 .B CLOCKS_PER_SEC
48 equals 1000000 independent
49 of the actual resolution.
50 .P
51 On several other implementations,
52 the value returned by
53 .BR clock ()
54 also includes the times of any children whose status has been
55 collected via
56 .BR wait (2)
57 (or another wait-type call).
58 Linux does not include the times of waited-for children in the
59 value returned by
60 .BR clock ().
61 .\" I have seen this behavior on Irix 6.3, and the OSF/1, HP/UX, and
62 .\" Solaris manual pages say that clock() also does this on those systems.
63 .\" POSIX.1-2001 doesn't explicitly allow this, nor is there an
64 .\" explicit prohibition. -- MTK
65 The
66 .BR times (2)
67 function, which explicitly returns (separate) information about the
68 caller and its children, may be preferable.
69 .SH STANDARDS
70 C11, POSIX.1-2008.
71 .SH HISTORY
72 POSIX.1-2001, C89.
73 .P
74 In glibc 2.17 and earlier,
75 .BR clock ()
76 was implemented on top of
77 .BR times (2).
78 For improved accuracy,
79 since glibc 2.18, it is implemented on top of
80 .BR clock_gettime (2)
81 (using the
82 .B CLOCK_PROCESS_CPUTIME_ID
83 clock).
84 .SH NOTES
85 The C standard allows for arbitrary values at the start of the program;
86 subtract the value returned from a call to
87 .BR clock ()
88 at the start of the program to get maximum portability.
89 .P
90 Note that the time can wrap around.
91 On a 32-bit system where
92 .B CLOCKS_PER_SEC
93 equals 1000000 this function will return the same
94 value approximately every 72 minutes.
95 .SH SEE ALSO
96 .BR clock_gettime (2),
97 .BR getrusage (2),
98 .BR times (2)