getitimer(2)                                               getitimer(2)

  getitimer()

  NAME

    getitimer(), setitimer() - get and set value of interval timer

  SYNOPSIS

    #include 

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

  DESCRIPTION

    The getitimer(2) call stores the current value of the which timer into the
    structure pointed to by value. The setitimer(2) call sets the timer
    indicated by which to the value stored in the structure value. The
    previous value of the timer is stored in ovalue, if ovalue is not NULL.

    The which argument specifies one of three types of timers (defined in
    ):

    ITIMER_REAL
        The real-time timer decrements in real time. When this timer expires,
        a SIGALRM signal is delivered to the process.

    ITIMER_VIRTUAL
        The virtual timer decrements in process virtual (user) time that is,
        only when the process is executing. When it expires, a SIGVTALRM
        signal is delivered to the process.

    ITIMER_PROF
        The profile timer decrements in process virtual (user) time and also
        when the system is running on behalf of the process. Each time this
        timer expires, a SIGPROF signal is delivered to the process. This
        timer is intended for use by interpreters, for statistically profiling
        the execution of interpreted programs.

    The itimerval structure defines a timer value:

    struct itimerval {
       struct timeval it_interval;
       struct timeval it_value;
    };

    The timeval structure is:

    struct timeval {
       time_t tv_sec;
       long tv_usec;
    };

    If the value of it_value is non-zero, it is a time until the next timer
    expiration. If the value is zero, then getitimer(2) disables a timer when
    it is called, regardless of the value of it_interval.

    If the value of it_interval is non-zero, it is an interval value which
    will be placed in it_value after the timer expires. If the value is zero,
    then the timer is disabled after the next time it expires.

    The value must be in canonical form: the number of microseconds (tv_usec)
    must be less than 1,000,000 (a million) and neither the number of seconds
    (tv_sec) or microseconds (tv_usec) can be negative integers.

    Three traditional macros are also defined in  for setting and
    testing timer values.
    timerclear()
        sets a timer value to zero.
    timerisset()
        tests whether a timer value is zero.
    timercmp()
        compares two timer values. Warning: do not use inequality operators
        (<= or >=) with this macro.)

  RETURN VALUE

    These functions return 0 on success and -1 if an error occurred.

  ERRORS

    The getitimer(2) and setitimer(2) calls can fail for the following
    reasons:

    [EINTR]
        The system call was interrupted.

    [EINVAL]
        The which argument is unknown.

    [ENOMEM]
        The system could not allocate space for maintaining the timer.

    [ENOSYS]
        The INTERIX subsystem on the machine is an earlier version than 2.2.
        (Versions before 2.2 did not support getitimer(2) or setitimer(2).)

    The setitimer(2) call can also fail because:

    [EINVAL]
        The value argument is not in canonical form.

  SEE ALSO

    alarm(2)

    sleep(2)

  USAGE NOTES

    All of these functions are thread safe.

    None of these functions are async-signal safe.