Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 187 insertions, 0 deletions

diff --git a/man/man2/timer_settime.2 b/man/man2/timer_settime.2
new file mode 100644
index 0000000..ce043ff
--- /dev/null
+++ b/man/man2/timer_settime.2
@@ -0,0 +1,187 @@
+.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH timer_settime 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+timer_settime, timer_gettime \- arm/disarm and fetch
+state of POSIX per-process timer
+.SH LIBRARY
+Real-time library
+.RI ( librt ", " \-lrt )
+.SH SYNOPSIS
+.nf
+.B  #include <time.h>
+.P
+.BI "int timer_gettime(timer_t " timerid ", struct itimerspec *" curr_value );
+.BI "int timer_settime(timer_t " timerid ", int " flags ,
+.BI "                  const struct itimerspec *restrict " new_value ,
+.BI "                  struct itimerspec *_Nullable restrict " old_value );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR timer_settime (),
+.BR timer_gettime ():
+.nf
+    _POSIX_C_SOURCE >= 199309L
+.fi
+.SH DESCRIPTION
+.BR timer_settime ()
+arms or disarms the timer identified by
+.IR timerid .
+The
+.I new_value
+argument is pointer to an
+.I itimerspec
+structure that specifies the new initial value and
+the new interval for the timer.
+The
+.I itimerspec
+structure is described in
+.BR itimerspec (3type).
+.P
+Each of the substructures of the
+.I itimerspec
+structure is a
+.BR timespec (3)
+structure that allows a time value to be specified
+in seconds and nanoseconds.
+These time values are measured according to the clock
+that was specified when the timer was created by
+.BR timer_create (2).
+.P
+If
+.I new_value\->it_value
+specifies a nonzero value (i.e., either subfield is nonzero), then
+.BR timer_settime ()
+arms (starts) the timer,
+setting it to initially expire at the given time.
+(If the timer was already armed,
+then the previous settings are overwritten.)
+If
+.I new_value\->it_value
+specifies a zero value
+(i.e., both subfields are zero),
+then the timer is disarmed.
+.P
+The
+.I new_value\->it_interval
+field specifies the period of the timer, in seconds and nanoseconds.
+If this field is nonzero, then each time that an armed timer expires,
+the timer is reloaded from the value specified in
+.IR new_value\->it_interval .
+If
+.I new_value\->it_interval
+specifies a zero value,
+then the timer expires just once, at the time specified by
+.IR it_value .
+.P
+By default, the initial expiration time specified in
+.I new_value\->it_value
+is interpreted relative to the current time on the timer's
+clock at the time of the call.
+This can be modified by specifying
+.B TIMER_ABSTIME
+in
+.IR flags ,
+in which case
+.I new_value\->it_value
+is interpreted as an absolute value as measured on the timer's clock;
+that is, the timer will expire when the clock value reaches the
+value specified by
+.IR new_value\->it_value .
+If the specified absolute time has already passed,
+then the timer expires immediately,
+and the overrun count (see
+.BR timer_getoverrun (2))
+will be set correctly.
+.\" By experiment: the overrun count is set correctly, for CLOCK_REALTIME.
+.P
+If the value of the
+.B CLOCK_REALTIME
+clock is adjusted while an absolute timer based on that clock is armed,
+then the expiration of the timer will be appropriately adjusted.
+Adjustments to the
+.B CLOCK_REALTIME
+clock have no effect on relative timers based on that clock.
+.\" Similar remarks might apply with respect to process and thread CPU time
+.\" clocks, but these clocks are not currently (2.6.28) settable on Linux.
+.P
+If
+.I old_value
+is not NULL, then it points to a buffer
+that is used to return the previous interval of the timer (in
+.IR old_value\->it_interval )
+and the amount of time until the timer
+would previously have next expired (in
+.IR old_value\->it_value ).
+.P
+.BR timer_gettime ()
+returns the time until next expiration, and the interval,
+for the timer specified by
+.IR timerid ,
+in the buffer pointed to by
+.IR curr_value .
+The time remaining until the next timer expiration is returned in
+.IR curr_value\->it_value ;
+this is always a relative value, regardless of whether the
+.B TIMER_ABSTIME
+flag was used when arming the timer.
+If the value returned in
+.I curr_value\->it_value
+is zero, then the timer is currently disarmed.
+The timer interval is returned in
+.IR curr_value\->it_interval .
+If the value returned in
+.I curr_value\->it_interval
+is zero, then this is a "one-shot" timer.
+.SH RETURN VALUE
+On success,
+.BR timer_settime ()
+and
+.BR timer_gettime ()
+return 0.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+These functions may fail with the following errors:
+.TP
+.B EFAULT
+.IR new_value ,
+.IR old_value ,
+or
+.I curr_value
+is not a valid pointer.
+.TP
+.B EINVAL
+.I timerid
+is invalid.
+.\" FIXME . eventually: invalid value in flags
+.P
+.BR timer_settime ()
+may fail with the following errors:
+.TP
+.B EINVAL
+.I new_value.it_value
+is negative; or
+.I new_value.it_value.tv_nsec
+is negative or greater than 999,999,999.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+Linux 2.6.
+POSIX.1-2001.
+.SH EXAMPLES
+See
+.BR timer_create (2).
+.SH SEE ALSO
+.BR timer_create (2),
+.BR timer_getoverrun (2),
+.BR timespec (3),
+.BR time (7)