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