.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
.\" <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
-.TH TIMER_SETTIME 2 2009-02-16 Linux "Linux Programmer's Manual"
+.\" %%%LICENSE_END
+.\"
+.TH TIMER_SETTIME 2 2017-09-15 Linux "Linux Programmer's Manual"
.SH NAME
timer_settime, timer_gettime \- arm/disarm and fetch
state of POSIX per-process timer
.SH SYNOPSIS
.nf
.B #include <time.h>
-
+.PP
.BI "int timer_settime(timer_t " timerid ", int " flags ,
.BI " const struct itimerspec *" new_value ,
-.BI " struct itimerspec * " old_value );
+.BI " struct itimerspec *" old_value );
.BI "int timer_gettime(timer_t " timerid ", struct itimerspec *" curr_value );
.fi
-
-Link with
-.IR \-lrt .
-.sp
+.PP
+Link with \fI\-lrt\fP.
+.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
-.sp
+.PP
.BR timer_settime (),
.BR timer_gettime ():
-_POSIX_C_SOURCE >= 199309
+_POSIX_C_SOURCE\ >=\ 199309L
.SH DESCRIPTION
.BR timer_settime ()
arms or disarms the timer identified by
.IR timerid .
The
.I new_value
-argument is an
+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 defined as follows:
-
+.PP
.in +4n
-.nf
+.EX
struct timespec {
time_t tv_sec; /* Seconds */
long tv_nsec; /* Nanoseconds */
struct timespec it_interval; /* Timer interval */
struct timespec it_value; /* Initial expiration */
};
-.fi
+.EE
.in
-
+.PP
Each of the substructures of the
.I itimerspec
structure is a
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 ()
-
+.BR timer_create (2).
+.PP
If
.I new_value->it_value
-specifies a non-zero value (i.e., either subfield is non-zero), then
+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.
specifies a zero value
(i.e., both subfields are zero),
then the timer is disarmed.
-
+.PP
The
.I new_value->it_interval
field specifies the period of the timer, in seconds and nanoseconds.
-If this field is non-zero, then each time that an armed timer expires,
+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
+specifies a zero value,
then the timer expires just once, at the time specified by
.IR it_value .
-
+.PP
By default, the initial expiration time specified in
.I new_value->it_value
is interpreted relative to the current time on the timer's
.BR timer_getoverrun (2))
will be set correctly.
.\" By experiment: the overrun count is set correctly, for CLOCK_REALTIME.
-
+.PP
If the value of the
.B CLOCK_REALTIME
clock is adjusted while an absolute timer based on that clock is armed,
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.
-
+.PP
If
.I old_value
-is not NULL, then it returns the previous interval of the timer (in
+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 ).
-
+.PP
.BR timer_gettime ()
-returns the time until next expiration, and the the interval,
+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 ;
+.IR curr_value->it_value ;
this is always a relative value, regardless of whether the
.BR TIMER_ABSTIME
flag was used when arming the timer.
If the value returned in
-.IR curr_value.it_value
+.IR curr_value->it_value
is zero, then the timer is currently disarmed.
The timer interval is returned in
-.IR curr_value.it_interval .
+.IR curr_value->it_interval .
If the value returned in
-.IR curr_value.it_interval
+.IR curr_value->it_interval
is zero, then this is a "one-shot" timer.
.SH RETURN VALUE
On success,
.IR old_value ,
or
.I curr_value
-is not valid a pointer.
+is not a valid pointer.
.TP
.B EINVAL
.I timerid
.SH VERSIONS
These system calls are available since Linux 2.6.
.SH CONFORMING TO
-POSIX.1-2001
+POSIX.1-2001, POSIX.1-2008.
+.SH EXAMPLE
+See
+.BR timer_create (2).
.SH SEE ALSO
.BR timer_create (2),
-.BR timer_settime (2),
.BR timer_getoverrun (2),
.BR time (7)
projects / thirdparty / man-pages.git / blobdiff