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