mirror of https://github.com/mkerrisk/man-pages
226 lines
5.8 KiB
Groff
226 lines
5.8 KiB
Groff
.\" Copyright 7/93 by Darren Senn <sinster@scintilla.santa-clara.ca.us>
|
|
.\" Based on a similar page Copyright 1992 by Rick Faith
|
|
.\" May be freely distributed
|
|
.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
|
|
.\" 2005-04-06 mtk, Matthias Lang <matthias@corelatus.se>
|
|
.\" Noted MAX_SEC_IN_JIFFIES ceiling
|
|
.TH GETITIMER 2 2009-03-15 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
getitimer, setitimer \- get or set value of an interval timer
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/time.h>
|
|
.sp
|
|
.BI "int getitimer(int " which ", struct itimerval *" curr_value );
|
|
.br
|
|
.BI "int setitimer(int " which ", const struct itimerval *" new_value ,
|
|
.BI " struct itimerval *" old_value );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The system provides each process with three interval timers,
|
|
each decrementing in a distinct time domain.
|
|
When any timer expires, a signal is sent to the
|
|
process, and the timer (potentially) restarts.
|
|
.TP 1.5i
|
|
.B ITIMER_REAL
|
|
decrements in real time, and delivers
|
|
.B SIGALRM
|
|
upon expiration.
|
|
.TP
|
|
.B ITIMER_VIRTUAL
|
|
decrements only when the process is executing, and delivers
|
|
.B SIGVTALRM
|
|
upon expiration.
|
|
.TP
|
|
.B ITIMER_PROF
|
|
decrements both when the process executes and when the system is executing
|
|
on behalf of the process.
|
|
Coupled with
|
|
.BR ITIMER_VIRTUAL ,
|
|
this timer is usually used to profile the time spent by the
|
|
application in user and kernel space.
|
|
.B SIGPROF
|
|
is delivered upon expiration.
|
|
.LP
|
|
Timer values are defined by the following structures:
|
|
.PD 0
|
|
.in +4n
|
|
.nf
|
|
|
|
struct itimerval {
|
|
struct timeval it_interval; /* next value */
|
|
struct timeval it_value; /* current value */
|
|
};
|
|
|
|
struct timeval {
|
|
long tv_sec; /* seconds */
|
|
long tv_usec; /* microseconds */
|
|
};
|
|
.fi
|
|
.in
|
|
.PD
|
|
.LP
|
|
The function
|
|
.BR getitimer ()
|
|
fills the structure pointed to by
|
|
.I curr_value
|
|
with the current setting for the timer specified by
|
|
.I which
|
|
(one of
|
|
.BR ITIMER_REAL ,
|
|
.BR ITIMER_VIRTUAL ,
|
|
or
|
|
.BR ITIMER_PROF ).
|
|
The element
|
|
.I it_value
|
|
is set to the amount of time remaining on the timer, or zero if the timer
|
|
is disabled.
|
|
Similarly,
|
|
.I it_interval
|
|
is set to the reset value.
|
|
|
|
The function
|
|
.BR setitimer ()
|
|
sets the specified timer to the value in
|
|
.IR new_value .
|
|
If
|
|
.I old_value
|
|
is non-NULL, the old value of the timer is stored there.
|
|
.LP
|
|
Timers decrement from
|
|
.I it_value
|
|
to zero, generate a signal, and reset to
|
|
.IR it_interval .
|
|
A timer which is set to zero
|
|
.RI ( it_value
|
|
is zero or the timer expires and
|
|
.I it_interval
|
|
is zero) stops.
|
|
.LP
|
|
Both
|
|
.I tv_sec
|
|
and
|
|
.I tv_usec
|
|
are significant in determining the duration of a timer.
|
|
.LP
|
|
Timers will never expire before the requested time,
|
|
but may expire some (short) time afterwards, which depends
|
|
on the system timer resolution and on the system load; see
|
|
.BR time (7).
|
|
(But see BUGS below.)
|
|
Upon expiration, a signal will be generated and the timer reset.
|
|
If the timer expires while the process is active (always true for
|
|
.BR ITIMER_VIRTUAL )
|
|
the signal will be delivered immediately when generated.
|
|
Otherwise the
|
|
delivery will be offset by a small time dependent on the system loading.
|
|
.SH "RETURN VALUE"
|
|
On success, zero is returned.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EFAULT
|
|
.IR new_value ,
|
|
.IR old_value ,
|
|
or
|
|
.I curr_value
|
|
is not valid a pointer.
|
|
.TP
|
|
.B EINVAL
|
|
.I which
|
|
is not one of
|
|
.BR ITIMER_REAL ,
|
|
.BR ITIMER_VIRTUAL ,
|
|
or
|
|
.BR ITIMER_PROF ;
|
|
or (since Linux 2.6.22) one of the
|
|
.I tv_usec
|
|
fields in the structure pointed to by
|
|
.I new_value
|
|
contains a value outside the range 0 to 999999.
|
|
.SH "CONFORMING TO"
|
|
POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
|
|
POSIX.1-2008 marks
|
|
.BR getitimer ()
|
|
and
|
|
.BR setitimer ()
|
|
obsolete, recommending the use of the POSIX timers API
|
|
.RB ( timer_gettime (2),
|
|
.BR timer_settime (2),
|
|
etc.) instead.
|
|
.SH NOTES
|
|
A child created via
|
|
.BR fork (2)
|
|
does not inherit its parent's interval timers.
|
|
Interval timers are preserved across an
|
|
.BR execve (2).
|
|
|
|
POSIX.1 leaves the
|
|
interaction between
|
|
.BR setitimer()
|
|
and the three interfaces
|
|
.BR alarm (2),
|
|
.BR sleep (3),
|
|
and
|
|
.BR usleep (3)
|
|
unspecified.
|
|
.SH BUGS
|
|
The generation and delivery of a signal are distinct, and
|
|
only one instance of each of the signals listed above may be pending
|
|
for a process.
|
|
Under very heavy loading, an
|
|
.B ITIMER_REAL
|
|
timer may expire before the signal from a previous expiration
|
|
has been delivered.
|
|
The second signal in such an event will be lost.
|
|
|
|
On Linux kernels before 2.6.16, timer values are represented in jiffies.
|
|
If a request is made set a timer with a value whose jiffies
|
|
representation exceeds
|
|
.B MAX_SEC_IN_JIFFIES
|
|
(defined in
|
|
.IR include/linux/jiffies.h ),
|
|
then the timer is silently truncated to this ceiling value.
|
|
On Linux/i386 (where, since Linux 2.6.13,
|
|
the default jiffy is 0.004 seconds),
|
|
this means that the ceiling value for a timer is
|
|
approximately 99.42 days.
|
|
Since Linux 2.6.16,
|
|
the kernel uses a different internal representation for times,
|
|
and this ceiling is removed.
|
|
|
|
On certain systems (including i386),
|
|
Linux kernels before version 2.6.12 have a bug which will produce
|
|
premature timer expirations of up to one jiffy under some circumstances.
|
|
This bug is fixed in kernel 2.6.12.
|
|
.\" 4 Jul 2005: It looks like this bug may remain in 2.4.x.
|
|
.\" http://lkml.org/lkml/2005/7/1/165
|
|
|
|
POSIX.1-2001 says that
|
|
.BR setitimer ()
|
|
should fail if a
|
|
.I tv_usec
|
|
value is specified that is outside of the range 0 to 999999.
|
|
However, in kernels up to and including 2.6.21,
|
|
Linux does not give an error, but instead silently
|
|
adjusts the corresponding seconds value for the timer.
|
|
From kernel 2.6.22 onwards,
|
|
this nonconformance has been repaired:
|
|
an improper
|
|
.I tv_usec
|
|
value results in an
|
|
.B EINVAL
|
|
error.
|
|
.\" Bugzilla report 25 Apr 2006:
|
|
.\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
|
|
.\" "setitimer() should reject noncanonical arguments"
|
|
.SH "SEE ALSO"
|
|
.BR gettimeofday (2),
|
|
.BR sigaction (2),
|
|
.BR signal (2),
|
|
.BR timer_create (2),
|
|
.BR timerfd_create (2),
|
|
.BR time (7)
|