original/man2/getitimer.2

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