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