1.\"
2.\" Copyright (c) 1996 Joerg Wunsch
3.\"
4.\" All rights reserved.
5.\"
6.\" This program is free software.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27.\"
| 1.\"
2.\" Copyright (c) 1996 Joerg Wunsch
3.\"
4.\" All rights reserved.
5.\"
6.\" This program is free software.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27.\"
|
28.\" $FreeBSD: head/share/man/man7/clocks.7 69027 2000-11-22 09:35:58Z ru $
| 28.\" $FreeBSD: head/share/man/man7/clocks.7 76190 2001-05-01 14:10:12Z schweikh $
|
29.\" "
30.Dd April 1, 1996
31.Os
32.Dt CLOCKS 7
33.Sh NAME
34.Nm clocks
35.Nd various system timers
36.Sh SYNOPSIS
37.Fd #include <time.h>
38.Sh DESCRIPTION
39.Ql HZ
40is not part of the application interface in BSD.
41.Pp
42There are many different real and virtual (timekeeping) clocks with
43different frequencies:
44.Bl -bullet -offset XXX
45.It
46The scheduling clock. This is a real clock with frequency that
47happens to be 100. It isn't available to applications.
48.It
49The statistics clock. This is a real clock with frequency that
50happens to be 128. It isn't directly available to applications.
51.It
52The clock reported by
53.Xr clock 3 .
54This is a virtual clock with a frequency that happens to be 128. Its
55actual frequency is given by the macro
56.Dv CLOCKS_PER_SEC .
57Note that
58.Dv CLOCKS_PER_SEC
59may be floating point. Don't use
60.Fn clock
61in new programs under
62.Fx .
63It is feeble compared with
64.Xr getrusage 2 .
65It is provided for ANSI conformance. It is implemented by calling
66.Fn getrusage
67and throwing away information and resolution.
68.It
69The clock reported by
70.Xr times 3 .
71This is a virtual clock with a frequency that happens to be 128. Its
72actual frequency is given by the macro
73.Dv CLK_TCK
74(deprecated; don't use) and by
75.Fn sysconf SC_CLK_TCK
76and by
77.Xr sysctl 3 .
78Note that its frequency may be different from
79.Dv CLOCKS_PER_SEC .
80Don't use
81.Xr times 3
82in new programs under
83.Fx .
84It is feeble compared with
85.Xr gettimeofday 2
86together with
87.Fn getrusage .
88It is provided for POSIX
89conformance. It is implemented by calling
90.Fn gettimeofday
91and
92.Fn getrusage
93and throwing away information and resolution.
94.It
95The profiling clock. This is a real clock with frequency 1024.
96It is used mainly by
97.Xr moncontrol 3 ,
98.Xr kgmon 8
99and
100.Xr gprof 1 .
101Applications should determine its actual frequency using
102.Xr sysctl 3
103or by reading it from the header in the profiling data file.
104.It
105The mc14618a clock. This is a real clock with a nominal frequency of
10632768. It is divided down to give the statistic clock and the profiling
107clock. It isn't available to applications.
108.It
109The microseconds clock. This is a virtual clock with frequency
1101000000. It is used for most timekeeping in BSD and is exported
111to applications in
112.Xr getrusage 2 ,
113.Xr gettimeofday 2 ,
114.Xr select 2 ,
115.Xr getitimer 2 ,
116etc... This is the clock that should normally be used
117by BSD applications.
118.It
119The i8254 clock. This is a real clock/timer with a nominal frequency of
1201193182. It is divided down to give the scheduling clock. It isn't
121available to applications.
122.It
123The TSC clock (64-bit register) on fifth-generation or later x86 systems.
124This is a real clock with a frequency that is equivalent to the number of
125cycles per second of the CPU(s).
126Its frequency can be found using the sysctl
127.Sy machdep.tsc_freq .
128It is used to interpolate between values of the scheduling clock.
| 29.\" "
30.Dd April 1, 1996
31.Os
32.Dt CLOCKS 7
33.Sh NAME
34.Nm clocks
35.Nd various system timers
36.Sh SYNOPSIS
37.Fd #include <time.h>
38.Sh DESCRIPTION
39.Ql HZ
40is not part of the application interface in BSD.
41.Pp
42There are many different real and virtual (timekeeping) clocks with
43different frequencies:
44.Bl -bullet -offset XXX
45.It
46The scheduling clock. This is a real clock with frequency that
47happens to be 100. It isn't available to applications.
48.It
49The statistics clock. This is a real clock with frequency that
50happens to be 128. It isn't directly available to applications.
51.It
52The clock reported by
53.Xr clock 3 .
54This is a virtual clock with a frequency that happens to be 128. Its
55actual frequency is given by the macro
56.Dv CLOCKS_PER_SEC .
57Note that
58.Dv CLOCKS_PER_SEC
59may be floating point. Don't use
60.Fn clock
61in new programs under
62.Fx .
63It is feeble compared with
64.Xr getrusage 2 .
65It is provided for ANSI conformance. It is implemented by calling
66.Fn getrusage
67and throwing away information and resolution.
68.It
69The clock reported by
70.Xr times 3 .
71This is a virtual clock with a frequency that happens to be 128. Its
72actual frequency is given by the macro
73.Dv CLK_TCK
74(deprecated; don't use) and by
75.Fn sysconf SC_CLK_TCK
76and by
77.Xr sysctl 3 .
78Note that its frequency may be different from
79.Dv CLOCKS_PER_SEC .
80Don't use
81.Xr times 3
82in new programs under
83.Fx .
84It is feeble compared with
85.Xr gettimeofday 2
86together with
87.Fn getrusage .
88It is provided for POSIX
89conformance. It is implemented by calling
90.Fn gettimeofday
91and
92.Fn getrusage
93and throwing away information and resolution.
94.It
95The profiling clock. This is a real clock with frequency 1024.
96It is used mainly by
97.Xr moncontrol 3 ,
98.Xr kgmon 8
99and
100.Xr gprof 1 .
101Applications should determine its actual frequency using
102.Xr sysctl 3
103or by reading it from the header in the profiling data file.
104.It
105The mc14618a clock. This is a real clock with a nominal frequency of
10632768. It is divided down to give the statistic clock and the profiling
107clock. It isn't available to applications.
108.It
109The microseconds clock. This is a virtual clock with frequency
1101000000. It is used for most timekeeping in BSD and is exported
111to applications in
112.Xr getrusage 2 ,
113.Xr gettimeofday 2 ,
114.Xr select 2 ,
115.Xr getitimer 2 ,
116etc... This is the clock that should normally be used
117by BSD applications.
118.It
119The i8254 clock. This is a real clock/timer with a nominal frequency of
1201193182. It is divided down to give the scheduling clock. It isn't
121available to applications.
122.It
123The TSC clock (64-bit register) on fifth-generation or later x86 systems.
124This is a real clock with a frequency that is equivalent to the number of
125cycles per second of the CPU(s).
126Its frequency can be found using the sysctl
127.Sy machdep.tsc_freq .
128It is used to interpolate between values of the scheduling clock.
|
129It is only available to applications in a purely machine-dependant manner.
| 129It is only available to applications in a purely machine-dependent manner.
|
130.El
131.Pp
132Summary: if
133.Ql HZ
134isn't 1000000 then the application is probably using the wrong clock.
135.Sh SEE ALSO
136.Xr gprof 1 ,
137.Xr getitimer 2 ,
138.Xr getrusage 2 ,
139.Xr gettimeofday 2 ,
140.Xr select 2 ,
141.Xr clock 3 ,
142.Xr moncontrol 3 ,
143.Xr times 3
144.Sh AUTHORS
145.An -nosplit
146This man page has been written by
147.An J\(:org Wunsch
148after a description posted by
149.An Bruce Evans .
| 130.El
131.Pp
132Summary: if
133.Ql HZ
134isn't 1000000 then the application is probably using the wrong clock.
135.Sh SEE ALSO
136.Xr gprof 1 ,
137.Xr getitimer 2 ,
138.Xr getrusage 2 ,
139.Xr gettimeofday 2 ,
140.Xr select 2 ,
141.Xr clock 3 ,
142.Xr moncontrol 3 ,
143.Xr times 3
144.Sh AUTHORS
145.An -nosplit
146This man page has been written by
147.An J\(:org Wunsch
148after a description posted by
149.An Bruce Evans .
|