summaryrefslogtreecommitdiffstats
path: root/man2/timerfd_create.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/timerfd_create.2')
-rw-r--r--man2/timerfd_create.2704
1 files changed, 0 insertions, 704 deletions
diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
deleted file mode 100644
index 1d6a0d2..0000000
--- a/man2/timerfd_create.2
+++ /dev/null
@@ -1,704 +0,0 @@
-.\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" SPDX-License-Identifier: GPL-2.0-or-later
-.\"
-.TH timerfd_create 2 2023-10-31 "Linux man-pages 6.7"
-.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)