mirror of https://github.com/mkerrisk/man-pages
177 lines
4.6 KiB
Groff
177 lines
4.6 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 1993-08-05 "Linux 0.99.11" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
getitimer, setitimer \- get or set value of an interval timer
|
|
.SH SYNOPSIS
|
|
.PD 0
|
|
.HP
|
|
.B #include <sys/time.h>
|
|
.sp
|
|
.HP
|
|
.B int getitimer(int
|
|
.IB which ,
|
|
.B struct itimerval
|
|
.BI * value );
|
|
.HP
|
|
.B int setitimer(int
|
|
.IB which ,
|
|
.B const struct itimerval
|
|
.BI * value ,
|
|
.B struct itimerval
|
|
.BI * ovalue );
|
|
.PD
|
|
.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
|
|
.RS .5i
|
|
.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
|
|
.RE
|
|
.PD
|
|
.LP
|
|
The function
|
|
.B getitimer
|
|
fills the structure indicated by
|
|
.I value
|
|
with the current setting for the timer indicated 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
|
|
.B setitimer
|
|
sets the indicated timer to the value in
|
|
.IR value .
|
|
If
|
|
.I ovalue
|
|
is non-zero, 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.
|
|
(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_VIRT )
|
|
the signal will be delivered immediately when generated. Otherwise the
|
|
delivery will be offset by a small time dependent on the system loading.
|
|
.LP
|
|
.SH "RETURN VALUE"
|
|
On success, zero is returned. On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EFAULT
|
|
.I value
|
|
or
|
|
.I ovalue
|
|
are not valid pointers.
|
|
.TP
|
|
.B EINVAL
|
|
.I which
|
|
is not one of
|
|
.BR ITIMER_REAL ,
|
|
.BR ITIMER_VIRT ,
|
|
or
|
|
.BR ITIMER_PROF .
|
|
.SH "CONFORMING TO"
|
|
POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
|
|
.SH "SEE ALSO"
|
|
.BR gettimeofday (2),
|
|
.BR sigaction (2),
|
|
.BR signal (2)
|
|
.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, timer values are represented in jiffies.
|
|
If a request is made set a timer with a value whose jiffies
|
|
representation exceeds MAX_SEC_IN_JIFFIES
|
|
(defined in
|
|
.IR include/linux/jiffies.h ),
|
|
then the timer is silently truncated to this ceiling value.
|
|
On Linux 2.6 on x86 (where a jiffy is 0.001 seconds),
|
|
this means that the ceiling value for a timer is
|
|
approximately 24.86 days.
|
|
|
|
On certain systems (including x86), the Linux kernel has a bug which will
|
|
produce premature timer expirations of up to one jiffy under some
|
|
circumstances.
|
|
.\" As at June 2005, the above holds in 2.4.x and 2.6.x (e.g., 2.6.12.)
|
|
|
|
POSIX.1 says that
|
|
.B setitimer
|
|
should fail if a
|
|
.I tv_usec
|
|
value is specified that is outside of the range 0 to 999999.
|
|
However, Linux does not give an error, but instead silently
|
|
adjusts the corresponding seconds value for the timer.
|