diff options
Diffstat (limited to 'man/man2/timer_settime.2')
| -rw-r--r-- | man/man2/timer_settime.2 | 187 |
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 000000000..1f8589874 --- /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 (date) "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) |