Overview of time.

diff --git a/man7/time.7 b/man7/time.7
new file mode 100644 (file)
index 0000000..fd7346d
--- /dev/null
+++ b/man7/time.7
@@ -0,0 +1,149 @@
+.\" Copyright (c) 2006 by Michael Kerrisk <mtk-manpages@gmx.net>
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.TH TIME 7 2006-04-28 "Linux 2.6.16" "Linux Programmer's Manual"
+.SH NAME
+time \- overview of time
+.SH DESCRIPTION
+.SS "Real time and process time"
+.I "Real time"
+is defined as time measured from some fixed point,
+either from a standard point in the past 
+(see the description of the Epoch and calendar time below),
+or from some point (e.g., the start) in the life of a process
+.RI ( "elapsed time" ).
+
+.I "Process time"
+is defined as the amount of CPU time used by a process.
+This is sometimes divided into 
+.I user
+and
+.I system
+components.
+User CPU time is the time spent executing code in user mode.
+System CPU time is the time spent by the kernel executing
+in system mode on behalf of the process (e.g., executing system calls).
+The
+.BR time (1)
+command can be used to determine the amount of CPU time consumed 
+during the execution of a program.
+A program can determine the amount of CPU time it has consumed using
+.BR times (2),
+.BR getrusage (2),
+or
+.BR clock (3).
+.SS "The Hardware Clock"
+Most computers have a (battery-powered) hardware clock which the kernel
+reads at boot time in order to initialize the software clock.
+For further details, see
+.BR rtc (4)
+and
+.BR hwclock (8).
+.SS "The Software Clock, HZ, and Jiffies"
+The accuracy of many system calls and timestamps is limited by 
+the resolution of the
+.IR "software clock" ,
+a clock maintained by the kernel which measures time in 
+.IR jiffies .
+The size of a jiffy is determined by the value of the kernel constant
+.IR HZ .
+The value of
+.I HZ
+varies across kernel versions and hardware platforms.
+On x86 the situation is as follows:
+on kernels up to and including 2.4.x, HZ was 100, 
+giving a jiffy value of 0.01 seconds;
+starting with with 2.6.0, HZ was raised to 1000, giving a jiffy of
+0.001 seconds; since kernel 2.6.13, the HZ value is a kernel
+configuration parameter and can be 100, 250 (the default) or 1000,
+yielding a jiffies value of, respectively, 0.01, 0.004, or 0.001 seconds.
+
+On Alpha and ia64,
+.I HZ
+is 1024.
+.SS "The Epoch"
+Unix systems represent time in seconds since the
+.IR Epoch ,
+which is defined as 0:00:00 UTC on the morning of 1 January 1970.
+
+A program can determine the 
+.IR "calendar time"
+using 
+.BR gettimeofday (2),
+which returns time (in seconds and microseconds) that have
+elapsed since the Epoch; 
+.BR time (2)
+provides similar information, but only with accuracy to the 
+nearest second.
+The system time can be changed using
+.BR settimeofday (2).
+.SS "Broken-down time"
+Certain library functions use a structure of
+type 
+.I tm
+to represent 
+.IR "broken-down time" ,
+which stores time value separated out into distinct components 
+(year, month, day, hour, minute, second, etc.).
+This structure is described in
+.BR ctime (3),
+which also describes functions that convert between calendar time and 
+broken-down time.
+Functions for converting between broken-down time and printable 
+string representations of the time are described in
+.BR ctime (3),
+.BR strftime (3),
+and
+.BR strptime (3).
+.SS "Sleeping and Setting Timers"
+Various system calls and functions allow a program to sleep (suspend execution) for a specified period of time; see 
+.BR nanosleep (2)
+and
+.BR sleep (3).
+
+Various system calls allow a process to set a timer that expires
+at some point in the future, and optionally at repeated intervals;
+see
+.BR alarm (2),
+.BR getitimer (2),
+and
+.BR timer_create (3).
+.\" FIXME . timer_create() and friends are not yet in man-pages
+.SH "SEE ALSO"
+.BR date (1),
+.BR time (1),
+.BR adjtimex (2),
+.BR alarm (2),
+.BR getitimer (2),
+.BR getrlimit (2),
+.BR getrusage (2),
+.BR gettimeofday (2),
+.BR nanosleep (2),
+.BR stat (2),
+.BR time (2),
+.BR times (2),
+.BR utime (2),
+.BR clock (3),
+.BR sleep (3),
+.BR ctime (3),
+.BR strftime (3),
+.BR strptime (3),
+.BR usleep (3),
+.BR rtc (4),
+.BR hwclock (8).