| .\" Copyright (c) 2006 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" 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. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 2008-06-24, mtk: added some details about where jiffies come into |
| .\" play; added section on high-resolution timers. |
| .\" |
| .TH TIME 7 2018-04-30 "Linux" "Linux Programmer's Manual" |
| .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" ). |
| .PP |
| .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 . |
| .PP |
| 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 2.4.x, HZ was 100, |
| giving a jiffy value of 0.01 seconds; |
| starting 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. |
| Since kernel 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). |
| .PP |
| 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 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. |
| .PP |
| 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 . |
| .PP |
| 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). |
| .PP |
| A program can determine the |
| .I "calendar time" |
| via the |
| .BR clock_gettime (2) |
| .BR 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 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), |
| .BR clock_nanosleep (2), |
| and |
| .BR sleep (3). |
| .PP |
| 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 hwclock (8) |