usr/src/man/man3c/timerfd_create.3c

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved.
  13 .\"
  14 .Dd March 26, 2017
  15 .Dt TIMERFD 3C
  16 .Os
  17 .Sh NAME
  18 .Nm timerfd_create ,
  19 .Nm timerfd_settime ,
  20 .Nm timerfd_gettime
  21 .Nd create and manipulate timers via a file descriptor interface
  22 .Sh SYNOPSIS
  23 .In sys/timerfd.h
  24 .Ft int
  25 .Fo timerfd_create
  26 .Fa "int clockid"
  27 .Fa "int flags"
  28 .Fc
  29 .Ft int
  30 .Fo timerfd_settime
  31 .Fa "int fd"
  32 .Fa "int flags"
  33 .Fa "const struct itimerspec *restrict value"
  34 .Fa "struct itimterspec *restrict ovalue"
  35 .Fc
  36 .Ft int
  37 .Fo timerfd_gettime
  38 .Fa "int fd"
  39 .Fa "struct itimerspec *value"
  40 .Fc
  41 .Sh DESCRIPTION
  42 These routines create and manipulate timers in which events are associated
  43 with a file descriptor, allowing for timer-based events to be used
  44 in file-descriptor based facilities like
  45 .Xr poll 2 ,
  46 .Xr port_get 3C
  47 or
  48 .Xr epoll_wait 3C .
  49 The
  50 .Fn timerfd_create
  51 function creates a timer with the clock
  52 type specified by
  53 .Fa clockid .
  54 The
  55 .Sy CLOCK_REALTIME
  56 and
  57 .Sy CLOCK_HIGHRES
  58 clock types, as defined in
  59 .Xr timer_create 3C ,
  60 are supported by
  61 .Fn timerfd_create .
  62 (Note that
  63 .Sy CLOCK_MONOTONIC
  64 may be used as an alias for
  65 .Sy CLOCK_HIGHRES Ns .)
  66 .Pp
  67 The
  68 .Fa flags
  69 argument specifies additional parameters for the timer instance, and can have
  70 any of the following values:
  71 .Bl -hang -width Ds
  72 .It Sy TFD_CLOEXEC
  73 .Bd -filled -compact
  74 Instance will be closed upon an
  75 .Xr exec 2 ;
  76 see
  77 .Xr open 2 Ns 's
  78 description of
  79 .Sy O_CLOEXEC .
  80 .Ed
  81 .It Sy TFD_NONBLOCK
  82 .Bd -filled -compact
  83 Instance will be set to be non-blocking.
  84 A
  85 .Xr read 2
  86 on a
  87 .Sy timerfd
  88 instance that has been initialized with
  89 .Sy TFD_NONBLOCK
  90 will return
  91 .Sy EAGAIN
  92 in lieu of blocking if the
  93 timer has not expired since the last
  94 .Fn timerfd_settime
  95 or successful
  96 .Fn read .
  97 .Ed
  98 .El
  99 .Pp
 100 The following operations can be performed upon a
 101 .Sy timerfd
 102 instance:
 103 .Bl -hang -width Ds
 104 .It Sy read(2)
 105 .Bd -filled -compact
 106 Atomically reads and clears the number of timer expirations since the
 107 last successful
 108 .Xr read 2
 109 or
 110 .Fn timerfd_settime .
 111 Upon success,
 112 the number of expirations will be copied into the eight byte buffer
 113 passed to the system call.
 114 If there have been no expirations of the timer since the last successful
 115 .Xr read 2
 116 or
 117 .Fn timerfd_sttime ,
 118 .Xr read 2
 119 will block until at least the next expiration,
 120 or return
 121 .Sy EAGAIN
 122 if the instance was created with
 123 .Sy TFD_NONBLOCK .
 124 Note that if multiple threads are blocked in
 125 .Xr read 2
 126 for the same timer, only one of them will return upon
 127 a single timer expiration.
 128 .Pp
 129 If the buffer specified to
 130 .Xr read 2
 131 is less than
 132 eight bytes in length,
 133 .Sy EINVAL
 134 will be returned.
 135 .Ed
 136 .It Sy poll(2), port_get(3C), epoll_wait(3C)
 137 .Bd -filled -compact
 138 Provide notification when the timer expires or has expired in the past without
 139 a more recent
 140 .Xr read 2 .
 141 Note that threads being simultaneously
 142 blocked in
 143 .Xr read 2
 144 and
 145 .Xr poll 2
 146 (or equivalents) for the same
 147 timer constitute an application-level race; on a timer expiration,
 148 the thread blocked in
 149 .Xr poll 2
 150 may or may not return depending on how
 151 it is scheduled with respect to the thread blocked in
 152 .Xr read 2 .
 153 .Ed
 154 .It Sy timerfd_gettime()
 155 .Bd -filled -compact
 156 Returns the amount of time until the next timer expiration, with the
 157 same functional signature and semantics as
 158 .Xr timer_gettime 3C .
 159 .Ed
 160 .It Sy timerfd_settime()
 161 .Bd -filled -compact
 162 Sets or disarms the timer, with the
 163 same functional signature and semantics as
 164 .Xr timer_settime 3C .
 165 .Ed
 166 .El
 167 .Sh RETURN VALUES
 168 Upon successful completion, a file descriptor associated with the instance
 169 is returned.
 170 Otherwise,
 171 .Sy -1
 172 is returned and errno is set to indicate the error.
 173 .Sh ERRORS
 174 The
 175 .Fn timerfd_create
 176 function will fail if:
 177 .Bl -tag -width Er
 178 .It Er EINAL
 179 The
 180 .Fa flags
 181 are invalid.
 182 .It Er EMFILE
 183 There are currently
 184 .Pf { Sy OPEN_MAX Ns }
 185 file descriptors open in the calling process.
 186 .It Er EPERM
 187 The
 188 .Fa clock_id ,
 189 is
 190 .Sy CLOCK_HIGHRES
 191 and the
 192 .Pf { Sy PRIV_PROC_CLOCK_HIGHRES Ns }
 193 is not asserted in the effective set of the calling process.
 194 .El
 195 .Sh SEE ALSO
 196 .Xr poll 2 ,
 197 .Xr epoll_wait 3C ,
 198 .Xr port_get 3C ,
 199 .Xr timer_create 3C ,
 200 .Xr timer_gettime 3C ,
 201 .Xr timer_settime 3C ,
 202 .Xr privileages 5 ,
 203 .Xr timerfd 5