xref: /freebsd/lib/libsys/timerfd.2 (revision 2f9966ff63d65bd474478888c9088eeae3f9c669)
1.\" SPDX-License-Identifier: BSD-2-Clause
2.\"
3.\" Copyright (c) 2023 Jake Freeland <jfree@FreeBSD.org>
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.Dd May 21, 2023
27.Dt TIMERFD 2
28.Os
29.Sh NAME
30.Nm timerfd ,
31.Nm timerfd_create ,
32.Nm timerfd_gettime ,
33.Nm timerfd_settime
34.Nd timers with file descriptor semantics
35.Sh LIBRARY
36.Lb libc
37.Sh SYNOPSIS
38.In sys/timerfd.h
39.Ft int
40.Fo timerfd_create
41.Fa "int clockid"
42.Fa "int flags"
43.Fc
44.Ft int
45.Fo timerfd_gettime
46.Fa "int fd"
47.Fa "struct itimerspec *curr_value"
48.Fc
49.Ft int
50.Fo timerfd_settime
51.Fa "int fd"
52.Fa "int flags"
53.Fa "const struct itimerspec *new_value"
54.Fa "struct itimerspec *old_value"
55.Fc
56.Sh DESCRIPTION
57The
58.Nm
59system calls operate on timers, identified by special
60.Nm
61file descriptors.
62These calls are analogous to
63.Fn timer_create ,
64.Fn timer_gettime ,
65and
66.Fn timer_settime
67per-process timer functions, but use a
68.Nm
69descriptor in place of
70.Fa timerid .
71.Pp
72All
73.Nm
74descriptors possess traditional file descriptor semantics; they may be passed
75to other processes, preserved across
76.Xr fork 2 ,
77and monitored via
78.Xr kevent 2 ,
79.Xr poll 2 ,
80or
81.Xr select 2 .
82When a
83.Nm
84descriptor is no longer needed, it may be disposed of using
85.Xr close 2 .
86.Bl -tag -width "Fn timerfd_settime"
87.It Fn timerfd_create
88Initialize a
89.Nm
90object and return its file descriptor.
91The
92.Fa clockid
93argument specifies the clock used as a timing base and may be:
94.Pp
95.Bl -tag -width "Dv CLOCK_MONOTONIC" -compact
96.It Dv CLOCK_REALTIME
97Increments as a wall clock should.
98.It Dv CLOCK_MONOTONIC
99Increments monotonically in SI seconds.
100.El
101.Pp
102The
103.Fa flags
104argument may contain the result of
105.Em or Ns 'ing
106the following values:
107.Pp
108.Bl -tag -width "Dv TFD_NONBLOCK" -compact
109.It Dv TFD_CLOEXEC
110The newly generated file descriptor will close-on-exec.
111.It Dv TFD_NONBLOCK
112Do not block on read/write operations.
113.El
114.It Fn timerfd_gettime
115Retrieve the current state of the timer denoted by
116.Fa fd .
117The result is stored in
118.Fa curr_value
119as a
120.Dv struct itimerspec .
121The
122.Fa it_value
123and
124.Fa it_interval
125members of
126.Fa curr_value
127represent the relative time until the next expiration and the interval
128reload value last set by
129.Fn timerfd_settime ,
130respectively.
131.It Fn timerfd_settime
132Update the timer denoted by
133.Fa fd
134with the
135.Dv struct itimerspec
136in
137.Fa new_value .
138The
139.Fa it_value
140member of
141.Fa new_value
142should contain the amount of time before the timer expires, or zero if the
143timer should be disarmed.
144The
145.Fa it_interval
146member should contain the reload time if an interval timer is desired.
147.Pp
148The previous timer state will be stored in
149.Fa old_value
150given
151.Fa old_value
152is not
153.Dv NULL .
154.Pp
155The
156.Fa flags
157argument may contain the result of
158.Em or Ns 'ing
159the following values:
160.Pp
161.Bl -tag -width TFD_TIMER_CANCEL_ON_SET -compact
162.It Dv TFD_TIMER_ABSTIME
163Expiration will occur at the absolute time provided in
164.Fa new_value .
165Normally,
166.Fa new_value
167represents a relative time compared to the timer's
168.Fa clockid
169clock.
170.It Dv TFD_TIMER_CANCEL_ON_SET
171If
172.Fa clockid
173has been set to
174.Dv CLOCK_REALTIME
175and the realtime clock has experienced a discontinuous jump,
176then the timer will be canceled and the next
177.Xr read 2
178will fail with
179.Dv ECANCELED .
180.El
181.El
182.Pp
183File operations have the following semantics:
184.Bl -tag -width ioctl
185.It Xr read 2
186Transfer the number of timer expirations that have occurred since the last
187successful
188.Xr read 2
189or
190.Fn timerfd_settime
191into the output buffer of size
192.Vt uint64_t .
193If the expiration counter is zero,
194.Xr read 2
195blocks until a timer expiration occurs unless
196.Dv TFD_NONBLOCK
197is set, where
198.Dv EAGAIN
199is returned.
200.It Xr poll 2
201The file descriptor is readable when its timer expiration counter is greater
202than zero.
203.It Xr ioctl 2
204.Bl -tag -width FIONREAD
205.It Dv FIOASYNC int
206A non-zero input will set the FASYNC flag.
207A zero input will clear the FASYNC flag.
208.It Dv FIONBIO int
209A non-zero input will set the FNONBLOCK flag.
210A zero input will clear the FNONBLOCK flag.
211.El
212.El
213.Sh RETURN VALUES
214The
215.Fn timerfd_create
216system call creates a
217.Nm
218object and returns its file descriptor.
219If an error occurs, -1 is returned and the global variable
220.Fa errno
221is set to indicate the error.
222.Pp
223The
224.Fn timerfd_gettime
225and
226.Fn timerfd_settime
227system calls return 0 on success.
228If an error occurs, -1 is returned and the global variable
229.Fa errno
230is set to indicate the error.
231.Sh ERRORS
232The
233.Fn timerfd_create
234system call fails if:
235.Bl -tag -width Er
236.It Bq Er EINVAL
237The specified
238.Fa clockid
239is not supported.
240.It Bq Er EINVAL
241The provided
242.Fa flags
243are invalid.
244.It Bq Er EMFILE
245The per-process descriptor table is full.
246.It Bq Er ENFILE
247The system file table is full.
248.It Bq Er ENOMEM
249The kernel failed to allocate enough memory for the timer.
250.El
251.Pp
252Both
253.Fn timerfd_gettime
254and
255.Fn timerfd_settime
256system calls fail if:
257.Bl -tag -width Er
258.It Bq Er EBADF
259The provided
260.Fa fd
261is invalid.
262.It Bq Er EFAULT
263The addresses provided by
264.Fa curr_value ,
265.Fa new_value ,
266or
267.Fa old_value
268are invalid.
269.It Bq Er EINVAL
270The provided
271.Fa fd
272is valid, but was not generated by
273.Fn timerfd_create .
274.El
275.Pp
276The following errors only apply to
277.Fn timerfd_settime :
278.Bl -tag -width Er
279.It Bq Er EINVAL
280The provided
281.Fa flags
282are invalid.
283.It Bq Er EINVAL
284A nanosecond field in the
285.Fa new_value
286argument specified a value less than zero, or greater than or equal to 10^9.
287.It Bq Er ECANCELED
288The timer 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 experienced a discontinuous change without
293being read.
294.El
295.Pp
296A read from a
297.Nm
298object fails if:
299.Bl -tag -width Er
300.It Bq Er EAGAIN
301The timer's expiration counter is zero and the
302.Nm
303object is set for non-blocking I/O.
304.It Bq Er ECANCELED
305The timer was created with the clock ID
306.Dv CLOCK_REALTIME ,
307was configured with the
308.Dv TFD_TIMER_CANCEL_ON_SET
309flag, and the system realtime clock experienced a discontinuous change.
310.It Bq Er EINVAL
311The size of the read buffer is not large enough to hold the
312.Vt uint64_t
313sized timer expiration counter.
314.El
315.Sh SEE ALSO
316.Xr eventfd 2 ,
317.Xr kqueue 2 ,
318.Xr poll 2 ,
319.Xr read 2 ,
320.Xr timer_create 2 ,
321.Xr timer_gettime 2 ,
322.Xr timer_settime 2
323.Sh STANDARDS
324The
325.Nm
326system calls originated from Linux and are non-standard.
327.Sh HISTORY
328.An -nosplit
329The
330.Nm
331facility was originally ported to
332.Fx Ns 's
333Linux compatibility layer by
334.An Dmitry Chagin Aq Mt dchagin@FreeBSD.org
335in
336.Fx 12.0 .
337It was revised and adapted to be native by
338.An Jake Freeland Aq Mt jfree@FreeBSD.org
339in
340.Fx 14.0 .
341