setitimer

Syntax

#include <sys/time.h> extern long __djgpp_clock_tick_interval; struct timeval { time_t tv_sec; long tv_usec; }; struct itimerval { struct timeval it_interval; /* timer interval */ struct timeval it_value; /* current value */ }; int setitimer(int which, struct itimerval *value, struct itimerval *ovalue);

Description

Each process has two interval timers, ITIMER_REAL and ITIMER_PROF, which raise the signals SIGALRM and SIGPROF, respectively. These are typically used to provide alarm and profiling capabilities.

This function changes the current value of the interval timer specified by which to the values in structure value. The previous value of the timer is returned in ovalue if it is not a NULL pointer. When the timer expires, the appropriate signal is raised.

Please see the documentation for signal (see section signal) for restrictions on signal handlers.

If value is a NULL pointer, setitimer stores the previous timer value in ovalue (if it is non-NULL), like getitimer does, but otherwise does nothing.

A timer is defined by the itimerval structure. If the it_value member is non-zero it specifies the time to the next timer expiration. If it_interval is non-zero, it specifies the value with which to reload the timer upon expiration. Setting it_value to zero disables a timer. Setting it_interval to zero causes the timer to stop after the next expiration (assuming that it_value is non-zero).

Although times can be given with microsecond resolution, the granularity is determined by the timer interrupt frequency. Time values smaller than the system clock granularity will be rounded up to that granularity, before they are used. This means that passing a very small but non-zero value in `value->it_interval.tv_usec' will cause the system clock granularity to be stored and returned by the next call to getitimer. See the example below.

If an application changes the system clock speed by reprogramming the timer chip, it should make the new clock speed known to setitimer, otherwise intervals smaller than the default PC clock speed cannot be set with a call to setitimer due to rounding up to clock granularity. To this end, an external variable __djgpp_clock_tick_interval is provided, which should be set to the number of microseconds between two timer ticks that trigger Interrupt 8. The default value of this variable is -1, which causes setitimer to work with 54926 microsecond granularity that corresponds to the standard 18.2Hz clock frequency. The library never changes the value of __djgpp_clock_tick_interval.

Return Value

Returns 0 on success, -1 on failure (and sets errno).

Portability

ANSI/ISO C	No
POSIX	No

Bugs

This version uses uclock (see section uclock) to determine the time of expiration. Under Windows 3.X, this fails because the OS reprograms the timer. Under Windows 9X, uclock sometimes reports erratic (non-increasing) time values; in these cases the timer might fire at a wrong time.

A misfeature of Windows 9X prevents the timer tick interrupt from being delivered to programs that are in the background (i.e. don't have the focus), even though the program itself might continue to run, if you uncheck the Background: Always suspend property in the Property Sheets. Therefore, the timers will not work in background programs on Windows 9X.

Also, debuggers compiled with DJGPP v2.02 and earlier cannot cope with timers and report SIGSEGV or SIGABRT, since signals were not supported in a debugged program before DJGPP v2.03.

Example

/* Find out what is the system clock granularity. */ struct itimerval tv; tv.it_interval.tv_sec = 0; tv.it_interval.tv_usec = 1; tv.it_value.tv_sec = 0; tv.it_value.tv_usec = 0; setitimer (ITIMER_REAL, &tv, 0); setitimer (ITIMER_REAL, 0, &tv); printf ("System clock granularity: %ld microseconds.\n", tv.it_interval.tv_usec);