1.\" $NetBSD: timerfd.2,v 1.4 2021/09/23 13:59:27 uwe Exp $ 2.\" 3.\" Copyright (c) 2021 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd September 17, 2021 31.Dt TIMERFD 2 32.Os 33.\" 34.\" 35.Sh NAME 36.Nm timerfd , 37.Nm timerfd_create , 38.Nm timerfd_gettime , 39.Nm timerfd_settime 40.Nd create and interact with a timer descriptor 41.\" 42.\" 43.Sh SYNOPSIS 44.In sys/timerfd.h 45.Ft int 46.Fn timerfd_create "clockid_t clockid" "int flags" 47.Ft int 48.Fn timerfd_gettime "int fd" "struct itimerspec *tim" 49.Ft int 50.Fn timerfd_settime "int fd" "int flags" \ 51"const struct itimerspec *tim" "struct itimerspec *otim" 52.\" 53.\" 54.Sh DESCRIPTION 55.Nm 56presents an interface to interval timers associated with a file descriptor. 57These timers are functionally equivalent to per-process timers but are 58associated with a file descriptor, rather than a process. 59Because they are associated with a file descriptor, they may be passed 60to other processes, inherited across a fork, and multiplexed using 61.Xr kevent 2 , 62.Xr poll 2 , 63or 64.Xr select 2 . 65When a 66.Nm 67object is no longer needed, it may be disposed of using 68.Xr close 2 . 69.Pp 70The 71.Fn timerfd_create 72system call creates a 73.Nm 74object using the clock specified in the 75.Fa clockid 76argument. 77Valid values for 78.Fa clockid 79are 80.Dv CLOCK_REALTIME 81and 82.Dv CLOCK_MONOTONIC . 83The following flags define the behavior of the resulting object: 84.Bl -tag -width Dv 85.It Dv TFD_CLOEXEC 86This is an alias for the 87.Dv O_CLOEXEC 88flag; see 89.Xr open 2 90for more information. 91.It Dv TFD_NONBLOCK 92This is an alias for the 93.Dv O_NONBLOCK 94flag; see 95.Xr open 2 96for more information. 97.El 98.Pp 99Each time a 100.Nm 101timer expires, an internal counter is incremented. 102Reads from an 103.Nm 104object return the value of this counter in the caller's buffer as an 105unsigned 64-bit integer and reset the counter to\~0. 106If the value of the 107.Nm 108object's counter is\~0, 109then reads will block, unless the 110.Nm 111object is set for non-blocking I/O. 112.Pp 113Writes to a 114.Nm 115object are not supported. 116.Pp 117The 118.Fn timerfd_settime 119system call sets the next expiration time of the 120.Nm 121object to the 122.Va it_value 123.Po 124see 125.Xr itimerspec 3 126.Pc 127specified in the 128.Fa tim 129argument. 130If the value is\~0, 131the timer is disarmed. 132If the argument 133.Fa otim 134is not 135.Dv NULL 136the old timer settings are returned. 137The following flags may be specified to alter the behavior of the timer: 138.Bl -tag -width "TFD_TIMER_CANCEL_ON_SET" 139.It Dv TFD_TIMER_ABSTIME 140The specified timer value is an absolute time. 141This is equivalent to specifying 142.Dv TIMER_ABSTIME 143to 144.Xr timer_settime 2 . 145Otherwise, the time value is a relative time, equivalent to specifying 146.Dv TIMER_RELTIME 147to 148.Xr timer_settime 2 . 149.It Dv TFD_TIMER_CANCEL_ON_SET 150If the 151.Nm 152object's clock ID is 153.Dv CLOCK_REALTIME , 154then the timer will be cancelled and its file descriptor will become 155immediately readable if the system realtime clock is set using 156.Xr clock_settime 2 157or 158.Xr settimeofday 2 . 159If the 160.Nm 161object's clock ID is not 162.Dv CLOCK_REALTIME 163this flag is ignored. 164.El 165.Pp 166If the 167.Va it_interval 168of the 169.Fa tim 170argument is non-zero, then the timer reloads upon expiration. 171.Pp 172The 173.Fn timerfd_gettime 174system call returns the current settings of the 175.Nm 176object in the 177.Fa tim 178argument. 179.\" 180.\" 181.Sh RETURN VALUES 182The 183.Fn timerfd_create 184system call returns\~\-1 if an error occurs, 185otherwise the return value is a descriptor representing the 186.Nm 187object. 188.Pp 189.Rv -std timerfd_gettime timerfd_settime 190.\" 191.\" 192.Sh ERRORS 193The 194.Fn timerfd 195system call fails if: 196.Bl -tag -width Er 197.It Bq Er EINVAL 198Flags other than 199.Dv TFD_CLOEXEC 200and 201.Dv TFD_NONBLOCK 202are set in the 203.Fa flags 204argument. 205.It Bq Er EINVAL 206The 207.Fa clockid 208argument was something other than 209.Dv CLOCK_REALTIME 210or 211.Dv CLOCK_MONOTONIC . 212.It Bq Er EMFILE 213The per-process descriptor table is full. 214.It Bq Er ENFILE 215The system file table is full. 216.El 217.Pp 218The 219.Fn timerfd_gettime 220system call fails if: 221.Bl -tag -width Er 222.It Bq Er EBADF 223The argument 224.Fa fd 225is not a valid file descriptor. 226.It Bq Er EFAULT 227The 228.Fa tim 229argument points outside the allocated address space. 230.It Bq Er EINVAL 231The argument 232.Fa fd 233does not refer to a 234.Nm timerfd 235object. 236.El 237.Pp 238The 239.Fn timerfd_settime 240system call fails if: 241.Bl -tag -width Er 242.It Bq Er EBADF 243The argument 244.Fa fd 245is not a valid file descriptor. 246.It Bq Er EFAULT 247The 248.Fa tim 249or 250.Fa otim 251arguments point outside the allocated address space. 252.It Bq Er EINVAL 253The argument 254.Fa fd 255does not refer to a 256.Nm timerfd 257object. 258.It Bq Er EINVAL 259Bits other than the defined 260.Dv TFD_TIMER_ABSTIME 261and 262.Dv TFD_TIMER_CANCEL_ON_SET 263bits are set in the 264.Fa flags 265argument. 266.It Bq Er EINVAL 267A nanosecond field in the 268.Fa tim 269argument specified a value less than zero or greater than or equal 270to\~10^9. 271.El 272.Pp 273A read from a 274.Nm 275object fails if: 276.Bl -tag -width Er 277.It Bq Er EAGAIN 278The value of the 279.Nm 280object's expiration counter is 281.Dv 0 282and the 283.Nm 284object is set for non-blocking I/O. 285.It Bq Er ECANCELED 286The 287.Nm 288object was created with the clock ID 289.Dv CLOCK_REALTIME , 290was configured with the 291.Dv TFD_TIMER_CANCEL_ON_SET 292flag, and the system realtime clock was changed with 293.Xr clock_settime 2 294or 295.Xr settimeofday 2 . 296.It Bq Er EINVAL 297The size of the read buffer is less than 8 bytes 298.Pq the size required to hold an unsigned 64-bit integer . 299.El 300.\" 301.\" 302.Sh SEE ALSO 303.Xr clock_settime 2 , 304.Xr close 2 , 305.Xr kevent 2 , 306.Xr open 2 , 307.Xr poll 2 , 308.Xr read 2 , 309.Xr select 2 , 310.Xr settimeofday 2 , 311.Xr timer_create 2 , 312.Xr timer_gettime 2 , 313.Xr timer_settime 2 314.\" 315.\" 316.Sh HISTORY 317The 318.Nm 319interface first appeared in 320.Nx 10 . 321It is compatible with the 322.Nm 323interface that appeared in Linux 2.6.25. 324