man2/timer_settime.2

   1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH timer_settime 2 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 timer_settime, timer_gettime \- arm/disarm and fetch
   9 state of POSIX per-process timer
  10 .SH LIBRARY
  11 Real-time library
  12 .RI ( librt ", " \-lrt )
  13 .SH SYNOPSIS
  14 .nf
  15 .B  #include <time.h>
  16 .P
  17 .BI "int timer_gettime(timer_t " timerid ", struct itimerspec *" curr_value );
  18 .BI "int timer_settime(timer_t " timerid ", int " flags ,
  19 .BI "                  const struct itimerspec *restrict " new_value ,
  20 .BI "                  struct itimerspec *_Nullable restrict " old_value );
  21 .fi
  22 .P
  23 .RS -4
  24 Feature Test Macro Requirements for glibc (see
  25 .BR feature_test_macros (7)):
  26 .RE
  27 .P
  28 .BR timer_settime (),
  29 .BR timer_gettime ():
  30 .nf
  31     _POSIX_C_SOURCE >= 199309L
  32 .fi
  33 .SH DESCRIPTION
  34 .BR timer_settime ()
  35 arms or disarms the timer identified by
  36 .IR timerid .
  37 The
  38 .I new_value
  39 argument is pointer to an
  40 .I itimerspec
  41 structure that specifies the new initial value and
  42 the new interval for the timer.
  43 The
  44 .I itimerspec
  45 structure is described in
  46 .BR itimerspec (3type).
  47 .P
  48 Each of the substructures of the
  49 .I itimerspec
  50 structure is a
  51 .BR timespec (3)
  52 structure that allows a time value to be specified
  53 in seconds and nanoseconds.
  54 These time values are measured according to the clock
  55 that was specified when the timer was created by
  56 .BR timer_create (2).
  57 .P
  58 If
  59 .I new_value\->it_value
  60 specifies a nonzero value (i.e., either subfield is nonzero), then
  61 .BR timer_settime ()
  62 arms (starts) the timer,
  63 setting it to initially expire at the given time.
  64 (If the timer was already armed,
  65 then the previous settings are overwritten.)
  66 If
  67 .I new_value\->it_value
  68 specifies a zero value
  69 (i.e., both subfields are zero),
  70 then the timer is disarmed.
  71 .P
  72 The
  73 .I new_value\->it_interval
  74 field specifies the period of the timer, in seconds and nanoseconds.
  75 If this field is nonzero, then each time that an armed timer expires,
  76 the timer is reloaded from the value specified in
  77 .IR new_value\->it_interval .
  78 If
  79 .I new_value\->it_interval
  80 specifies a zero value,
  81 then the timer expires just once, at the time specified by
  82 .IR it_value .
  83 .P
  84 By default, the initial expiration time specified in
  85 .I new_value\->it_value
  86 is interpreted relative to the current time on the timer's
  87 clock at the time of the call.
  88 This can be modified by specifying
  89 .B TIMER_ABSTIME
  90 in
  91 .IR flags ,
  92 in which case
  93 .I new_value\->it_value
  94 is interpreted as an absolute value as measured on the timer's clock;
  95 that is, the timer will expire when the clock value reaches the
  96 value specified by
  97 .IR new_value\->it_value .
  98 If the specified absolute time has already passed,
  99 then the timer expires immediately,
 100 and the overrun count (see
 101 .BR timer_getoverrun (2))
 102 will be set correctly.
 103 .\" By experiment: the overrun count is set correctly, for CLOCK_REALTIME.
 104 .P
 105 If the value of the
 106 .B CLOCK_REALTIME
 107 clock is adjusted while an absolute timer based on that clock is armed,
 108 then the expiration of the timer will be appropriately adjusted.
 109 Adjustments to the
 110 .B CLOCK_REALTIME
 111 clock have no effect on relative timers based on that clock.
 112 .\" Similar remarks might apply with respect to process and thread CPU time
 113 .\" clocks, but these clocks are not currently (2.6.28) settable on Linux.
 114 .P
 115 If
 116 .I old_value
 117 is not NULL, then it points to a buffer
 118 that is used to return the previous interval of the timer (in
 119 .IR old_value\->it_interval )
 120 and the amount of time until the timer
 121 would previously have next expired (in
 122 .IR old_value\->it_value ).
 123 .P
 124 .BR timer_gettime ()
 125 returns the time until next expiration, and the interval,
 126 for the timer specified by
 127 .IR timerid ,
 128 in the buffer pointed to by
 129 .IR curr_value .
 130 The time remaining until the next timer expiration is returned in
 131 .IR curr_value\->it_value ;
 132 this is always a relative value, regardless of whether the
 133 .B TIMER_ABSTIME
 134 flag was used when arming the timer.
 135 If the value returned in
 136 .I curr_value\->it_value
 137 is zero, then the timer is currently disarmed.
 138 The timer interval is returned in
 139 .IR curr_value\->it_interval .
 140 If the value returned in
 141 .I curr_value\->it_interval
 142 is zero, then this is a "one-shot" timer.
 143 .SH RETURN VALUE
 144 On success,
 145 .BR timer_settime ()
 146 and
 147 .BR timer_gettime ()
 148 return 0.
 149 On error, \-1 is returned, and
 150 .I errno
 151 is set to indicate the error.
 152 .SH ERRORS
 153 These functions may fail with the following errors:
 154 .TP
 155 .B EFAULT
 156 .IR new_value ,
 157 .IR old_value ,
 158 or
 159 .I curr_value
 160 is not a valid pointer.
 161 .TP
 162 .B EINVAL
 163 .I timerid
 164 is invalid.
 165 .\" FIXME . eventually: invalid value in flags
 166 .P
 167 .BR timer_settime ()
 168 may fail with the following errors:
 169 .TP
 170 .B EINVAL
 171 .I new_value.it_value
 172 is negative; or
 173 .I new_value.it_value.tv_nsec
 174 is negative or greater than 999,999,999.
 175 .SH STANDARDS
 176 POSIX.1-2008.
 177 .SH HISTORY
 178 Linux 2.6.
 179 POSIX.1-2001.
 180 .SH EXAMPLES
 181 See
 182 .BR timer_create (2).
 183 .SH SEE ALSO
 184 .BR timer_create (2),
 185 .BR timer_getoverrun (2),
 186 .BR timespec (3),
 187 .BR time (7)