lib/libc/sys/timerfd.2

   1 .\" SPDX-License-Identifier: BSD-2-Clause
   2 .\"
   3 .\" Copyright (c) 2023 Jake Freeland <jfree@FreeBSD.org>
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd May 21, 2023
  27 .Dt TIMERFD 2
  28 .Os
  29 .Sh NAME
  30 .Nm timerfd ,
  31 .Nm timerfd_create ,
  32 .Nm timerfd_gettime ,
  33 .Nm timerfd_settime
  34 .Nd timers with file descriptor semantics
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In sys/timerfd.h
  39 .Ft int
  40 .Fo timerfd_create
  41 .Fa "int clockid"
  42 .Fa "int flags"
  43 .Fc
  44 .Ft int
  45 .Fo timerfd_gettime
  46 .Fa "int fd"
  47 .Fa "struct itimerspec *curr_value"
  48 .Fc
  49 .Ft int
  50 .Fo timerfd_settime
  51 .Fa "int fd"
  52 .Fa "int flags"
  53 .Fa "const struct itimerspec *new_value"
  54 .Fa "struct itimerspec *old_value"
  55 .Fc
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 system calls operate on timers, identified by special
  60 .Nm
  61 file descriptors.
  62 These calls are analogous to
  63 .Fn timer_create ,
  64 .Fn timer_gettime ,
  65 and
  66 .Fn timer_settime
  67 per-process timer functions, but use a
  68 .Nm
  69 descriptor in place of
  70 .Fa timerid .
  71 .Pp
  72 All
  73 .Nm
  74 descriptors possess traditional file descriptor semantics; they may be passed
  75 to other processes, preserved across
  76 .Xr fork 2 ,
  77 and monitored via
  78 .Xr kevent 2 ,
  79 .Xr poll 2 ,
  80 or
  81 .Xr select 2 .
  82 When a
  83 .Nm
  84 descriptor is no longer needed, it may be disposed of using
  85 .Xr close 2 .
  86 .Bl -tag -width "Fn timerfd_settime"
  87 .It Fn timerfd_create
  88 Initialize a
  89 .Nm
  90 object and return its file descriptor.
  91 The
  92 .Fa clockid
  93 argument specifies the clock used as a timing base and may be:
  94 .Pp
  95 .Bl -tag -width "Dv CLOCK_MONOTONIC" -compact
  96 .It Dv CLOCK_REALTIME
  97 Increments as a wall clock should.
  98 .It Dv CLOCK_MONOTONIC
  99 Increments monotonically in SI seconds.
 100 .El
 101 .Pp
 102 The
 103 .Fa flags
 104 argument may contain the result of
 105 .Em or Ns 'ing
 106 the following values:
 107 .Pp
 108 .Bl -tag -width "Dv TFD_NONBLOCK" -compact
 109 .It Dv TFD_CLOEXEC
 110 The newly generated file descriptor will close-on-exec.
 111 .It Dv TFD_NONBLOCK
 112 Do not block on read/write operations.
 113 .El
 114 .It Fn timerfd_gettime
 115 Retrieve the current state of the timer denoted by
 116 .Fa fd .
 117 The result is stored in
 118 .Fa curr_value
 119 as a
 120 .Dv struct itimerspec .
 121 The
 122 .Fa it_value
 123 and
 124 .Fa it_interval
 125 members of
 126 .Fa curr_value
 127 represent the relative time until the next expiration and the interval
 128 reload value last set by
 129 .Fn timerfd_settime ,
 130 respectively.
 131 .It Fn timerfd_settime
 132 Update the timer denoted by
 133 .Fa fd
 134 with the
 135 .Dv struct itimerspec
 136 in
 137 .Fa new_value .
 138 The
 139 .Fa it_value
 140 member of
 141 .Fa new_value
 142 should contain the amount of time before the timer expires, or zero if the
 143 timer should be disarmed.
 144 The
 145 .Fa it_interval
 146 member should contain the reload time if an interval timer is desired.
 147 .Pp
 148 The previous timer state will be stored in
 149 .Fa old_value
 150 given
 151 .Fa old_value
 152 is not
 153 .Dv NULL .
 154 .Pp
 155 The
 156 .Fa flags
 157 argument may contain the result of
 158 .Em or Ns 'ing
 159 the following values:
 160 .Pp
 161 .Bl -tag -width TFD_TIMER_CANCEL_ON_SET -compact
 162 .It Dv TFD_TIMER_ABSTIME
 163 Expiration will occur at the absolute time provided in
 164 .Fa new_value .
 165 Normally,
 166 .Fa new_value
 167 represents a relative time compared to the timer's
 168 .Fa clockid
 169 clock.
 170 .It Dv TFD_TIMER_CANCEL_ON_SET
 171 If
 172 .Fa clockid
 173 has been set to
 174 .Dv CLOCK_REALTIME
 175 and the realtime clock has experienced a discontinuous jump,
 176 then the timer will be canceled and the next
 177 .Xr read 2
 178 will fail with
 179 .Dv ECANCELED .
 180 .El
 181 .El
 182 .Pp
 183 File operations have the following semantics:
 184 .Bl -tag -width ioctl
 185 .It Xr read 2
 186 Transfer the number of timer expirations that have occurred since the last
 187 successful
 188 .Xr read 2
 189 or
 190 .Fn timerfd_settime
 191 into the output buffer of size
 192 .Vt uint64_t .
 193 If the expiration counter is zero,
 194 .Xr read 2
 195 blocks until a timer expiration occurs unless
 196 .Dv TFD_NONBLOCK
 197 is set, where
 198 .Dv EAGAIN
 199 is returned.
 200 .It Xr poll 2
 201 The file descriptor is readable when its timer expiration counter is greater
 202 than zero.
 203 .It Xr ioctl 2
 204 .Bl -tag -width FIONREAD
 205 .It Dv FIOASYNC int
 206 A non-zero input will set the FASYNC flag.
 207 A zero input will clear the FASYNC flag.
 208 .It Dv FIONBIO int
 209 A non-zero input will set the FNONBLOCK flag.
 210 A zero input will clear the FNONBLOCK flag.
 211 .El
 212 .El
 213 .Sh RETURN VALUES
 214 The
 215 .Fn timerfd_create
 216 system call creates a
 217 .Nm
 218 object and returns its file descriptor.
 219 If an error occurs, -1 is returned and the global variable
 220 .Fa errno
 221 is set to indicate the error.
 222 .Pp
 223 The
 224 .Fn timerfd_gettime
 225 and
 226 .Fn timerfd_settime
 227 system calls return 0 on success.
 228 If an error occurs, -1 is returned and the global variable
 229 .Fa errno
 230 is set to indicate the error.
 231 .Sh ERRORS
 232 The
 233 .Fn timerfd_create
 234 system call fails if:
 235 .Bl -tag -width Er
 236 .It Bq Er EINVAL
 237 The specified
 238 .Fa clockid
 239 is not supported.
 240 .It Bq Er EINVAL
 241 The provided
 242 .Fa flags
 243 are invalid.
 244 .It Bq Er EMFILE
 245 The per-process descriptor table is full.
 246 .It Bq Er ENFILE
 247 The system file table is full.
 248 .It Bq Er ENOMEM
 249 The kernel failed to allocate enough memory for the timer.
 250 .El
 251 .Pp
 252 Both
 253 .Fn timerfd_gettime
 254 and
 255 .Fn timerfd_settime
 256 system calls fail if:
 257 .Bl -tag -width Er
 258 .It Bq Er EBADF
 259 The provided
 260 .Fa fd
 261 is invalid.
 262 .It Bq Er EFAULT
 263 The addresses provided by
 264 .Fa curr_value ,
 265 .Fa new_value ,
 266 or
 267 .Fa old_value
 268 are invalid.
 269 .It Bq Er EINVAL
 270 The provided
 271 .Fa fd
 272 is valid, but was not generated by
 273 .Fn timerfd_create .
 274 .El
 275 .Pp
 276 The following errors only apply to
 277 .Fn timerfd_settime :
 278 .Bl -tag -width Er
 279 .It Bq Er EINVAL
 280 The provided
 281 .Fa flags
 282 are invalid.
 283 .It Bq Er EINVAL
 284 A nanosecond field in the
 285 .Fa new_value
 286 argument specified a value less than zero, or greater than or equal to 10^9.
 287 .It Bq Er ECANCELED
 288 The timer was created with the clock ID
 289 .Dv CLOCK_REALTIME ,
 290 was configured with the
 291 .Dv TFD_TIMER_CANCEL_ON_SET
 292 flag, and the system realtime clock experienced a discontinuous change without
 293 being read.
 294 .El
 295 .Pp
 296 A read from a
 297 .Nm
 298 object fails if:
 299 .Bl -tag -width Er
 300 .It Bq Er EAGAIN
 301 The timer's expiration counter is zero and the
 302 .Nm
 303 object is is set for non-blocking I/O.
 304 .It Bq Er ECANCELED
 305 The timer was created with the clock ID
 306 .Dv CLOCK_REALTIME ,
 307 was configured with the
 308 .Dv TFD_TIMER_CANCEL_ON_SET
 309 flag, and the system realtime clock experienced a discontinuous change.
 310 .It Bq Er EINVAL
 311 The size of the read buffer is not large enough to hold the
 312 .Vt uint64_t
 313 sized timer expiration counter.
 314 .El
 315 .Sh SEE ALSO
 316 .Xr eventfd 2 ,
 317 .Xr kqueue 2 ,
 318 .Xr poll 2 ,
 319 .Xr read 2 ,
 320 .Xr timer_create 2 ,
 321 .Xr timer_gettime 2 ,
 322 .Xr timer_settime 2
 323 .Sh STANDARDS
 324 The
 325 .Nm
 326 system calls originated from Linux and are non-standard.
 327 .Sh HISTORY
 328 .An -nosplit
 329 The
 330 .Nm
 331 facility was originally ported to
 332 .Fx Ns 's
 333 Linux compatibility layer by
 334 .An Dmitry Chagin Aq Mt dchagin@FreeBSD.org
 335 in
 336 .Fx 12.0 .
 337 It was revised and adapted to be native by
 338 .An Jake Freeland Aq Mt jfree@FreeBSD.org
 339 in
 340 .Fx 14.0 .