man/man2/getitimer.2

   1 .TH GETITIMER 2  "April 14, 2006"
   2 .UC 4
   3 .SH NAME
   4 getitimer, setitimer \- get and set value of interval timer
   5 .SH SYNOPSIS
   6 .nf
   7 .ft B
   8 #include <sys/time.h>
   9
  10 int getitimer(int \fIwhich\fP, struct itimerval *\fIvalue\fP)
  11 .in +5
  12 .ti -5
  13 int setitimer(int \fIwhich\fP, const struct itimerval *\fIvalue\fP, struct itimerval *\fIovalue\fP);
  14 .in -5
  15 .ft R
  16 .fi
  17 .SH DESCRIPTION
  18 .B Getitimer
  19 retrieves the current value of the given interval timer, in \fIvalue\fP.
  20 .PP
  21 .B Setitimer
  22 sets a new value for the given interval timer, as given in \fIvalue\fP, and, if \fIovalue\fP is not set to
  23 .BR NULL ,
  24 stores the old value for the interval timer in \fIovalue\fP.
  25 .PP
  26 For both functions, the \fIwhich\fP parameter indicates which of the interval timers they work on; \fIwhich\fP can have one of the following values:
  27 .PP
  28 .TP 15
  29 .B ITIMER_REAL
  30 A timer that is decremented in realtime. When it expires, a
  31 .BR SIGARLM
  32 signal is delivered to the process.
  33 .TP
  34 .B ITIMER_VIRTUAL
  35 A timer that is decremented in process user time. When it expires, a
  36 .BR SIGVTALRM
  37 signal is delivered to the process.
  38 .TP
  39 .B ITIMER_PROF
  40 A timer that is decremented in process user+system time. When it expires, a
  41 .BR SIGPROF
  42 signal is delivered to the process.
  43 .PP
  44 The specified timer will first expire after the time specified in the 'it_value' field of the itimerval structure. Similarly, upon retrieval the 'it_value' field will contain the time after which the timer will expire.
  45 .PP
  46 If 'it_value' is zero, then the timer is disabled, and the 'it_interval' field is ignored and (upon retrieval) set to zero. Otherwise, 'it_interval' contains the repetition interval after which the timer will repeatedly expire, starting from the moment that the timer expires for the first time according to the 'it_value' value. If 'it_interval' is set to zero, no repetition will occur.
  47 .PP
  48 The maximum supported timeout value that
  49 .B setitimer
  50 accepts, depends on the clock tick rate of the operating system.
  51 .PP
  52 These functions share their real-time timer with
  53 .BR alarm (2).
  54 Therefore, use of both types of functions in one program yields undefined results.
  55 .SH RETURN VALUES
  56 Upon successful completion, these functions return 0. Otherwise, a value of -1 is returned and \fIerrno\fP is set to indicate the error.
  57 .SH ERRORS
  58 The functions will fail if any of the following occur:
  59 .TP 15
  60 .B EINVAL
  61 Either \fIwhich\fP is not one of the ITIMER_* constants above, or one of the timeval structures in \fIvalue\fP contains a bad or too large value.
  62 .TP
  63 .B EFAULT
  64 Bad \fIvalue\fP or \fIovalue\fP address.
  65 .SH SEE ALSO
  66 .BR alarm (2)
  67 .SH AUTHOR
  68 David van Moolenbroek <dcvmoole@cs.vu.nl>