Debian Codegraph @

upstream/debian-trixie/man3/clock.3

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