SunOS man pages : getitimer (2)
System Calls getitimer(2)
NAME
getitimer, setitimer - get or set value of interval timer
SYNOPSIS
#include <sys/time.h>
int getitimer(int which, struct itimerval *value);
int setitimer(int which, const struct itimerval *value,
struct itimerval *ovalue);
DESCRIPTION
The system provides each process with four interval timers,
defined in sys/time.h. The getitimer() function stores the
current value of the timer specified by which into the
structure pointed to by value. The setitimer() function call
sets the value of the timer specified by which to the value
specified in the structure pointed to by value, and if
ovalue is not NULL, stores the previous value of the timer
in the structure pointed to by ovalue.
A timer value is defined by the itimerval structure (see
gettimeofday(3C)) for the definition of timeval), which
includes the following members:
struct timeval it_interval; /* timer interval */
struct timeval it_value; /* current value */
The it_value member indicates the time to the next timer
expiration. The it_interval member specifies a value to be
used in reloading it_value when the timer expires. Setting
it_value to 0 disables a timer, regardless of the value of
it_interval. Setting it_interval to 0 disables a timer after
its next expiration (assuming it_value is non-zero).
Time values smaller than the resolution of the system clock
are rounded up to the resolution of the system clock, except
for ITIMER_REALPROF, whose values are rounded up to the
resolution of the profiling clock. The four timers are as
follows:
ITIMER_REAL
Decrements in real time. A SIGALRM signal is
delivered when this timer expires.
In the current and previous releases, when
setitimer(ITIMER_REAL, ...) is called in a mul-
tithreaded process linked with -lthread (Solaris
threads) or -lpthread (POSIX threads; see standards(5)
), the resulting SIGALRM is sent to the bound
thread that called setitimer(); setitimer() has a
SunOS 5.8 Last change: 28 Dec 1996 1
System Calls getitimer(2)
per-thread semantic when called from a bound thread.
This semantic will become obsolete in a future
release. The semantic will move to a per-process
semantic, with the resulting SIGALRM being sent to the
process. The SIGALRM so generated is not maskable on
this bound thread by any signal masking function,
pthread_sigmask(3THR), thr_sigsetmask(3THR), or sigprocmask(2)
. This is a bug that will not be fixed,
since the per-thread semantic will be discontinued in
the next release.
Also, calling this routine from an unbound thread is
not guaranteed to work as in the case of bound
threads. The resulting SIGALRM may be sent to some
other thread (see alarm(2)). This is a bug and will
not be fixed since the per-thread semantic is going to
be discontinued.
Calling setitimer(ITIMER_REAL, ...) from a process
linked with -lpthread (POSIX threads) has the same
behavior as Solaris threads described above, where a
Solaris bound thread is the same as a POSIX thread in
system scheduling scope and a Solaris unbound thread
is the same as a POSIX thread in local scheduling
scope.
Hence, for multithreaded (Solaris or POSIX) programs
in the current and previous releases, the only reli-
able way to use the ITIMER_REAL flag is to call it
from a bound thread which does not mask SIGALRM and to
expect the SIGALRM to be delivered to this bound
thread.
The current working of this flag is not being improved
since some applications might depend on the current
(slightly broken) semantic. When this semantic is dis-
continued in the future, it will be replaced with a
per-process semantic, i.e. using this flag from any
thread, bound or unbound, will result in the SIGALRM
being sent to the process.
New MT applications should not use this flag, and
should use alarm(2) instead.
ITIMER_VIRTUAL
Decrements in process virtual time. It runs only when
the process is executing. A SIGVTALRM signal is
delivered when it expires. (For multithreaded programs
see the WARNINGS section below).
ITIMER_PROF
Decrements both in process virtual time and when the
SunOS 5.8 Last change: 28 Dec 1996 2
System Calls getitimer(2)
system is running on behalf of the process. It is
designed to be used by interpreters in statistically
profiling the execution of interpreted programs. Each
time the ITIMER_PROF timer expires, the SIGPROF signal
is delivered. Because this signal may interrupt in-
progress functions, programs using this timer must be
prepared to restart interrupted functions. (For mul-
tithreaded programs see the WARNINGS section below).
ITIMER_REALPROF
Decrements in real time. It is designed to be used for
real-time profiling of multithreaded programs. Each
time the ITIMER_REALPROF timer expires, one counter in
a set of counters maintained by the system for each
lightweight process (lwp) is incremented. The counter
corresponds to the state of the lwp at the time of the
timer tick. All lwps executing in user mode when the
timer expires are interrupted into system mode. When
each lwp resumes execution in user mode, if any of the
elements in its set of counters are non-zero, the SIG-
PROF signal is delivered to the lwp. The SIGPROF sig-
nal is delivered before any other signal except SIG-
KILL. This signal does not interrupt any in-progress
function. A siginfo structure, defined in
<sys/siginfo.h>, is associated with the delivery of
the SIGPROF signal, and includes the following
members:
si_tstamp; /* high resolution timestamp */
si_syscall; /* current syscall */
si_nsysarg; /* number of syscall arguments */
si_sysarg[]; /* actual syscall arguments */
si_fault; /* last fault type */
si_faddr; /* last fault address */
si_mstate[]; /* ticks in each microstate */
The enumeration of microstates (indices into
si_mstate) is defined in <sys/msacct.h>. (For mul-
tithreaded programs see the WARNINGS section below).
RETURN VALUES
Upon successful completion, 0 is returned. Otherwise, -1 is
returned and errno is set to indicate the error.
ERRORS
The getitimer() and setitimer() functions will fail if:
EINVAL
The specified number of seconds is greater than
100,000,000, the number of microseconds is greater
SunOS 5.8 Last change: 28 Dec 1996 3
System Calls getitimer(2)
than or equal to 1,000,000, or the which argument is
unrecognized.
The setitimer() function will fail if:
EACCES
Either an unbound Solaris thread or a POSIX thread in
local scheduling scope with a flag other than
ITIMER_REAL called setitimer().
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
alarm(2), sigprocmask(2), gettimeofday(3C),
pthread_attr_setscope(3THR), pthread_sigmask(3THR),
sleep(3C), sysconf(3C), attributes(5), standards(5)
WARNINGS
All flags to setitimer() other than ITIMER_REAL behave as
documented only with "bound" threads. Their ability to mask
the signal works only with bound threads. If the call is
made using one of these flags from an unbound thread, the
system call returns -1 and sets errno to EACCES.
These behaviors are the same for bound or unbound POSIX
threads. A POSIX thread with system-wide scope, created by
the call
pthread_attr_setscope(&attr, PTHREAD_SCOPE_SYSTEM);
is equivalent to a Solaris bound thread. A POSIX thread with
local process scope, created by the call
pthread_attr_setscope(&attr, PTHREAD_SCOPE_PROCESS);
is equivalent to a Solaris unbound thread.
NOTES
The microseconds field should not be equal to or greater
than one second.
SunOS 5.8 Last change: 28 Dec 1996 4
System Calls getitimer(2)
The setitimer() function is independent of the alarm() func-
tion.
Do not use setitimer(ITIMER_REAL) with the sleep() routine.
A sleep(3C) call wipes out knowledge of the user signal
handler for SIGALRM.
The ITIMER_PROF and ITIMER_REALPROF timers deliver the same
signal and have different semantics. They cannot be used
together.
The granularity of the resolution of alarm time is
platform-dependent.
SunOS 5.8 Last change: 28 Dec 1996 5
|
 |
|
|
