Add clocks(7).

Submitted by:	bde

2 files changed, 124 insertions, 1 deletions

diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile
index 1bef6bc40ff2..4a085c485c70 100644
--- a/share/man/man7/Makefile
+++ b/share/man/man7/Makefile
@@ -1,7 +1,7 @@
 #	@(#)Makefile	8.1 (Berkeley) 6/5/93
 
 #MISSING: eqnchar.7 man.7 ms.7 term.7
-MAN7=	ascii.7 environ.7 hier.7 hostname.7 intro.7 mailaddr.7 \
+MAN7=	ascii.7 clocks.7 environ.7 hier.7 hostname.7 intro.7 mailaddr.7 \
 	mdoc.7 mdoc.samples.7 operator.7
 MLINKS=	intro.7 miscellaneous.7
 
diff --git a/share/man/man7/clocks.7 b/share/man/man7/clocks.7
new file mode 100644
index 000000000000..40b9bf0a48a7
--- /dev/null
+++ b/share/man/man7/clocks.7
@@ -0,0 +1,123 @@
+.\"
+.\" Copyright (c) 1996 Joerg Wunsch
+.\"
+.\" All rights reserved.
+.\"
+.\" This program is free software.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $Id$
+.\" "
+.Dd April 1, 1996
+.Os
+.Dt CLOCKS 7
+.Sh NAME
+.Nm timer
+.Nd various system timers
+.Sh SYNOPSIS
+.Fd #include <time.h>
+.Sh DESCRIPTION
+.Ql HZ
+is not part of the application interface in BSD.
+.Pp
+There are many different real and virtual (timekeeping) clocks with
+different frequencies:
+.Bl -bullet -offset XXX
+.It
+The scheduling clock.  This is a real clock with frequency that
+happens to be 100.  It isn't available to applications.
+.It
+The statistics clock.  This is a real clock with frequency that
+happens to be 128.  It isn't directly available to applications.
+.It
+The clock reported by
+.Xr clock 3 .
+This is a virtual clock with a frequency that happens to be 128.  It's
+actual frequency is given by the macro CLOCKS_PER_SEC.  Note that
+CLOCKS_PER_SEC may be floating point.  Don't use clock() in new
+programs under FreeBSD.  It is feeble compared with
+.Xr getrusage 2 .
+It is provided for ANSI conformance.  It is implemented by calling
+getrusage() and throwing away information and resolution.
+.It
+The clock reported by
+.Xr times 3 .
+This is a virtual clock with a frequency that happens to be 128.  It's
+actual frequency is given by the macro CLK_TCK (deprecated; don't use)
+and by sysconf(_SC_CLK_TCK) and by
+.Xr sysctl 3 .
+Note that its frequency may be different fro CLOCKS_PER_SEC.  Don't
+use times() in new programs under FreeBSD.  It is feeble compared with
+gettimeofday() together with getrusage().  It is provided for POSIX
+conformance.  It is implemented by calling gettimeofday() and
+getrusage() and throwing away information and resolution.
+.It
+The profiling clock.  This is a real clock with frequency 1024.
+It is used mainly by
+.Xr moncontrol 3 ,
+.Xr kgmon 8
+and
+.Xr gprof 1 .
+Applications should determine its actual frequency using
+.Xr sysctl 3
+or by reading it from the header in the profiling data file.
+.It
+The mc14618a clock.  This is a real clock with a nominal frequency of
+32768.  It is divided down to give the statistic clock and the profiling
+clock.  It isn't available to applications.
+.It
+The microseconds clock.  This is a virtual clock with frequency
+1000000.  It is used for most timekeeping in BSD and is exported
+to applications in
+.Xr getrusage 2 ,
+.Xr gettimeofday 2 ,
+.Xr select 2 ,
+.Xr getitimer 2 ,
+...  This is the clock that should normally be used
+by BSD applications.
+.It
+the i8254 clock.  This is a real clock with a nominal frequency of
+1193182.  It is divided down to give the scheduling clock.  It isn't
+available to applications.
+.It
+the i586 clock on i586 systems.  This is a real clock with a frequency
+of up to 200000000.  It is used to interpolate between values of the
+scheduling clock.  It isn't available to applications.
+.El
+.Pp
+Summary: if
+.Ql HZ
+isn't 1000000 then the application is probably using the wrong clock.
+.Sh SEE ALSO
+.Xr gprof 1 ,
+.Xr getitimer 2 ,
+.Xr getrusage 2 ,
+.Xr gettimeofday 2 ,
+.Xr select 2 ,
+.Xr clock 3 ,
+.Xr moncontrol 3 ,
+.Xr times 3
+.Sh AUTHORS
+This man page has been written by
+.ie t J\(:org Wunsch
+.el Joerg Wunsch
+after a description posted by Bruce Evans.