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: src/share/man/man7/clocks.7,v 1.9.2.5 2001/12/17 11:30:15 ru Exp $ 29.\" 30.Dd January 5, 2019 31.Dt CLOCKS 7 32.Os 33.Sh NAME 34.Nm clocks 35.Nd various system timers 36.Sh SYNOPSIS 37.In time.h 38.Sh DESCRIPTION 39.Ql HZ 40is not part of the application interface in 41.Bx . 42.Pp 43There are many different real and virtual (timekeeping) clocks with 44different frequencies: 45.Bl -bullet -offset XXX 46.It 47The scheduling clock. This is a real clock with frequency that 48happens to be 100. It isn't available to applications. 49.It 50The statistics clock. This is a real clock with frequency that 51happens to be 128. It isn't directly available to applications. 52.It 53The clock reported by 54.Xr clock 3 . 55This is a virtual clock with a frequency that happens to be 128. Its 56actual frequency is given by the macro 57.Dv CLOCKS_PER_SEC . 58Note that 59.Dv CLOCKS_PER_SEC 60may be floating point. Don't use 61.Fn clock 62in new programs under 63.Dx . 64It is feeble compared with 65.Xr getrusage 2 . 66It is provided for ANSI conformance. It is implemented by calling 67.Fn getrusage 68and throwing away information and resolution. 69.It 70The clock reported by 71.Xr times 3 . 72This is a virtual clock with a frequency that happens to be 128. Its 73actual frequency is given by the macro 74.Dv CLK_TCK 75(deprecated; don't use) and by 76.Fn sysconf SC_CLK_TCK 77and by 78.Xr sysctl 3 . 79Note that its frequency may be different from 80.Dv CLOCKS_PER_SEC . 81Don't use 82.Xr times 3 83in new programs under 84.Dx . 85It is feeble compared with 86.Xr gettimeofday 2 87together with 88.Fn getrusage . 89It is provided for POSIX 90conformance. It is implemented by calling 91.Fn gettimeofday 92and 93.Fn getrusage 94and throwing away information and resolution. 95.It 96The profiling clock. This is a real clock with frequency 1024. 97It is used mainly by 98.Xr moncontrol 3 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 111.Bx 112and is exported 113to applications in 114.Xr getrusage 2 , 115.Xr gettimeofday 2 , 116.Xr select 2 , 117.Xr getitimer 2 , 118etc... This is the clock that should normally be used 119by 120.Bx 121applications. 122.It 123The i8254 clock. This is a real clock/timer with a nominal frequency of 1241193182. It is divided down to give the scheduling clock. It isn't 125available to applications. 126.It 127The TSC clock (64-bit register) on fifth-generation or later x86 systems. 128This is a real clock with a frequency that is equivalent to the number of 129cycles per second of the CPU(s). 130Its frequency can be found using the sysctl 131.Va hw.tsc_frequency 132and its presence via 133.Va hw.tsc_present . 134It is used to interpolate between values of the scheduling clock. 135It is only available to applications in a purely machine-dependent manner. 136.It 137The HPET (High Precision Event Timers). 138Only main counter is used currently. 139This CPU timer is expected to be faster than ACPI-fast24 and ACPI-safe, 140so it should be given higher priority. 141HPET is not enabled by default. 142To enable it, you should add 143.Li debug.acpi.enabled="hpet" 144to your 145.Pa /boot/loader.conf . 146If the HPET is detected and attached, 147.Va kern.cputimer.name 148will report 149.Li HPET . 150.El 151.Pp 152Summary: if 153.Ql HZ 154isn't 1000000 then the application is probably using the wrong clock. 155.Sh SEE ALSO 156.Xr gprof 1 , 157.Xr getitimer 2 , 158.Xr getrusage 2 , 159.Xr gettimeofday 2 , 160.Xr select 2 , 161.Xr clock 3 , 162.Xr moncontrol 3 , 163.Xr times 3 , 164.Xr loader.conf 5 165.Sh AUTHORS 166.An -nosplit 167This man page has been written by 168.An J\(:org Wunsch 169after a description posted by 170.An Bruce Evans . 171