man2/getitimer.2

   1 .\" Copyright 7/93 by Darren Senn <sinster@scintilla.santa-clara.ca.us>
   2 .\" and Copyright (C) 2016, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" Based on a similar page Copyright 1992 by Rick Faith
   4 .\"
   5 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
   6 .\" May be freely distributed and modified
   7 .\" %%%LICENSE_END
   8 .\"
   9 .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
  10 .\" 2005-04-06 mtk, Matthias Lang <matthias@corelatus.se>
  11 .\"     Noted MAX_SEC_IN_JIFFIES ceiling
  12 .\"
  13 .TH GETITIMER 2 2017-09-15 "Linux" "Linux Programmer's Manual"
  14 .SH NAME
  15 getitimer, setitimer \- get or set value of an interval timer
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <sys/time.h>
  19 .PP
  20 .BI "int getitimer(int " which ", struct itimerval *" curr_value );
  21 .BI "int setitimer(int " which ", const struct itimerval *" new_value ,
  22 .BI "              struct itimerval *" old_value );
  23 .fi
  24 .SH DESCRIPTION
  25 These system calls provide access to interval timers, that is,
  26 timers that initially expire at some point in the future,
  27 and (optionally) at regular intervals after that.
  28 When a timer expires, a signal is generated for the calling process,
  29 and the timer is reset to the specified interval
  30 (if the interval is nonzero).
  31 .PP
  32 Three types of timers\(emspecified via the
  33 .IR which
  34 argument\(emare provided,
  35 each of which counts against a different clock and
  36 generates a different signal on timer expiration:
  37 .TP 1.5i
  38 .B ITIMER_REAL
  39 This timer counts down in real (i.e., wall clock) time.
  40 At each expiration, a
  41 .B SIGALRM
  42 signal is generated.
  43 .TP
  44 .B ITIMER_VIRTUAL
  45 This timer counts down against the user-mode CPU time consumed by the process.
  46 (The measurement includes CPU time consumed by all threads in the process.)
  47 At each expiration, a
  48 .B SIGVTALRM
  49 signal is generated.
  50 .TP
  51 .B ITIMER_PROF
  52 This timer counts down against the total (i.e., both user and system)
  53 CPU time consumed by the process.
  54 (The measurement includes CPU time consumed by all threads in the process.)
  55 At each expiration, a
  56 .B SIGPROF
  57 signal is generated.
  58 .IP
  59 In conjunction with
  60 .BR ITIMER_VIRTUAL ,
  61 this timer can be used to profile user and system CPU time
  62 consumed by the process.
  63 .PP
  64 A process has only one of each of the three types of timers.
  65 .PP
  66 Timer values are defined by the following structures:
  67 .PP
  68 .in +4n
  69 .EX
  70 struct itimerval {
  71     struct timeval it_interval; /* Interval for periodic timer */
  72     struct timeval it_value;    /* Time until next expiration */
  73 };
  74
  75 struct timeval {
  76     time_t      tv_sec;         /* seconds */
  77     suseconds_t tv_usec;        /* microseconds */
  78 };
  79 .EE
  80 .in
  81 .\"
  82 .SS getitimer()
  83 The function
  84 .BR getitimer ()
  85 places the current value of the timer specified by
  86 .IR which
  87 in the buffer pointed to by
  88 .IR curr_value .
  89 .PP
  90 The
  91 .IR it_value
  92 substructure is populated with the amount of time remaining until
  93 the next expiration of the specified timer.
  94 This value changes as the timer counts down, and will be reset to
  95 .IR it_interval
  96 when the timer expires.
  97 If both fields of
  98 .IR it_value
  99 are zero, then this timer is currently disarmed (inactive).
 100 .PP
 101 The
 102 .IR it_interval
 103 substructure is populated with the timer interval.
 104 If both fields of
 105 .IR it_interval
 106 are zero, then this is a single-shot timer (i.e., it expires just once).
 107 .SS setitimer()
 108 The function
 109 .BR setitimer ()
 110 arms or disarms the timer specified by
 111 .IR which ,
 112 by setting the timer to the value specified by
 113 .IR new_value .
 114 If
 115 .I old_value
 116 is non-NULL,
 117 the buffer it points to is used to return the previous value of the timer
 118 (i.e., the same information that is returned by
 119 .BR getitimer ()).
 120 .PP
 121 If either field in
 122 .IR new_value.it_value
 123 is nonzero,
 124 then the timer is armed to initially expire at the specified time.
 125 If both fields in
 126 .IR new_value.it_value
 127 are zero, then the timer is disarmed.
 128 .PP
 129 The
 130 .IR new_value.it_interval
 131 field specifies the new interval for the timer;
 132 if both of its subfields are zero, the timer is single-shot.
 133 .SH RETURN VALUE
 134 On success, zero is returned.
 135 On error, \-1 is returned, and
 136 .I errno
 137 is set appropriately.
 138 .SH ERRORS
 139 .TP
 140 .B EFAULT
 141 .IR new_value ,
 142 .IR old_value ,
 143 or
 144 .I curr_value
 145 is not valid a pointer.
 146 .TP
 147 .B EINVAL
 148 .I which
 149 is not one of
 150 .BR ITIMER_REAL ,
 151 .BR ITIMER_VIRTUAL ,
 152 or
 153 .BR ITIMER_PROF ;
 154 or (since Linux 2.6.22) one of the
 155 .I tv_usec
 156 fields in the structure pointed to by
 157 .I new_value
 158 contains a value outside the range 0 to 999999.
 159 .SH CONFORMING TO
 160 POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
 161 POSIX.1-2008 marks
 162 .BR getitimer ()
 163 and
 164 .BR setitimer ()
 165 obsolete, recommending the use of the POSIX timers API
 166 .RB ( timer_gettime (2),
 167 .BR timer_settime (2),
 168 etc.) instead.
 169 .SH NOTES
 170 Timers will never expire before the requested time,
 171 but may expire some (short) time afterward, which depends
 172 on the system timer resolution and on the system load; see
 173 .BR time (7).
 174 (But see BUGS below.)
 175 If the timer expires while the process is active (always true for
 176 .BR ITIMER_VIRTUAL ),
 177 the signal will be delivered immediately when generated.
 178 .PP
 179 A child created via
 180 .BR fork (2)
 181 does not inherit its parent's interval timers.
 182 Interval timers are preserved across an
 183 .BR execve (2).
 184 .PP
 185 POSIX.1 leaves the
 186 interaction between
 187 .BR setitimer ()
 188 and the three interfaces
 189 .BR alarm (2),
 190 .BR sleep (3),
 191 and
 192 .BR usleep (3)
 193 unspecified.
 194 .PP
 195 The standards are silent on the meaning of the call:
 196 .PP
 197     setitimer(which, NULL, &old_value);
 198 .PP
 199 Many systems (Solaris, the BSDs, and perhaps others)
 200 treat this as equivalent to:
 201 .PP
 202     getitimer(which, &old_value);
 203 .PP
 204 In Linux, this is treated as being equivalent to a call in which the
 205 .I new_value
 206 fields are zero; that is, the timer is disabled.
 207 .IR "Don't use this Linux misfeature" :
 208 it is nonportable and unnecessary.
 209 .SH BUGS
 210 The generation and delivery of a signal are distinct, and
 211 only one instance of each of the signals listed above may be pending
 212 for a process.
 213 Under very heavy loading, an
 214 .B ITIMER_REAL
 215 timer may expire before the signal from a previous expiration
 216 has been delivered.
 217 The second signal in such an event will be lost.
 218 .PP
 219 On Linux kernels before 2.6.16, timer values are represented in jiffies.
 220 If a request is made set a timer with a value whose jiffies
 221 representation exceeds
 222 .B MAX_SEC_IN_JIFFIES
 223 (defined in
 224 .IR include/linux/jiffies.h ),
 225 then the timer is silently truncated to this ceiling value.
 226 On Linux/i386 (where, since Linux 2.6.13,
 227 the default jiffy is 0.004 seconds),
 228 this means that the ceiling value for a timer is
 229 approximately 99.42 days.
 230 Since Linux 2.6.16,
 231 the kernel uses a different internal representation for times,
 232 and this ceiling is removed.
 233 .PP
 234 On certain systems (including i386),
 235 Linux kernels before version 2.6.12 have a bug which will produce
 236 premature timer expirations of up to one jiffy under some circumstances.
 237 This bug is fixed in kernel 2.6.12.
 238 .\" 4 Jul 2005: It looks like this bug may remain in 2.4.x.
 239 .\"     http://lkml.org/lkml/2005/7/1/165
 240 .PP
 241 POSIX.1-2001 says that
 242 .BR setitimer ()
 243 should fail if a
 244 .I tv_usec
 245 value is specified that is outside of the range 0 to 999999.
 246 However, in kernels up to and including 2.6.21,
 247 Linux does not give an error, but instead silently
 248 adjusts the corresponding seconds value for the timer.
 249 From kernel 2.6.22 onward,
 250 this nonconformance has been repaired:
 251 an improper
 252 .I tv_usec
 253 value results in an
 254 .B EINVAL
 255 error.
 256 .\" Bugzilla report 25 Apr 2006:
 257 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
 258 .\" "setitimer() should reject noncanonical arguments"
 259 .SH SEE ALSO
 260 .BR gettimeofday (2),
 261 .BR sigaction (2),
 262 .BR signal (2),
 263 .BR timer_create (2),
 264 .BR timerfd_create (2),
 265 .BR time (7)