Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 218 insertions, 0 deletions

diff --git a/man/man7/time.7 b/man/man7/time.7
new file mode 100644
index 0000000..8d472a6
--- /dev/null
+++ b/man/man7/time.7
@@ -0,0 +1,218 @@
+.\" Copyright (c) 2006 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 2008-06-24, mtk: added some details about where jiffies come into
+.\"     play; added section on high-resolution timers.
+.\"
+.TH time 7 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+time \- overview of time and timers
+.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" ).
+.P
+.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 various system calls that set timeouts,
+(e.g.,
+.BR select (2),
+.BR sigtimedwait (2))
+.\" semtimedop(), mq_timedwait(), io_getevents(), poll() are the same
+.\" futexes and thus sem_timedwait() seem to use high-res timers.
+and measure CPU time (e.g.,
+.BR getrusage (2))
+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 .
+.P
+The value of
+.I HZ
+varies across kernel versions and hardware platforms.
+On i386 the situation is as follows:
+on kernels up to and including Linux 2.4.x,
+HZ was 100,
+giving a jiffy value of 0.01 seconds;
+starting with Linux 2.6.0,
+HZ was raised to 1000,
+giving a jiffy of 0.001 seconds.
+Since Linux 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.
+Since Linux 2.6.20, a further frequency is available:
+300, a number that divides evenly for the common video frame rates
+(PAL, 25 Hz; NTSC, 30 Hz).
+.P
+The
+.BR times (2)
+system call is a special case.
+It reports times with a granularity defined by the kernel constant
+.IR USER_HZ .
+User-space applications can determine the value of this constant using
+.IR sysconf(_SC_CLK_TCK) .
+.\" glibc gets this info with a little help from the ELF loader;
+.\" see glibc elf/dl-support.c and kernel fs/binfmt_elf.c.
+.\"
+.SS System and process clocks; time namespaces
+The kernel supports a range of clocks that measure various kinds of
+elapsed and virtual (i.e., consumed CPU) time.
+These clocks are described in
+.BR clock_gettime (2).
+A few of the clocks are settable using
+.BR clock_settime (2).
+The values of certain clocks are virtualized by time namespaces; see
+.BR time_namespaces (7).
+.\"
+.SS High-resolution timers
+Before Linux 2.6.21, the accuracy of timer and sleep system calls
+(see below) was also limited by the size of the jiffy.
+.P
+Since Linux 2.6.21, Linux supports high-resolution timers (HRTs),
+optionally configurable via
+.BR CONFIG_HIGH_RES_TIMERS .
+On a system that supports HRTs, the accuracy of sleep and timer
+system calls is no longer constrained by the jiffy,
+but instead can be as accurate as the hardware allows
+(microsecond accuracy is typical of modern hardware).
+You can determine whether high-resolution timers are supported by
+checking the resolution returned by a call to
+.BR clock_getres (2)
+or looking at the "resolution" entries in
+.IR /proc/timer_list .
+.P
+HRTs are not supported on all hardware architectures.
+(Support is provided on x86, ARM, and PowerPC, among others.)
+.SS The Epoch
+UNIX systems represent time in seconds since the
+.IR Epoch ,
+1970-01-01 00:00:00 +0000 (UTC).
+.P
+A program can determine the
+.I "calendar time"
+via the
+.BR clock_gettime (2)
+.B CLOCK_REALTIME
+clock,
+which returns time (in seconds and nanoseconds) 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 clock_settime (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 tm (3type),
+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),
+.BR clock_nanosleep (2),
+and
+.BR sleep (3).
+.P
+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),
+.BR timerfd_create (2),
+and
+.BR timer_create (2).
+.SS Timer slack
+Since Linux 2.6.28, it is possible to control the "timer slack"
+value for a thread.
+The timer slack is the length of time by
+which the kernel may delay the wake-up of certain
+system calls that block with a timeout.
+Permitting this delay allows the kernel to coalesce wake-up events,
+thus possibly reducing the number of system wake-ups and saving power.
+For more details, see the description of
+.B PR_SET_TIMERSLACK
+in
+.BR prctl (2).
+.SH SEE ALSO
+.ad l
+.nh
+.BR date (1),
+.BR time (1),
+.BR timeout (1),
+.BR adjtimex (2),
+.BR alarm (2),
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.BR getitimer (2),
+.BR getrlimit (2),
+.BR getrusage (2),
+.BR gettimeofday (2),
+.BR nanosleep (2),
+.BR stat (2),
+.BR time (2),
+.BR timer_create (2),
+.BR timerfd_create (2),
+.BR times (2),
+.BR utime (2),
+.BR adjtime (3),
+.BR clock (3),
+.BR clock_getcpuclockid (3),
+.BR ctime (3),
+.BR ntp_adjtime (3),
+.BR ntp_gettime (3),
+.BR pthread_getcpuclockid (3),
+.BR sleep (3),
+.BR strftime (3),
+.BR strptime (3),
+.BR timeradd (3),
+.BR usleep (3),
+.BR rtc (4),
+.BR time_namespaces (7),
+.BR hwclock (8)