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 February 17, 2023 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 itimerspec *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 42These routines create and manipulate timers in which events are associated 43with a file descriptor, allowing for timer-based events to be used 44in file-descriptor based facilities like 45.Xr poll 2 , 46.Xr port_get 3C 47or 48.Xr epoll_wait 3C . 49The 50.Fn timerfd_create 51function creates a timer with the clock 52type specified by 53.Fa clockid . 54The 55.Sy CLOCK_REALTIME 56and 57.Sy CLOCK_HIGHRES 58clock types, as defined in 59.Xr timer_create 3C , 60are supported by 61.Fn timerfd_create . 62(Note that 63.Sy CLOCK_MONOTONIC 64may be used as an alias for 65.Sy CLOCK_HIGHRES Ns .) 66.Pp 67The 68.Fa flags 69argument specifies additional parameters for the timer instance, and can have 70any of the following values: 71.Bl -hang -width Ds 72.It Sy TFD_CLOEXEC 73.Bd -filled -compact 74Instance will be closed upon an 75.Xr exec 2 ; 76see 77.Xr open 2 Ns 's 78description of 79.Sy O_CLOEXEC . 80.Ed 81.It Sy TFD_NONBLOCK 82.Bd -filled -compact 83Instance will be set to be non-blocking. 84A 85.Xr read 2 86on a 87.Sy timerfd 88instance that has been initialized with 89.Sy TFD_NONBLOCK 90will return 91.Sy EAGAIN 92in lieu of blocking if the 93timer has not expired since the last 94.Fn timerfd_settime 95or successful 96.Fn read . 97.Ed 98.El 99.Pp 100The following operations can be performed upon a 101.Sy timerfd 102instance: 103.Bl -hang -width Ds 104.It Sy read(2) 105.Bd -filled -compact 106Atomically reads and clears the number of timer expirations since the 107last successful 108.Xr read 2 109or 110.Fn timerfd_settime . 111Upon success, 112the number of expirations will be copied into the eight byte buffer 113passed to the system call. 114If there have been no expirations of the timer since the last successful 115.Xr read 2 116or 117.Fn timerfd_sttime , 118.Xr read 2 119will block until at least the next expiration, 120or return 121.Sy EAGAIN 122if the instance was created with 123.Sy TFD_NONBLOCK . 124Note that if multiple threads are blocked in 125.Xr read 2 126for the same timer, only one of them will return upon 127a single timer expiration. 128.Pp 129If the buffer specified to 130.Xr read 2 131is less than 132eight bytes in length, 133.Sy EINVAL 134will be returned. 135.Ed 136.It Sy poll(2), port_get(3C), epoll_wait(3C) 137.Bd -filled -compact 138Provide notification when the timer expires or has expired in the past without 139a more recent 140.Xr read 2 . 141Note that threads being simultaneously 142blocked in 143.Xr read 2 144and 145.Xr poll 2 146(or equivalents) for the same 147timer constitute an application-level race; on a timer expiration, 148the thread blocked in 149.Xr poll 2 150may or may not return depending on how 151it is scheduled with respect to the thread blocked in 152.Xr read 2 . 153.Ed 154.It Sy timerfd_gettime() 155.Bd -filled -compact 156Returns the amount of time until the next timer expiration, with the 157same functional signature and semantics as 158.Xr timer_gettime 3C . 159.Ed 160.It Sy timerfd_settime() 161.Bd -filled -compact 162Sets or disarms the timer, with the 163same functional signature and semantics as 164.Xr timer_settime 3C . 165.Ed 166.El 167.Sh RETURN VALUES 168Upon successful completion, a file descriptor associated with the instance 169is returned. 170Otherwise, 171.Sy -1 172is returned and errno is set to indicate the error. 173.Sh ERRORS 174The 175.Fn timerfd_create 176function will fail if: 177.Bl -tag -width Er 178.It Er EINAL 179The 180.Fa flags 181are invalid. 182.It Er EMFILE 183There are currently 184.Pf { Sy OPEN_MAX Ns } 185file descriptors open in the calling process. 186.It Er EPERM 187The 188.Fa clock_id , 189is 190.Sy CLOCK_HIGHRES 191and the 192.Pf { Sy PRIV_PROC_CLOCK_HIGHRES Ns } 193is 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 privileges 7 , 203.Xr timerfd 7 204