diff options
Diffstat (limited to 'man/man2/timerfd_create.2')
| -rw-r--r-- | man/man2/timerfd_create.2 | 704 |
1 files changed, 704 insertions, 0 deletions
diff --git a/man/man2/timerfd_create.2 b/man/man2/timerfd_create.2 new file mode 100644 index 000000000..23c399c7d --- /dev/null +++ b/man/man2/timerfd_create.2 @@ -0,0 +1,704 @@ +.\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH timerfd_create 2 (date) "Linux man-pages (unreleased)" +.SH NAME +timerfd_create, timerfd_settime, timerfd_gettime \- +timers that notify via file descriptors +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/timerfd.h> +.P +.BI "int timerfd_create(int " clockid ", int " flags ); +.P +.BI "int timerfd_settime(int " fd ", int " flags , +.BI " const struct itimerspec *" new_value , +.BI " struct itimerspec *_Nullable " old_value ); +.BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value ); +.fi +.SH DESCRIPTION +These system calls create and operate on a timer +that delivers timer expiration notifications via a file descriptor. +They provide an alternative to the use of +.BR setitimer (2) +or +.BR timer_create (2), +with the advantage that the file descriptor may be monitored by +.BR select (2), +.BR poll (2), +and +.BR epoll (7). +.P +The use of these three system calls is analogous to the use of +.BR timer_create (2), +.BR timer_settime (2), +and +.BR timer_gettime (2). +(There is no analog of +.BR timer_getoverrun (2), +since that functionality is provided by +.BR read (2), +as described below.) +.\" +.SS timerfd_create() +.BR timerfd_create () +creates a new timer object, +and returns a file descriptor that refers to that timer. +The +.I clockid +argument specifies the clock that is used to mark the progress +of the timer, and must be one of the following: +.TP +.B CLOCK_REALTIME +A settable system-wide real-time clock. +.TP +.B CLOCK_MONOTONIC +A nonsettable monotonically increasing clock that measures time +from some unspecified point in the past that does not change +after system startup. +.TP +.BR CLOCK_BOOTTIME " (Since Linux 3.15)" +.\" commit 4a2378a943f09907fb1ae35c15de917f60289c14 +Like +.BR CLOCK_MONOTONIC , +this is a monotonically increasing clock. +However, whereas the +.B CLOCK_MONOTONIC +clock does not measure the time while a system is suspended, the +.B CLOCK_BOOTTIME +clock does include the time during which the system is suspended. +This is useful for applications that need to be suspend-aware. +.B CLOCK_REALTIME +is not suitable for such applications, since that clock is affected +by discontinuous changes to the system clock. +.TP +.BR CLOCK_REALTIME_ALARM " (since Linux 3.11)" +.\" commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8 +This clock is like +.BR CLOCK_REALTIME , +but will wake the system if it is suspended. +The caller must have the +.B CAP_WAKE_ALARM +capability in order to set a timer against this clock. +.TP +.BR CLOCK_BOOTTIME_ALARM " (since Linux 3.11)" +.\" commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8 +This clock is like +.BR CLOCK_BOOTTIME , +but will wake the system if it is suspended. +The caller must have the +.B CAP_WAKE_ALARM +capability in order to set a timer against this clock. +.P +See +.BR clock_getres (2) +for some further details on the above clocks. +.P +The current value of each of these clocks can be retrieved using +.BR clock_gettime (2). +.P +Starting with Linux 2.6.27, the following values may be bitwise ORed in +.I flags +to change the behavior of +.BR timerfd_create (): +.TP 14 +.B TFD_NONBLOCK +Set the +.B O_NONBLOCK +file status flag on the open file description (see +.BR open (2)) +referred to by the new file descriptor. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B TFD_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.P +In Linux versions up to and including 2.6.26, +.I flags +must be specified as zero. +.SS timerfd_settime() +.BR timerfd_settime () +arms (starts) or disarms (stops) +the timer referred to by the file descriptor +.IR fd . +.P +The +.I new_value +argument specifies the initial expiration and interval for the timer. +The +.I itimerspec +structure used for this argument is described in +.BR itimerspec (3type). +.P +.I new_value.it_value +specifies the initial expiration of the timer, +in seconds and nanoseconds. +Setting either field of +.I new_value.it_value +to a nonzero value arms the timer. +Setting both fields of +.I new_value.it_value +to zero disarms the timer. +.P +Setting one or both fields of +.I new_value.it_interval +to nonzero values specifies the period, in seconds and nanoseconds, +for repeated timer expirations after the initial expiration. +If both fields of +.I new_value.it_interval +are zero, the timer expires just once, at the time specified by +.IR new_value.it_value . +.P +By default, +the initial expiration time specified in +.I new_value +is interpreted relative to the current time +on the timer's clock at the time of the call (i.e., +.I new_value.it_value +specifies a time relative to the current value of the clock specified by +.IR clockid ). +An absolute timeout can be selected via the +.I flags +argument. +.P +The +.I flags +argument is a bit mask that can include the following values: +.TP +.B TFD_TIMER_ABSTIME +Interpret +.I new_value.it_value +as an absolute value on the timer's clock. +The timer will expire when the value of the timer's +clock reaches the value specified in +.IR new_value.it_value . +.TP +.B TFD_TIMER_CANCEL_ON_SET +If this flag is specified along with +.B TFD_TIMER_ABSTIME +and the clock for this timer is +.B CLOCK_REALTIME +or +.BR CLOCK_REALTIME_ALARM , +then mark this timer as cancelable if the real-time clock +undergoes a discontinuous change +.RB ( settimeofday (2), +.BR clock_settime (2), +or similar). +When such changes occur, a current or future +.BR read (2) +from the file descriptor will fail with the error +.BR ECANCELED . +.P +If the +.I old_value +argument is not NULL, then the +.I itimerspec +structure that it points to is used to return the setting of the timer +that was current at the time of the call; +see the description of +.BR timerfd_gettime () +following. +.\" +.SS timerfd_gettime() +.BR timerfd_gettime () +returns, in +.IR curr_value , +an +.I itimerspec +structure that contains the current setting of the timer +referred to by the file descriptor +.IR fd . +.P +The +.I it_value +field returns the amount of time +until the timer will next expire. +If both fields of this structure are zero, +then the timer is currently disarmed. +This field always contains a relative value, regardless of whether the +.B TFD_TIMER_ABSTIME +flag was specified when setting the timer. +.P +The +.I it_interval +field returns the interval of the timer. +If both fields of this structure are zero, +then the timer is set to expire just once, at the time specified by +.IR curr_value.it_value . +.SS Operating on a timer file descriptor +The file descriptor returned by +.BR timerfd_create () +supports the following additional operations: +.TP +.BR read (2) +If the timer has already expired one or more times since +its settings were last modified using +.BR timerfd_settime (), +or since the last successful +.BR read (2), +then the buffer given to +.BR read (2) +returns an unsigned 8-byte integer +.RI ( uint64_t ) +containing the number of expirations that have occurred. +(The returned value is in host byte order\[em]that is, +the native byte order for integers on the host machine.) +.IP +If no timer expirations have occurred at the time of the +.BR read (2), +then the call either blocks until the next timer expiration, +or fails with the error +.B EAGAIN +if the file descriptor has been made nonblocking +(via the use of the +.BR fcntl (2) +.B F_SETFL +operation to set the +.B O_NONBLOCK +flag). +.IP +A +.BR read (2) +fails with the error +.B EINVAL +if the size of the supplied buffer is less than 8 bytes. +.IP +If the associated clock is either +.B CLOCK_REALTIME +or +.BR CLOCK_REALTIME_ALARM , +the timer is absolute +.RB ( TFD_TIMER_ABSTIME ), +and the flag +.B TFD_TIMER_CANCEL_ON_SET +was specified when calling +.BR timerfd_settime (), +then +.BR read (2) +fails with the error +.B ECANCELED +if the real-time clock undergoes a discontinuous change. +(This allows the reading application to discover +such discontinuous changes to the clock.) +.IP +If the associated clock is either +.B CLOCK_REALTIME +or +.BR CLOCK_REALTIME_ALARM , +the timer is absolute +.RB ( TFD_TIMER_ABSTIME ), +and the flag +.B TFD_TIMER_CANCEL_ON_SET +was +.I not +specified when calling +.BR timerfd_settime (), +then a discontinuous negative change to the clock (e.g., +.BR clock_settime (2)) +may cause +.BR read (2) +to unblock, but return a value of 0 (i.e., no bytes read), +if the clock change occurs after the time expired, +but before the +.BR read (2) +on the file descriptor. +.TP +.BR poll (2) +.TQ +.BR select (2) +.TQ +(and similar) +The file descriptor is readable +(the +.BR select (2) +.I readfds +argument; the +.BR poll (2) +.B POLLIN +flag) +if one or more timer expirations have occurred. +.IP +The file descriptor also supports the other file-descriptor +multiplexing APIs: +.BR pselect (2), +.BR ppoll (2), +and +.BR epoll (7). +.TP +.BR ioctl (2) +The following timerfd-specific command is supported: +.RS +.TP +.BR TFD_IOC_SET_TICKS " (since Linux 3.17)" +.\" commit 5442e9fbd7c23172a1c9bc736629cd123a9923f0 +Adjust the number of timer expirations that have occurred. +The argument is a pointer to a nonzero 8-byte integer +.RI ( uint64_t *) +containing the new number of expirations. +Once the number is set, any waiter on the timer is woken up. +The only purpose of this command is to restore the expirations +for the purpose of checkpoint/restore. +This operation is available only if the kernel was configured with the +.B CONFIG_CHECKPOINT_RESTORE +option. +.RE +.TP +.BR close (2) +When the file descriptor is no longer required it should be closed. +When all file descriptors associated with the same timer object +have been closed, +the timer is disarmed and its resources are freed by the kernel. +.\" +.SS fork(2) semantics +After a +.BR fork (2), +the child inherits a copy of the file descriptor created by +.BR timerfd_create (). +The file descriptor refers to the same underlying +timer object as the corresponding file descriptor in the parent, +and +.BR read (2)s +in the child will return information about +expirations of the timer. +.\" +.SS execve(2) semantics +A file descriptor created by +.BR timerfd_create () +is preserved across +.BR execve (2), +and continues to generate timer expirations if the timer was armed. +.SH RETURN VALUE +On success, +.BR timerfd_create () +returns a new file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.P +.BR timerfd_settime () +and +.BR timerfd_gettime () +return 0 on success; +on error they return \-1, and set +.I errno +to indicate the error. +.SH ERRORS +.BR timerfd_create () +can fail with the following errors: +.TP +.B EINVAL +The +.I clockid +is not valid. +.TP +.B EINVAL +.I flags +is invalid; +or, in Linux 2.6.26 or earlier, +.I flags +is nonzero. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been +reached. +.TP +.B ENODEV +Could not mount (internal) anonymous inode device. +.TP +.B ENOMEM +There was insufficient kernel memory to create the timer. +.TP +.B EPERM +.I clockid +was +.B CLOCK_REALTIME_ALARM +or +.B CLOCK_BOOTTIME_ALARM +but the caller did not have the +.B CAP_WAKE_ALARM +capability. +.P +.BR timerfd_settime () +and +.BR timerfd_gettime () +can fail with the following errors: +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EFAULT +.IR new_value , +.IR old_value , +or +.I curr_value +is not a valid pointer. +.TP +.B EINVAL +.I fd +is not a valid timerfd file descriptor. +.P +.BR timerfd_settime () +can also fail with the following errors: +.TP +.B ECANCELED +See NOTES. +.TP +.B EINVAL +.I new_value +is not properly initialized (one of the +.I tv_nsec +falls outside the range zero to 999,999,999). +.TP +.B EINVAL +.\" This case only checked since Linux 2.6.29, and Linux 2.2.2[78].some-stable-version. +.\" In older kernel versions, no check was made for invalid flags. +.I flags +is invalid. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.25, +glibc 2.8. +.SH NOTES +Suppose the following scenario for +.B CLOCK_REALTIME +or +.B CLOCK_REALTIME_ALARM +timer that was created with +.BR timerfd_create (): +.IP (1) 5 +The timer has been started +.RB ( timerfd_settime ()) +with the +.B TFD_TIMER_ABSTIME +and +.B TFD_TIMER_CANCEL_ON_SET +flags; +.IP (2) +A discontinuous change (e.g., +.BR settimeofday (2)) +is subsequently made to the +.B CLOCK_REALTIME +clock; and +.IP (3) +the caller once more calls +.BR timerfd_settime () +to rearm the timer (without first doing a +.BR read (2) +on the file descriptor). +.P +In this case the following occurs: +.IP \[bu] 3 +The +.BR timerfd_settime () +returns \-1 with +.I errno +set to +.BR ECANCELED . +(This enables the caller to know that the previous timer was affected +by a discontinuous change to the clock.) +.IP \[bu] +The timer +.I "is successfully rearmed" +with the settings provided in the second +.BR timerfd_settime () +call. +(This was probably an implementation accident, but won't be fixed now, +in case there are applications that depend on this behaviour.) +.SH BUGS +Currently, +.\" 2.6.29 +.BR timerfd_create () +supports fewer types of clock IDs than +.BR timer_create (2). +.SH EXAMPLES +The following program creates a timer and then monitors its progress. +The program accepts up to three command-line arguments. +The first argument specifies the number of seconds for +the initial expiration of the timer. +The second argument specifies the interval for the timer, in seconds. +The third argument specifies the number of times the program should +allow the timer to expire before terminating. +The second and third command-line arguments are optional. +.P +The following shell session demonstrates the use of the program: +.P +.in +4n +.EX +.RB "$" " a.out 3 1 100" +0.000: timer started +3.000: read: 1; total=1 +4.000: read: 1; total=2 +.BR "\[ha]Z " " # type control\-Z to suspend the program" +[1]+ Stopped ./timerfd3_demo 3 1 100 +.RB "$ " "fg" " # Resume execution after a few seconds" +a.out 3 1 100 +9.660: read: 5; total=7 +10.000: read: 1; total=8 +11.000: read: 1; total=9 +.BR "\[ha]C " " # type control\-C to suspend the program" +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (timerfd_create.c) +.EX +.\" The commented out code here is what we currently need until +.\" the required stuff is in glibc +.\" +.\" +.\"/* Link with \-lrt */ +.\"#define _GNU_SOURCE +.\"#include <sys/syscall.h> +.\"#include <unistd.h> +.\"#include <time.h> +.\"#if defined(__i386__) +.\"#define __NR_timerfd_create 322 +.\"#define __NR_timerfd_settime 325 +.\"#define __NR_timerfd_gettime 326 +.\"#endif +.\" +.\"static int +.\"timerfd_create(int clockid, int flags) +.\"{ +.\" return syscall(__NR_timerfd_create, clockid, flags); +.\"} +.\" +.\"static int +.\"timerfd_settime(int fd, int flags, struct itimerspec *new_value, +.\" struct itimerspec *curr_value) +.\"{ +.\" return syscall(__NR_timerfd_settime, fd, flags, new_value, +.\" curr_value); +.\"} +.\" +.\"static int +.\"timerfd_gettime(int fd, struct itimerspec *curr_value) +.\"{ +.\" return syscall(__NR_timerfd_gettime, fd, curr_value); +.\"} +.\" +.\"#define TFD_TIMER_ABSTIME (1 << 0) +.\" +.\"//////////////////////////////////////////////////////////// +#include <err.h> +#include <inttypes.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/timerfd.h> +#include <time.h> +#include <unistd.h> +\& +static void +print_elapsed_time(void) +{ + int secs, nsecs; + static int first_call = 1; + struct timespec curr; + static struct timespec start; +\& + if (first_call) { + first_call = 0; + if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1) + err(EXIT_FAILURE, "clock_gettime"); + } +\& + if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1) + err(EXIT_FAILURE, "clock_gettime"); +\& + secs = curr.tv_sec \- start.tv_sec; + nsecs = curr.tv_nsec \- start.tv_nsec; + if (nsecs < 0) { + secs\-\-; + nsecs += 1000000000; + } + printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000); +} +\& +int +main(int argc, char *argv[]) +{ + int fd; + ssize_t s; + uint64_t exp, tot_exp, max_exp; + struct timespec now; + struct itimerspec new_value; +\& + if (argc != 2 && argc != 4) { + fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + if (clock_gettime(CLOCK_REALTIME, &now) == \-1) + err(EXIT_FAILURE, "clock_gettime"); +\& + /* Create a CLOCK_REALTIME absolute timer with initial + expiration and interval as specified in command line. */ +\& + new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]); + new_value.it_value.tv_nsec = now.tv_nsec; + if (argc == 2) { + new_value.it_interval.tv_sec = 0; + max_exp = 1; + } else { + new_value.it_interval.tv_sec = atoi(argv[2]); + max_exp = atoi(argv[3]); + } + new_value.it_interval.tv_nsec = 0; +\& + fd = timerfd_create(CLOCK_REALTIME, 0); + if (fd == \-1) + err(EXIT_FAILURE, "timerfd_create"); +\& + if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == \-1) + err(EXIT_FAILURE, "timerfd_settime"); +\& + print_elapsed_time(); + printf("timer started\en"); +\& + for (tot_exp = 0; tot_exp < max_exp;) { + s = read(fd, &exp, sizeof(uint64_t)); + if (s != sizeof(uint64_t)) + err(EXIT_FAILURE, "read"); +\& + tot_exp += exp; + print_elapsed_time(); + printf("read: %" PRIu64 "; total=%" PRIu64 "\en", exp, tot_exp); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR eventfd (2), +.BR poll (2), +.BR read (2), +.BR select (2), +.BR setitimer (2), +.BR signalfd (2), +.BR timer_create (2), +.BR timer_gettime (2), +.BR timer_settime (2), +.BR timespec (3), +.BR epoll (7), +.BR time (7) |