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 Feb 23, 2105
  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.  A
  84 .Xr read 2
  85 on a
  86 .Sy timerfd
  87 instance that has been initialized with
  88 .Sy TFD_NONBLOCK
  89 will return
  90 .Sy EAGAIN
  91 in lieu of blocking if the
  92 timer has not expired since the last
  93 .Fn timerfd_settime
  94 or successful
  95 .Fn read .
  96 .Ed
  97 .El
  98 .Pp
  99 The following operations can be performed upon a
 100 .Sy timerfd
 101 instance:
 102 .Bl -hang -width Ds
 103 .It Sy read(2)
 104 .Bd -filled -compact
 105 Atomically reads and clears the number of timer expirations since the
 106 last successful
 107 .Xr read 2
 108 or
 109 .Fn timerfd_settime .
 110 Upon success,
 111 the number of expirations will be copied into the eight byte buffer
 112 passed to the system call. If there have been no expirations of the
 113 timer since the last successful
 114 .Xr read 2
 115 or
 116 .Fn timerfd_sttime ,
 117 .Xr read 2
 118 will block until at least the next expiration,
 119 or return
 120 .Sy EAGAIN
 121 if the instance was created with
 122 .Sy TFD_NONBLOCK .
 123 Note that if multiple threads are blocked in
 124 .Xr read 2
 125 for the same timer, only one of them will return upon
 126 a single timer expiration.
 127 .Pp
 128 If the buffer specified to
 129 .Xr read 2
 130 is less than
 131 eight bytes in length,
 132 .Sy EINAVL
 133 will be returned.
 134 .Ed
 135 .It Sy poll(2), port_get(3C), epoll_wait(3C)
 136 .Bd -filled -compact
 137 Provide notification when the timer expires or has expired in the past without
 138 a more recent
 139 .Xr read 2 .
 140 Note that threads being simultaneously
 141 blocked in
 142 .Xr read 2
 143 and
 144 .Xr poll 2
 145 (or equivalents) for the same
 146 timer constitute an application-level race; on a timer expiration,
 147 the thread blocked in
 148 .Xr poll 2
 149 may or may not return depending on how
 150 it is scheduled with respect to the thread blocked in
 151 .Xr read 2 .
 152 .Ed
 153 .It Sy timerfd_gettime()
 154 .Bd -filled -compact
 155 Returns the amount of time until the next timer expiration, with the
 156 same functional signature and semantics as
 157 .Xr timer_gettime 3C .
 158 .Ed
 159 .It Sy timerfd_settime()
 160 .Bd -filled -compact
 161 Sets or disarms the timer, with the
 162 same functional signature and semantics as
 163 .Xr timer_settime 3C .
 164 .Ed
 165 .El
 166 .Sh RETURN VALUES
 167 Upon succesful completion, a file descriptor associated with the instance
 168 is returned. Otherwise,
 169 .Sy -1
 170 is returned and errno is set to indicate the error.
 171 .Sh ERRORS
 172 The
 173 .Fn timerfd_create
 174 function will fail if:
 175 .Bl -tag -width Er
 176 .It Er EINAL
 177 The
 178 .Fa flags
 179 are invalid.
 180 .It Er EMFILE
 181 There are currently
 182 .Pf { Sy OPEN_MAX Ns }
 183 file descriptors open in the calling process.
 184 .It Er EPERM
 185 The
 186 .Fa clock_id ,
 187 is
 188 .Sy CLOCK_HIGHRES
 189 and the
 190 .Pf { Sy PRIV_PROC_CLOCK_HIGHRES Ns }
 191 is not asserted in the effective set of the calling process.
 192 .El
 193 .Sh SEE ALSO
 194 .Xr poll 2 ,
 195 .Xr epoll_wait 3C ,
 196 .Xr port_get 3C ,
 197 .Xr timer_create 3C ,
 198 .Xr timer_gettime 3C ,
 199 .Xr timer_settime 3C ,
 200 .Xr privileages 5 ,
 201 .Xr timerfd 5