@node getitimer, process
@subheading Syntax

@example
#include <sys/time.h>

int getitimer(int which, struct itimerval *value);
@end example

@subheading Description

This function gets the current value of the interval timer specified by
@var{which} into structure @var{value}.  Variable @var{which} can have
the value of @code{ITIMER_REAL} or @code{ITIMER_PROF}.
@xref{setitimer}, for more details about timers.

Upon return, the @code{it_value} member of @var{value} will hold the
amount of time left until timer expiration, or zero if the timer has
expired or was stopped by a previous call to @code{setitimer}.  The
@code{it_interval} member will hold the interval between two successive
alarms as set by the last call to @code{setitimer} (but note that
interval values less than the system clock granularity are rounded up to
that granularity).  The value returned in @code{it_interval} member is
@emph{not} set to zero when the timer is stopped, it always retains the
interval that was last in use.

@subheading Return Value

Returns 0 on success, -1 on failure (and sets @code{errno}).

@subheading Portability

@portability !ansi, !posix

@c ----------------------------------------------------------------------
@node setitimer, process
@subheading Syntax

@example
#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);
@end example

@subheading Description

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

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

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

A timer is defined by the @code{itimerval} structure.  If the
@code{it_value} member is non-zero it specifies the time to the next
timer expiration.  If @code{it_interval} is non-zero, it specifies the
value with which to reload the timer upon expiration.  Setting
@code{it_value} to zero disables a timer.  Setting @code{it_interval} to
zero causes the timer to stop after the next expiration (assuming that
@code{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 @samp{value->it_interval.tv_usec} will cause the
system clock granularity to be stored and returned by the next call to
@code{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
@code{setitimer}, otherwise intervals smaller than the default PC clock
speed cannot be set with a call to @code{setitimer} due to rounding up
to clock granularity.  To this end, an external variable
@code{__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 @code{-1}, which
causes @code{setitimer} to work with 54926 microsecond granularity that
corresponds to the standard 18.2@dmn{Hz} clock frequency.  The library
never changes the value of @code{__djgpp_clock_tick_interval}.

@subheading Return Value

Returns 0 on success, -1 on failure (and sets @code{errno}).

@subheading Portability

@portability !ansi, !posix

@subheading Bugs

This version uses @code{uclock} (@pxref{uclock}) to determine the time
of expiration.  Under Windows 3.X, this fails because the OS reprograms
the timer.  Under Windows 9X, @code{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 @cite{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 @code{SIGSEGV} or @code{SIGABRT}, since signals were
not supported in a debugged program before DJGPP v2.03.

@subheading Example

@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);
@end example