7.7.2 The timerfd API

The following bindings are exported by (vicare posix) and reexported by (vicare linux):

make-struct-timespec           struct-timespec?
struct-timespec-tv_sec         struct-timespec-tv_nsec
set-struct-timespec-tv_sec!    set-struct-timespec-tv_nsec!

make-struct-itimerspec         struct-itimerspec?
struct-itimerspec-it_interval  struct-itimerspec-it_value
set-struct-itimerspec-it_interval!
set-struct-itimerspec-it_value!

The following bindings are exported by the (vicare linux) library.

Function: timerfd-create clockid

Function: timerfd-create clockid flags

Interface to the C function timerfd_create(). Create a new timer object and a file descriptor that refers to that timer; if successful return a fixnum representing the file descriptor, else raise an exception.

clockid must be one among: CLOCK_REALTIME, CLOCK_MONOTONIC. flags can be either the fixnum zero or a bitwise OR combination of: TFD_CLOEXEC, TFD_NONBLOCK; when not given: it defaults to the fixnum zero.

Function: timerfd-settime fd flags new

Function: timerfd-settime fd flags new old

Interface to the C function timerfd_settime(). Start or stop the timer referred to by the file descriptor fd. If successful return old or #f when old is not given; if an error occurs raise an exception.

flags can be either the fixnum zero or TFD_TIMER_ABSTIME. new must be a valid instance of struct-itimerspec, which is used to set the timer. The optional old can be #f or a valid instance of struct-itimerspec; when given: it is filled with the old timer specification.

Function: timerfd-gettime fd

Function: timerfd-gettime fd curr

Interface to the C function timerfd_gettime(). Retrieve the current timer specification associated to the file descriptor fd. If successful return curr or a newly built instance of struct-itimerspec; if an error occurs: raise an exception.

The optional curr must be a valid instance of struct-itimerspec, when not given a new instance of this structure type is internally built: it is filled with the current timer specification.

Function: timerfd-read fd

Perform a read() operation on fd, which must be a file descriptor associated to a timer. The function behaves as follows:

• If the operation is successful: return the number of timer expirations occurred since the timer was set or the last successful read().
• if the operation fails with code EWOULDBLOCK: the return value is zero.
• Else an exception is raised.