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 May 2, 2009 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 , 99.Xr kgmon 8 100and 101.Xr gprof 1 . 102Applications should determine its actual frequency using 103.Xr sysctl 3 104or by reading it from the header in the profiling data file. 105.It 106The mc14618a clock. This is a real clock with a nominal frequency of 10732768. It is divided down to give the statistic clock and the profiling 108clock. It isn't available to applications. 109.It 110The microseconds clock. This is a virtual clock with frequency 1111000000. It is used for most timekeeping in 112.Bx 113and is exported 114to applications in 115.Xr getrusage 2 , 116.Xr gettimeofday 2 , 117.Xr select 2 , 118.Xr getitimer 2 , 119etc... This is the clock that should normally be used 120by 121.Bx 122applications. 123.It 124The i8254 clock. This is a real clock/timer with a nominal frequency of 1251193182. It is divided down to give the scheduling clock. It isn't 126available to applications. 127.It 128The TSC clock (64-bit register) on fifth-generation or later x86 systems. 129This is a real clock with a frequency that is equivalent to the number of 130cycles per second of the CPU(s). 131Its frequency can be found using the sysctl 132.Va hw.tsc_frequency 133and its presence via 134.Va hw.tsc_present . 135It is used to interpolate between values of the scheduling clock. 136It is only available to applications in a purely machine-dependent manner. 137.It 138The HPET (High Precision Event Timers). 139Only main counter is used currently. 140This CPU timer is expected to be faster than ACPI-fast24 and ACPI-safe, 141so it should be given higher priority. 142HPET is not enabled by default. 143To enable it, you should add 144.Li debug.acpi.enabled="hpet" 145to your 146.Pa /boot/loader.conf . 147If the HPET is detected and attached, 148.Va kern.cputimer.name 149will report 150.Li HPET . 151.El 152.Pp 153Summary: if 154.Ql HZ 155isn't 1000000 then the application is probably using the wrong clock. 156.Sh SEE ALSO 157.Xr gprof 1 , 158.Xr getitimer 2 , 159.Xr getrusage 2 , 160.Xr gettimeofday 2 , 161.Xr select 2 , 162.Xr clock 3 , 163.Xr moncontrol 3 , 164.Xr times 3 , 165.Xr loader.conf 5 166.Sh AUTHORS 167.An -nosplit 168This man page has been written by 169.An J\(:org Wunsch 170after a description posted by 171.An Bruce Evans . 172