setitimer(2) - NetBSD Manual Pages

GETITIMER(2)              NetBSD System Calls Manual              GETITIMER(2)


NAME

     getitimer, setitimer -- get/set value of interval timer


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <sys/time.h>

     int
     getitimer(int which, struct itimerval *value);

     int
     setitimer(int which, const struct itimerval * restrict value,
         struct itimerval * restrict ovalue);


DESCRIPTION

     The system provides each process with multiple interval timers, defined
     in <sys/time.h>.  The getitimer() call returns the current value for the
     timer specified in which in the structure at value.  The setitimer() call
     sets a timer to the specified value, returning the previous value of the
     timer if ovalue is not NULL.

     A timer value is defined by the itimerval structure:

           struct itimerval {
                   struct  timeval it_interval;    /* timer interval */
                   struct  timeval it_value;       /* current value */
           };

     If it_value is non-zero, it indicates the time to the next timer expira-
     tion.  If it_interval is non-zero, it specifies a value to be used in
     reloading it_value when the timer expires.  Setting it_value to 0 dis-
     ables a timer.  Setting it_interval to 0 causes a timer to be disabled
     after its next expiration (assuming it_value is non-zero).

     The which parameter specifies the type of the timer:

           ITIMER_REAL        timer decrements in real time.  This timer is
                              affected by adjtime(2) and settimeofday(2).  A
                              SIGALRM signal is delivered when this timer
                              expires.

           ITIMER_VIRTUAL     timer decrements in process virtual time.  It
                              runs only when the process is executing.  A
                              SIGVTALRM signal is delivered when it expires.

           ITIMER_PROF        timer decrements both in process virtual time
                              and when the system is running on behalf of the
                              process.  It is designed to be used by inter-
                              preters 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 system calls, programs using this
                              timer must be prepared to restart interrupted
                              system calls.

           ITIMER_MONOTONIC   timer decrements in monotonic time.  This timer
                              is not affected by adjtime(2) and
                              settimeofday(2).  A SIGALRM signal is delivered
                              when this timer expires.
     Note that:

           ·   Time values smaller than the resolution of the system clock are
               rounded up to this resolution (typically 10 milliseconds).

           ·   The interaction between setitimer() and alarm(3) or sleep(3) is
               unspecified by the specification.


RETURN VALUES

     If the calls succeed, a value of 0 is returned.  If an error occurs, the
     value -1 is returned, and a more precise error code is placed in the
     global variable errno.


ERRORS

     Both functions may fail if:

     [EFAULT]           The value parameter specified a bad address.

     [EINVAL]           The which parameter was not a known timer type, or the
                        value parameter specified a time that was too large to
                        be handled.


SEE ALSO

     gettimeofday(2), select(2), sigaction(2), itimerval(3), timeradd(3)


STANDARDS

     The functions conform to IEEE Std 1003.1-2001 (``POSIX.1'').  The later
     IEEE Std 1003.1-2008 (``POSIX.1'') revision however marked both as obso-
     lescent, recommending the use of timer_gettime(2) and timer_settime(2)
     instead.


HISTORY

     The getitimer() function call appeared in 4.2BSD.  The ITIMER_MONOTONIC
     functionality appeared in NetBSD 6.0.

NetBSD 9.2                      April 28, 2019                      NetBSD 9.2