| .\" Copyright 7/93 by Darren Senn <sinster@scintilla.santa-clara.ca.us> |
| .\" and Copyright (C) 2016, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" Based on a similar page Copyright 1992 by Rick Faith |
| .\" |
| .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) |
| .\" May be freely distributed and modified |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> |
| .\" 2005-04-06 mtk, Matthias Lang <matthias@corelatus.se> |
| .\" Noted MAX_SEC_IN_JIFFIES ceiling |
| .\" |
| .TH GETITIMER 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| getitimer, setitimer \- get or set value of an interval timer |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/time.h> |
| .PP |
| .BI "int getitimer(int " which ", struct itimerval *" curr_value ); |
| .BI "int setitimer(int " which ", const struct itimerval *" new_value , |
| .BI " struct itimerval *" old_value ); |
| .fi |
| .SH DESCRIPTION |
| These system calls provide access to interval timers, that is, |
| timers that initially expire at some point in the future, |
| and (optionally) at regular intervals after that. |
| When a timer expires, a signal is generated for the calling process, |
| and the timer is reset to the specified interval |
| (if the interval is nonzero). |
| .PP |
| Three types of timers\(emspecified via the |
| .IR which |
| argument\(emare provided, |
| each of which counts against a different clock and |
| generates a different signal on timer expiration: |
| .TP 1.5i |
| .B ITIMER_REAL |
| This timer counts down in real (i.e., wall clock) time. |
| At each expiration, a |
| .B SIGALRM |
| signal is generated. |
| .TP |
| .B ITIMER_VIRTUAL |
| This timer counts down against the user-mode CPU time consumed by the process. |
| (The measurement includes CPU time consumed by all threads in the process.) |
| At each expiration, a |
| .B SIGVTALRM |
| signal is generated. |
| .TP |
| .B ITIMER_PROF |
| This timer counts down against the total (i.e., both user and system) |
| CPU time consumed by the process. |
| (The measurement includes CPU time consumed by all threads in the process.) |
| At each expiration, a |
| .B SIGPROF |
| signal is generated. |
| .IP |
| In conjunction with |
| .BR ITIMER_VIRTUAL , |
| this timer can be used to profile user and system CPU time |
| consumed by the process. |
| .PP |
| A process has only one of each of the three types of timers. |
| .PP |
| Timer values are defined by the following structures: |
| .PP |
| .in +4n |
| .EX |
| struct itimerval { |
| struct timeval it_interval; /* Interval for periodic timer */ |
| struct timeval it_value; /* Time until next expiration */ |
| }; |
| |
| struct timeval { |
| time_t tv_sec; /* seconds */ |
| suseconds_t tv_usec; /* microseconds */ |
| }; |
| .EE |
| .in |
| .\" |
| .SS getitimer() |
| The function |
| .BR getitimer () |
| places the current value of the timer specified by |
| .IR which |
| in the buffer pointed to by |
| .IR curr_value . |
| .PP |
| The |
| .IR it_value |
| substructure is populated with the amount of time remaining until |
| the next expiration of the specified timer. |
| This value changes as the timer counts down, and will be reset to |
| .IR it_interval |
| when the timer expires. |
| If both fields of |
| .IR it_value |
| are zero, then this timer is currently disarmed (inactive). |
| .PP |
| The |
| .IR it_interval |
| substructure is populated with the timer interval. |
| If both fields of |
| .IR it_interval |
| are zero, then this is a single-shot timer (i.e., it expires just once). |
| .SS setitimer() |
| The function |
| .BR setitimer () |
| arms or disarms the timer specified by |
| .IR which , |
| by setting the timer to the value specified by |
| .IR new_value . |
| If |
| .I old_value |
| is non-NULL, |
| the buffer it points to is used to return the previous value of the timer |
| (i.e., the same information that is returned by |
| .BR getitimer ()). |
| .PP |
| If either field in |
| .IR new_value.it_value |
| is nonzero, |
| then the timer is armed to initially expire at the specified time. |
| If both fields in |
| .IR new_value.it_value |
| are zero, then the timer is disarmed. |
| .PP |
| The |
| .IR new_value.it_interval |
| field specifies the new interval for the timer; |
| if both of its subfields are zero, the timer is single-shot. |
| .SH RETURN VALUE |
| On success, zero is returned. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| .IR new_value , |
| .IR old_value , |
| or |
| .I curr_value |
| is not valid a pointer. |
| .TP |
| .B EINVAL |
| .I which |
| is not one of |
| .BR ITIMER_REAL , |
| .BR ITIMER_VIRTUAL , |
| or |
| .BR ITIMER_PROF ; |
| or (since Linux 2.6.22) one of the |
| .I tv_usec |
| fields in the structure pointed to by |
| .I new_value |
| contains a value outside the range 0 to 999999. |
| .SH CONFORMING TO |
| POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD). |
| POSIX.1-2008 marks |
| .BR getitimer () |
| and |
| .BR setitimer () |
| obsolete, recommending the use of the POSIX timers API |
| .RB ( timer_gettime (2), |
| .BR timer_settime (2), |
| etc.) instead. |
| .SH NOTES |
| Timers will never expire before the requested time, |
| but may expire some (short) time afterward, which depends |
| on the system timer resolution and on the system load; see |
| .BR time (7). |
| (But see BUGS below.) |
| If the timer expires while the process is active (always true for |
| .BR ITIMER_VIRTUAL ), |
| the signal will be delivered immediately when generated. |
| .PP |
| A child created via |
| .BR fork (2) |
| does not inherit its parent's interval timers. |
| Interval timers are preserved across an |
| .BR execve (2). |
| .PP |
| POSIX.1 leaves the |
| interaction between |
| .BR setitimer () |
| and the three interfaces |
| .BR alarm (2), |
| .BR sleep (3), |
| and |
| .BR usleep (3) |
| unspecified. |
| .PP |
| The standards are silent on the meaning of the call: |
| .PP |
| setitimer(which, NULL, &old_value); |
| .PP |
| Many systems (Solaris, the BSDs, and perhaps others) |
| treat this as equivalent to: |
| .PP |
| getitimer(which, &old_value); |
| .PP |
| In Linux, this is treated as being equivalent to a call in which the |
| .I new_value |
| fields are zero; that is, the timer is disabled. |
| .IR "Don't use this Linux misfeature" : |
| it is nonportable and unnecessary. |
| .SH BUGS |
| The generation and delivery of a signal are distinct, and |
| only one instance of each of the signals listed above may be pending |
| for a process. |
| Under very heavy loading, an |
| .B ITIMER_REAL |
| timer may expire before the signal from a previous expiration |
| has been delivered. |
| The second signal in such an event will be lost. |
| .PP |
| On Linux kernels before 2.6.16, timer values are represented in jiffies. |
| If a request is made set a timer with a value whose jiffies |
| representation exceeds |
| .B MAX_SEC_IN_JIFFIES |
| (defined in |
| .IR include/linux/jiffies.h ), |
| then the timer is silently truncated to this ceiling value. |
| On Linux/i386 (where, since Linux 2.6.13, |
| the default jiffy is 0.004 seconds), |
| this means that the ceiling value for a timer is |
| approximately 99.42 days. |
| Since Linux 2.6.16, |
| the kernel uses a different internal representation for times, |
| and this ceiling is removed. |
| .PP |
| On certain systems (including i386), |
| Linux kernels before version 2.6.12 have a bug which will produce |
| premature timer expirations of up to one jiffy under some circumstances. |
| This bug is fixed in kernel 2.6.12. |
| .\" 4 Jul 2005: It looks like this bug may remain in 2.4.x. |
| .\" http://lkml.org/lkml/2005/7/1/165 |
| .PP |
| POSIX.1-2001 says that |
| .BR setitimer () |
| should fail if a |
| .I tv_usec |
| value is specified that is outside of the range 0 to 999999. |
| However, in kernels up to and including 2.6.21, |
| Linux does not give an error, but instead silently |
| adjusts the corresponding seconds value for the timer. |
| From kernel 2.6.22 onward, |
| this nonconformance has been repaired: |
| an improper |
| .I tv_usec |
| value results in an |
| .B EINVAL |
| error. |
| .\" Bugzilla report 25 Apr 2006: |
| .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443 |
| .\" "setitimer() should reject noncanonical arguments" |
| .SH SEE ALSO |
| .BR gettimeofday (2), |
| .BR sigaction (2), |
| .BR signal (2), |
| .BR timer_create (2), |
| .BR timerfd_create (2), |
| .BR time (7) |