getitimer(S) 6 January 1993 getitimer(S) Name getitimer, setitimer - get and set value of interval timers Syntax cc . . . -lc #include <sys/select.h> #include <sys/itimer.h> getitimer(which, value) int which; struct itimerval *value); setitimer(which, value, ovalue) int which; const struct itimerval *value; struct itimerval *ovalue; Description getitimer - returns the current value of the specified timer setitimer - sets the specified interval timer Each process has three interval timers or ``itimers'' associated with it. At the expiration of a programmed amount of time, an interval timer sig- nals the process and (optionally) automatically reloads itself to re- interrupt the process at programmed intervals. Each itimer counts a dif- ferent type of time, and generates a different signal upon expiration: ITIMERREAL Counts in real (wall-clock) time. A SIGALRM is generated when this itimer expires. alarm(S) is a lower-precision non-reloading ITIMERREAL; a process may have either an alarm, a ITIMERREAL, or neither, but never both simul- taneously. ITIMERVIRT Counts in process-virtual time. It runs only when the process is executing in user mode. A SIGVTALRM is gen- erated when this itimer expires. ITIMERPROF Counts in both process-virtual time and the time when the system is running on behalf of the process. A SIGPROF is generated when this itimer expires. Each itimer counts by decrementing the programmed amount towards zero. The getitimer function returns the current value for the itimer specified by the which parameter in the structure pointed to by the value parame- ter. The setitimer function programs the which itimer to the specified value. If the ovalue pointer is not NULL, the previous setting is returned in the itimerval structure pointed to by ovalue. An itimer is defined by the itimerval structure defined in <sys/itimer.h> and the timeval structure defined in <sys/select.h>: struct itimerval { struct timeval it_interval; /* timer interval */ struct timeval it_value; /* current value */ } struct timeval { long tv_sec; /* seconds */ long tv_usec; /* and microseconds */ } If the itvalue field is nonzero, it indicates the time to the next iti- mer expiration. This field is decremented as time advances. If the itinterval field is nonzero, it specifies a value to be used in reload- ing itvalue when the itimer expires. Setting itvalue to zero disables an itimer. Setting itinterval to zero causes an itimer to be disabled after its next expiration (assuming itvalue is nonzero). The child process does not inherit its parent's itimers after a fork(S); that is, all of the child's itimers are disabled. Interval timer set- tings are not changed by exec(S). Both the itvalue and itinterval fields have microsecond precision. The tvsec field indicates the number of seconds, and tvusec the millionths of a second. A timeval structure is zero only when both tvsec and tvusec are zero. Time values smaller than the resolution of the system's clock are rounded up to this resolution. The system clock resolution is returned by gethz(S) or sysconf(S). Typically, the resolution is ten milliseconds (or ten thousand microseconds). The accuracy of an itimer depends on the system's load; the busier the system, the greater the delay between the generation of the signal and its delivery to the process. Since time values are rounded up, an itimer never expires before it is programmed to expire. On sufficiently busy systems (or with very short itimer inter- vals) a signal may not be delivered before the subsequent one is gen- erated. Since signals don't queue, only one signal will be delivered. The system compensates and does not allow the itimer to drift; that is, each successive signal is generated when it is programmed to occur and is not dependent on whether or when the prior signal was delivered. Four macros are defined in <sys/itimer.h> for manipulating timeval struc- tures: timercopy( const struct timeval source, struct timeval destination ) The timercopy macro copies the structure pointed to by source to that pointed to by destination . timerisset( const struct timeval timvalptr ) The timerisset macro is nonzero (true) if the structure pointed to by timvalptr is nonzero. timerclear( struct timeval timvalptr ) The timerclear macro zeros the structure pointed to by timvalptr . timercmp( const struct timeval leftvptr, const struct timeval rightvptr, operator ) The timercmp macro compares the two intervals defined by the structures pointed to by lefttvptr and righttvptr according to the specified opera- tor (<, ==, !=, or >): (lefttvptr's interval) operator (righttvptr's interval) The <= and >= operators do not work with the timercmp macro. The getitimer() system call fails if one or more of the following is true: [EINVAL] which is not ITIMERREAL, ITIMERVIRT, or ITIMERPROF. [EINVAL] value is NULL. [EFAULT] value points outside the allocated address space of the process. [ENOSYS] Interval timers are either not installed or not supported on this system; a SIGSYS signal is also generated. The setitimer() system call fails if one of more of the following is true, and the current itimer setting is not changed: [EINVAL] which is not ITIMERREAL, ITIMERVIRT, or ITIMERPROF. [EINVAL] value is NULL. [EINVAL] Either value ->itvalue or value ->itinterval is not nor- malized: Either ``tv_sec'' is negative or over ten mil- lion seconds, or ``tv_usec'' is negative or over 999,999 microseconds. [EFAULT] Either ovalue or value points outside the allocated address space of the process. [ENOMEM] There are insufficient system resources to program the itimer. In this case the current which itimer setting is lost, disabling that itimer. [ENOSYS] Interval timers are either not installed or not supported on this system; a SIGSYS signal is also generated. Diagnostics Upon successful completion, a value of zero is returned. Otherwise, a value of -1 is returned, and errno is set to indicate the error. Notes Older systems do not have itimers, and itimers may be deconfigured (not present) in newer systems (by disabling the itimer pseudo-driver). If either the getitimer() or setitimer() system call is attempted when iti- mers are not available, a SIGSYS signal results. The itimer pseudo- driver will not function in older systems. Other vendors' systems may use <sys/time.h> instead of <sys/itimer.h>. Any call to alarm() disables the ITIMERREAL. Any (successful) call to setitimer() disables any alarm. getitimer() returns information about whichever of alarm() and ITIMERREAL. is currently enabled. Older versions of sleep(S) may inadvertently convert a ITIMERREAL into an alarm, which has only seconds precision and is not reloaded when it expires. The ITIMERPROF interval timer is traditionally used by interpreters to statistically profile interpreted code. The generated SIGPROF may inter- rupt in-progress system calls. There is no facility to restart such interrupted system calls, so this itimer may not be very useful for such profiling. See Also alarm(S), exec(S), fork(S), gethz(S), sigaction(S), signal(S), sleep(S), sysconf(S) Standards conformance getitimer and setitimer are not part of any currently supported standard; they were developed at the University of California at Berkeley and are used by permission.