NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | WARNINGS | NOTES
#include <sys/time.h>int getitimer(int which, struct itimerval *value);
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:
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 multithreaded 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 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 reliable 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 discontinued 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.
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).
Decrements both in process virtual time and when the 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 multithreaded programs
see the WARNINGS section below).
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 SIGPROF
signal is delivered to the lwp. The SIGPROF
signal
is delivered before any other signal except SIGKILL
. 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 multithreaded programs see the WARNINGS section below).
Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno is set to indicate the error.
The getitimer() and setitimer() functions will fail if:
The specified number of seconds is greater than 100,000,000, the number of microseconds is greater than or equal to 1,000,000, or the which argument is unrecognized.
The setitimer() function will fail if:
Either an unbound Solaris thread or a POSIX thread in local scheduling scope with a flag other than ITIMER_REAL called setitimer().
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
MT-Level | MT-Safe |
alarm(2), sigprocmask(2), gettimeofday(3C), pthread_attr_setscope(3THR), pthread_sigmask(3THR), sleep(3C), sysconf(3C), attributes(5), standards(5)
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.
The microseconds field should not be equal to or greater than one second.
The setitimer() function is independent of the alarm() function.
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.
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | WARNINGS | NOTES