16a72db4aSBryan Cantrill.\" 26a72db4aSBryan Cantrill.\" This file and its contents are supplied under the terms of the 36a72db4aSBryan Cantrill.\" Common Development and Distribution License ("CDDL"), version 1.0. 46a72db4aSBryan Cantrill.\" You may only use this file in accordance with the terms of version 56a72db4aSBryan Cantrill.\" 1.0 of the CDDL. 66a72db4aSBryan Cantrill.\" 76a72db4aSBryan Cantrill.\" A full copy of the text of the CDDL should have accompanied this 86a72db4aSBryan Cantrill.\" source. A copy of the CDDL is also available via the Internet at 96a72db4aSBryan Cantrill.\" http://www.illumos.org/license/CDDL. 106a72db4aSBryan Cantrill.\" 116a72db4aSBryan Cantrill.\" 126a72db4aSBryan Cantrill.\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved. 136a72db4aSBryan Cantrill.\" 14*4a8d6d7cSPeter Tribble.Dd February 17, 2023 156a72db4aSBryan Cantrill.Dt TIMERFD 3C 166a72db4aSBryan Cantrill.Os 176a72db4aSBryan Cantrill.Sh NAME 186a72db4aSBryan Cantrill.Nm timerfd_create , 196a72db4aSBryan Cantrill.Nm timerfd_settime , 206a72db4aSBryan Cantrill.Nm timerfd_gettime 216a72db4aSBryan Cantrill.Nd create and manipulate timers via a file descriptor interface 226a72db4aSBryan Cantrill.Sh SYNOPSIS 236a72db4aSBryan Cantrill.In sys/timerfd.h 246a72db4aSBryan Cantrill.Ft int 256a72db4aSBryan Cantrill.Fo timerfd_create 266a72db4aSBryan Cantrill.Fa "int clockid" 276a72db4aSBryan Cantrill.Fa "int flags" 286a72db4aSBryan Cantrill.Fc 296a72db4aSBryan Cantrill.Ft int 306a72db4aSBryan Cantrill.Fo timerfd_settime 316a72db4aSBryan Cantrill.Fa "int fd" 326a72db4aSBryan Cantrill.Fa "int flags" 336a72db4aSBryan Cantrill.Fa "const struct itimerspec *restrict value" 34*4a8d6d7cSPeter Tribble.Fa "struct itimerspec *restrict ovalue" 356a72db4aSBryan Cantrill.Fc 366a72db4aSBryan Cantrill.Ft int 376a72db4aSBryan Cantrill.Fo timerfd_gettime 386a72db4aSBryan Cantrill.Fa "int fd" 396a72db4aSBryan Cantrill.Fa "struct itimerspec *value" 406a72db4aSBryan Cantrill.Fc 416a72db4aSBryan Cantrill.Sh DESCRIPTION 426a72db4aSBryan CantrillThese routines create and manipulate timers in which events are associated 436a72db4aSBryan Cantrillwith a file descriptor, allowing for timer-based events to be used 446a72db4aSBryan Cantrillin file-descriptor based facilities like 456a72db4aSBryan Cantrill.Xr poll 2 , 466a72db4aSBryan Cantrill.Xr port_get 3C 476a72db4aSBryan Cantrillor 486a72db4aSBryan Cantrill.Xr epoll_wait 3C . 496a72db4aSBryan CantrillThe 506a72db4aSBryan Cantrill.Fn timerfd_create 516a72db4aSBryan Cantrillfunction creates a timer with the clock 526a72db4aSBryan Cantrilltype specified by 536a72db4aSBryan Cantrill.Fa clockid . 546a72db4aSBryan CantrillThe 556a72db4aSBryan Cantrill.Sy CLOCK_REALTIME 566a72db4aSBryan Cantrilland 576a72db4aSBryan Cantrill.Sy CLOCK_HIGHRES 586a72db4aSBryan Cantrillclock types, as defined in 596a72db4aSBryan Cantrill.Xr timer_create 3C , 606a72db4aSBryan Cantrillare supported by 616a72db4aSBryan Cantrill.Fn timerfd_create . 626a72db4aSBryan Cantrill(Note that 636a72db4aSBryan Cantrill.Sy CLOCK_MONOTONIC 646a72db4aSBryan Cantrillmay be used as an alias for 656a72db4aSBryan Cantrill.Sy CLOCK_HIGHRES Ns .) 666a72db4aSBryan Cantrill.Pp 676a72db4aSBryan CantrillThe 686a72db4aSBryan Cantrill.Fa flags 696a72db4aSBryan Cantrillargument specifies additional parameters for the timer instance, and can have 706a72db4aSBryan Cantrillany of the following values: 716a72db4aSBryan Cantrill.Bl -hang -width Ds 726a72db4aSBryan Cantrill.It Sy TFD_CLOEXEC 736a72db4aSBryan Cantrill.Bd -filled -compact 746a72db4aSBryan CantrillInstance will be closed upon an 756a72db4aSBryan Cantrill.Xr exec 2 ; 766a72db4aSBryan Cantrillsee 776a72db4aSBryan Cantrill.Xr open 2 Ns 's 786a72db4aSBryan Cantrilldescription of 796a72db4aSBryan Cantrill.Sy O_CLOEXEC . 806a72db4aSBryan Cantrill.Ed 816a72db4aSBryan Cantrill.It Sy TFD_NONBLOCK 826a72db4aSBryan Cantrill.Bd -filled -compact 8372d3dbb9SYuri PankovInstance will be set to be non-blocking. 8472d3dbb9SYuri PankovA 856a72db4aSBryan Cantrill.Xr read 2 866a72db4aSBryan Cantrillon a 876a72db4aSBryan Cantrill.Sy timerfd 886a72db4aSBryan Cantrillinstance that has been initialized with 896a72db4aSBryan Cantrill.Sy TFD_NONBLOCK 906a72db4aSBryan Cantrillwill return 916a72db4aSBryan Cantrill.Sy EAGAIN 926a72db4aSBryan Cantrillin lieu of blocking if the 936a72db4aSBryan Cantrilltimer has not expired since the last 946a72db4aSBryan Cantrill.Fn timerfd_settime 956a72db4aSBryan Cantrillor successful 966a72db4aSBryan Cantrill.Fn read . 976a72db4aSBryan Cantrill.Ed 986a72db4aSBryan Cantrill.El 996a72db4aSBryan Cantrill.Pp 1006a72db4aSBryan CantrillThe following operations can be performed upon a 1016a72db4aSBryan Cantrill.Sy timerfd 1026a72db4aSBryan Cantrillinstance: 1036a72db4aSBryan Cantrill.Bl -hang -width Ds 1046a72db4aSBryan Cantrill.It Sy read(2) 1056a72db4aSBryan Cantrill.Bd -filled -compact 1066a72db4aSBryan CantrillAtomically reads and clears the number of timer expirations since the 1076a72db4aSBryan Cantrilllast successful 1086a72db4aSBryan Cantrill.Xr read 2 1096a72db4aSBryan Cantrillor 1106a72db4aSBryan Cantrill.Fn timerfd_settime . 1116a72db4aSBryan CantrillUpon success, 1126a72db4aSBryan Cantrillthe number of expirations will be copied into the eight byte buffer 11372d3dbb9SYuri Pankovpassed to the system call. 11472d3dbb9SYuri PankovIf there have been no expirations of the timer since the last successful 1156a72db4aSBryan Cantrill.Xr read 2 1166a72db4aSBryan Cantrillor 1176a72db4aSBryan Cantrill.Fn timerfd_sttime , 1186a72db4aSBryan Cantrill.Xr read 2 1196a72db4aSBryan Cantrillwill block until at least the next expiration, 1206a72db4aSBryan Cantrillor return 1216a72db4aSBryan Cantrill.Sy EAGAIN 1226a72db4aSBryan Cantrillif the instance was created with 1236a72db4aSBryan Cantrill.Sy TFD_NONBLOCK . 1246a72db4aSBryan CantrillNote that if multiple threads are blocked in 1256a72db4aSBryan Cantrill.Xr read 2 1266a72db4aSBryan Cantrillfor the same timer, only one of them will return upon 1276a72db4aSBryan Cantrilla single timer expiration. 1286a72db4aSBryan Cantrill.Pp 1296a72db4aSBryan CantrillIf the buffer specified to 1306a72db4aSBryan Cantrill.Xr read 2 1316a72db4aSBryan Cantrillis less than 1326a72db4aSBryan Cantrilleight bytes in length, 133c71d194aSDillon Amburgey.Sy EINVAL 1346a72db4aSBryan Cantrillwill be returned. 1356a72db4aSBryan Cantrill.Ed 1366a72db4aSBryan Cantrill.It Sy poll(2), port_get(3C), epoll_wait(3C) 1376a72db4aSBryan Cantrill.Bd -filled -compact 1386a72db4aSBryan CantrillProvide notification when the timer expires or has expired in the past without 1396a72db4aSBryan Cantrilla more recent 1406a72db4aSBryan Cantrill.Xr read 2 . 1416a72db4aSBryan CantrillNote that threads being simultaneously 1426a72db4aSBryan Cantrillblocked in 1436a72db4aSBryan Cantrill.Xr read 2 1446a72db4aSBryan Cantrilland 1456a72db4aSBryan Cantrill.Xr poll 2 1466a72db4aSBryan Cantrill(or equivalents) for the same 1476a72db4aSBryan Cantrilltimer constitute an application-level race; on a timer expiration, 1486a72db4aSBryan Cantrillthe thread blocked in 1496a72db4aSBryan Cantrill.Xr poll 2 1506a72db4aSBryan Cantrillmay or may not return depending on how 1516a72db4aSBryan Cantrillit is scheduled with respect to the thread blocked in 1526a72db4aSBryan Cantrill.Xr read 2 . 1536a72db4aSBryan Cantrill.Ed 1546a72db4aSBryan Cantrill.It Sy timerfd_gettime() 1556a72db4aSBryan Cantrill.Bd -filled -compact 1566a72db4aSBryan CantrillReturns the amount of time until the next timer expiration, with the 1576a72db4aSBryan Cantrillsame functional signature and semantics as 1586a72db4aSBryan Cantrill.Xr timer_gettime 3C . 1596a72db4aSBryan Cantrill.Ed 1606a72db4aSBryan Cantrill.It Sy timerfd_settime() 1616a72db4aSBryan Cantrill.Bd -filled -compact 1626a72db4aSBryan CantrillSets or disarms the timer, with the 1636a72db4aSBryan Cantrillsame functional signature and semantics as 1646a72db4aSBryan Cantrill.Xr timer_settime 3C . 1656a72db4aSBryan Cantrill.Ed 1666a72db4aSBryan Cantrill.El 1676a72db4aSBryan Cantrill.Sh RETURN VALUES 168843c398eSCody Peter MelloUpon successful completion, a file descriptor associated with the instance 16972d3dbb9SYuri Pankovis returned. 17072d3dbb9SYuri PankovOtherwise, 1716a72db4aSBryan Cantrill.Sy -1 1726a72db4aSBryan Cantrillis returned and errno is set to indicate the error. 1736a72db4aSBryan Cantrill.Sh ERRORS 1746a72db4aSBryan CantrillThe 1753a005aadSYuri Pankov.Fn timerfd_create 1766a72db4aSBryan Cantrillfunction will fail if: 1776a72db4aSBryan Cantrill.Bl -tag -width Er 1786a72db4aSBryan Cantrill.It Er EINAL 1796a72db4aSBryan CantrillThe 1806a72db4aSBryan Cantrill.Fa flags 1816a72db4aSBryan Cantrillare invalid. 1826a72db4aSBryan Cantrill.It Er EMFILE 1836a72db4aSBryan CantrillThere are currently 1846a72db4aSBryan Cantrill.Pf { Sy OPEN_MAX Ns } 1856a72db4aSBryan Cantrillfile descriptors open in the calling process. 1866a72db4aSBryan Cantrill.It Er EPERM 1876a72db4aSBryan CantrillThe 1886a72db4aSBryan Cantrill.Fa clock_id , 1896a72db4aSBryan Cantrillis 1906a72db4aSBryan Cantrill.Sy CLOCK_HIGHRES 1916a72db4aSBryan Cantrilland the 1926a72db4aSBryan Cantrill.Pf { Sy PRIV_PROC_CLOCK_HIGHRES Ns } 1936a72db4aSBryan Cantrillis not asserted in the effective set of the calling process. 1946a72db4aSBryan Cantrill.El 1956a72db4aSBryan Cantrill.Sh SEE ALSO 1966a72db4aSBryan Cantrill.Xr poll 2 , 1976a72db4aSBryan Cantrill.Xr epoll_wait 3C , 1983a005aadSYuri Pankov.Xr port_get 3C , 1996a72db4aSBryan Cantrill.Xr timer_create 3C , 2006a72db4aSBryan Cantrill.Xr timer_gettime 3C , 2016a72db4aSBryan Cantrill.Xr timer_settime 3C , 202bbf21555SRichard Lowe.Xr privileges 7 , 203bbf21555SRichard Lowe.Xr timerfd 7 204