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.Dd January 18, 2008 29.Dt CLOCKS 7 30.Os 31.Sh NAME 32.Nm clocks 33.Nd various system timers 34.Sh SYNOPSIS 35.In time.h 36.Sh DESCRIPTION 37.Dv HZ 38is not part of the application interface in 39.Bx . 40.Pp 41There are many different real and virtual (timekeeping) clocks with 42different frequencies: 43.Bl -bullet 44.It 45The scheduling clock. 46This is a real clock with frequency that happens to be 100. 47It is not available to applications. 48.It 49The statistics clock. 50This is a real clock with frequency that happens to be 128. 51It is not 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. 56Its actual frequency is given by the macro 57.Dv CLOCKS_PER_SEC . 58Note that 59.Dv CLOCKS_PER_SEC 60may be floating point. 61Do not use 62.Xr clock 3 63in new programs under 64.Fx . 65It is feeble compared with 66.Xr getrusage 2 . 67It is provided for 68.Tn ANSI 69conformance. 70It is implemented by calling 71.Xr getrusage 2 72and throwing away information and resolution. 73.It 74The clock reported by 75.Xr times 3 . 76This is a virtual clock with a frequency that happens to be 128. 77Its actual frequency is given by the macro 78.Dv CLK_TCK 79(deprecated; do not use) and by 80.Fn sysconf _SC_CLK_TCK 81and by 82.Xr sysctl 3 . 83Note that its frequency may be different from 84.Dv CLOCKS_PER_SEC . 85Do not use 86.Xr times 3 87in new programs under 88.Fx . 89It is feeble compared with 90.Xr gettimeofday 2 91together with 92.Xr getrusage 2 . 93It is provided for 94.Tn POSIX 95conformance. 96It is implemented by calling 97.Xr gettimeofday 2 98and 99.Xr getrusage 2 100and throwing away information and resolution. 101.It 102The profiling clock. 103This is a real clock with frequency 1024. 104It is used mainly by 105.Xr moncontrol 3 106and 107.Xr gprof 1 . 108Applications should determine its actual frequency using 109.Xr sysctl 3 110or by reading it from the header in the profiling data file. 111.It 112The mc146818a clock. 113This is a real clock with a nominal frequency of 32768. 114It is divided down to give the statistic clock and the profiling clock. 115It is not available to applications. 116.It 117The microseconds clock. 118This is a virtual clock with frequency 1000000. 119It is used for most timekeeping in 120.Bx 121and is exported to applications in 122.Xr getrusage 2 , 123.Xr gettimeofday 2 , 124.Xr select 2 , 125.Xr getitimer 2 , 126etc. 127This is the clock that should normally be used by 128.Bx 129applications. 130.It 131The i8254 clock. 132This is a real clock/timer with a nominal frequency of 1193182. 133It has three independent time counters to be used. 134It is divided down to give the scheduling clock. 135It is not available to applications. 136.It 137The TSC clock (64-bit register) on fifth-generation or later x86 systems. 138This is a real clock with a frequency that is equivalent to the number of 139cycles per second of the CPU(s). 140Its frequency can be found using the 141.Va machdep.tsc_freq 142sysctl, if it is available. 143It is used to interpolate between values of the scheduling clock. 144It can be accessed using the 145.Dv PMIOTSTAMP 146request of 147.Xr perfmon 4 . 148.It 149The ACPI clock. 150This is a real clock/timer with a nominal frequency of 3579545. 151It is accessed via a 24 or 32 bit register. 152Unlike the TSC clock, it maintains a constant tick rate even when the CPU 153sleeps or its clock rate changes. 154It is not available to applications. 155.El 156.Pp 157Summary: if 158.Dv HZ 159is not 1000000 then the application is probably using the wrong clock. 160.Sh SEE ALSO 161.Xr gprof 1 , 162.Xr clock_gettime 2 , 163.Xr getitimer 2 , 164.Xr getrusage 2 , 165.Xr gettimeofday 2 , 166.Xr select 2 , 167.Xr clock 3 , 168.Xr moncontrol 3 , 169.Xr times 3 170.Sh AUTHORS 171.An -nosplit 172This manual page was written by 173.An J\(:org Wunsch 174after a description posted by 175.An Bruce Evans . 176