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 2012-10-01 "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 any timer expires, a signal is sent to the
  28 process, and the timer (potentially) restarts.
  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; /* next value */
  57     struct timeval it_value;    /* current value */
  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 setting for the timer specified by
  73 .I which
  74 (one of
  75 .BR ITIMER_REAL ,
  76 .BR ITIMER_VIRTUAL ,
  77 or
  78 .BR ITIMER_PROF ).
  79 The element
  80 .I it_value
  81 is set to the amount of time remaining on the timer, or zero if the timer
  82 is disabled.
  83 Similarly,
  84 .I it_interval
  85 is set to the reset value.
  86
  87 The function
  88 .BR setitimer ()
  89 sets the specified timer to the value in
  90 .IR new_value .
  91 If
  92 .I old_value
  93 is non-NULL, the old value of the timer is stored there.
  94 .LP
  95 Timers decrement from
  96 .I it_value
  97 to zero, generate a signal, and reset to
  98 .IR it_interval .
  99 A timer which is set to zero
 100 .RI ( it_value
 101 is zero or the timer expires and
 102 .I it_interval
 103 is zero) stops.
 104 .LP
 105 Both
 106 .I tv_sec
 107 and
 108 .I tv_usec
 109 are significant in determining the duration of a timer.
 110 .LP
 111 Timers will never expire before the requested time,
 112 but may expire some (short) time afterward, which depends
 113 on the system timer resolution and on the system load; see
 114 .BR time (7).
 115 (But see BUGS below.)
 116 Upon expiration, a signal will be generated and the timer reset.
 117 If the timer expires while the process is active (always true for
 118 .BR ITIMER_VIRTUAL ),
 119 the signal will be delivered immediately when generated.
 120 Otherwise, the
 121 delivery will be offset by a small time dependent on the system loading.
 122 .SH RETURN VALUE
 123 On success, zero is returned.
 124 On error, \-1 is returned, and
 125 .I errno
 126 is set appropriately.
 127 .SH ERRORS
 128 .TP
 129 .B EFAULT
 130 .IR new_value ,
 131 .IR old_value ,
 132 or
 133 .I curr_value
 134 is not valid a pointer.
 135 .TP
 136 .B EINVAL
 137 .I which
 138 is not one of
 139 .BR ITIMER_REAL ,
 140 .BR ITIMER_VIRTUAL ,
 141 or
 142 .BR ITIMER_PROF ;
 143 or (since Linux 2.6.22) one of the
 144 .I tv_usec
 145 fields in the structure pointed to by
 146 .I new_value
 147 contains a value outside the range 0 to 999999.
 148 .SH CONFORMING TO
 149 POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
 150 POSIX.1-2008 marks
 151 .BR getitimer ()
 152 and
 153 .BR setitimer ()
 154 obsolete, recommending the use of the POSIX timers API
 155 .RB ( timer_gettime (2),
 156 .BR timer_settime (2),
 157 etc.) instead.
 158 .SH NOTES
 159 A child created via
 160 .BR fork (2)
 161 does not inherit its parent's interval timers.
 162 Interval timers are preserved across an
 163 .BR execve (2).
 164
 165 POSIX.1 leaves the
 166 interaction between
 167 .BR setitimer ()
 168 and the three interfaces
 169 .BR alarm (2),
 170 .BR sleep (3),
 171 and
 172 .BR usleep (3)
 173 unspecified.
 174
 175 The standards are silent on the meaning of the call:
 176
 177     setitimer(which, NULL, &old_value);
 178
 179 Many systems (Solaris, the BSDs, and perhaps others)
 180 treat this as equivalent to:
 181
 182     getitimer(which, &old_value);
 183
 184 In Linux, this is treated as being equivalent to a call in which the
 185 .I new_value
 186 fields are zero; that is, the timer is disabled.
 187 .IR "Don't use this Linux misfeature" :
 188 it is nonportable and unnecessary.
 189 .SH BUGS
 190 The generation and delivery of a signal are distinct, and
 191 only one instance of each of the signals listed above may be pending
 192 for a process.
 193 Under very heavy loading, an
 194 .B ITIMER_REAL
 195 timer may expire before the signal from a previous expiration
 196 has been delivered.
 197 The second signal in such an event will be lost.
 198
 199 On Linux kernels before 2.6.16, timer values are represented in jiffies.
 200 If a request is made set a timer with a value whose jiffies
 201 representation exceeds
 202 .B MAX_SEC_IN_JIFFIES
 203 (defined in
 204 .IR include/linux/jiffies.h ),
 205 then the timer is silently truncated to this ceiling value.
 206 On Linux/i386 (where, since Linux 2.6.13,
 207 the default jiffy is 0.004 seconds),
 208 this means that the ceiling value for a timer is
 209 approximately 99.42 days.
 210 Since Linux 2.6.16,
 211 the kernel uses a different internal representation for times,
 212 and this ceiling is removed.
 213
 214 On certain systems (including i386),
 215 Linux kernels before version 2.6.12 have a bug which will produce
 216 premature timer expirations of up to one jiffy under some circumstances.
 217 This bug is fixed in kernel 2.6.12.
 218 .\" 4 Jul 2005: It looks like this bug may remain in 2.4.x.
 219 .\"     http://lkml.org/lkml/2005/7/1/165
 220
 221 POSIX.1-2001 says that
 222 .BR setitimer ()
 223 should fail if a
 224 .I tv_usec
 225 value is specified that is outside of the range 0 to 999999.
 226 However, in kernels up to and including 2.6.21,
 227 Linux does not give an error, but instead silently
 228 adjusts the corresponding seconds value for the timer.
 229 From kernel 2.6.22 onward,
 230 this nonconformance has been repaired:
 231 an improper
 232 .I tv_usec
 233 value results in an
 234 .B EINVAL
 235 error.
 236 .\" Bugzilla report 25 Apr 2006:
 237 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
 238 .\" "setitimer() should reject noncanonical arguments"
 239 .SH SEE ALSO
 240 .BR gettimeofday (2),
 241 .BR sigaction (2),
 242 .BR signal (2),
 243 .BR timer_create (2),
 244 .BR timerfd_create (2),
 245 .BR time (7)
 246 .SH COLOPHON
 247 This page is part of release 3.67 of the Linux
 248 .I man-pages
 249 project.
 250 A description of the project,
 251 information about reporting bugs,
 252 and the latest version of this page,
 253 can be found at
 254 \%http://www.kernel.org/doc/man\-pages/.