# clock_getres

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           clock_getres, clock_gettime, clock_settime — clock and timer
           functions
    


## SYNOPSIS



           #include <time.h>
    
           int clock_getres(clockid_t _clock_id_ , struct timespec *_res_);
           int clock_gettime(clockid_t _clock_id_ , struct timespec *_tp_);
           int clock_settime(clockid_t _clock_id_ , const struct timespec *_tp_);
    


## DESCRIPTION



           The _clock_getres_() function shall return the resolution of any
           clock. Clock resolutions are implementation-defined and cannot be
           set by a process. If the argument _res_ is not NULL, the resolution
           of the specified clock shall be stored in the location pointed to
           by _res_.  If _res_ is NULL, the clock resolution is not returned. If
           the _time_ argument of _clock_settime_() is not a multiple of _res_ ,
           then the value is truncated to a multiple of _res_.
    
           The _clock_gettime_() function shall return the current value _tp_ for
           the specified clock, _clock_id_.
    
           The _clock_settime_() function shall set the specified clock,
           _clock_id_ , to the value specified by _tp_.  Time values that are
           between two consecutive non-negative integer multiples of the
           resolution of the specified clock shall be truncated down to the
           smaller multiple of the resolution.
    
           A clock may be system-wide (that is, visible to all processes) or
           per-process (measuring time that is meaningful only within a
           process).  All implementations shall support a _clock_id_ of
           CLOCK_REALTIME as defined in _< time.h>_.  This clock represents the
           clock measuring real time for the system.  For this clock, the
           values returned by _clock_gettime_() and specified by
           _clock_settime_() represent the amount of time (in seconds and
           nanoseconds) since the Epoch. An implementation may also support
           additional clocks. The interpretation of time values for these
           clocks is unspecified.
    
           If the value of the CLOCK_REALTIME clock is set via
           _clock_settime_(), the new value of the clock shall be used to
           determine the time of expiration for absolute time services based
           upon the CLOCK_REALTIME clock. This applies to the time at which
           armed absolute timers expire.  If the absolute time requested at
           the invocation of such a time service is before the new value of
           the clock, the time service shall expire immediately as if the
           clock had reached the requested time normally.
    
           Setting the value of the CLOCK_REALTIME clock via _clock_settime_()
           shall have no effect on threads that are blocked waiting for a
           relative time service based upon this clock, including the
           _nanosleep_() function; nor on the expiration of relative timers
           based upon this clock. Consequently, these time services shall
           expire when the requested relative interval elapses, independently
           of the new or old value of the clock.
    
           If the Monotonic Clock option is supported, all implementations
           shall support a _clock_id_ of CLOCK_MONOTONIC defined in _< time.h>_.
           This clock represents the monotonic clock for the system. For this
           clock, the value returned by _clock_gettime_() represents the amount
           of time (in seconds and nanoseconds) since an unspecified point in
           the past (for example, system start-up time, or the Epoch). This
           point does not change after system start-up time. The value of the
           CLOCK_MONOTONIC clock cannot be set via _clock_settime_().  This
           function shall fail if it is invoked with a _clock_id_ argument of
           CLOCK_MONOTONIC.
    
           The effect of setting a clock via _clock_settime_() on armed per-
           process timers associated with a clock other than CLOCK_REALTIME
           is implementation-defined.
    
           If the value of the CLOCK_REALTIME clock is set via
           _clock_settime_(), the new value of the clock shall be used to
           determine the time at which the system shall awaken a thread
           blocked on an absolute _clock_nanosleep_() call based upon the
           CLOCK_REALTIME clock. If the absolute time requested at the
           invocation of such a time service is before the new value of the
           clock, the call shall return immediately as if the clock had
           reached the requested time normally.
    
           Setting the value of the CLOCK_REALTIME clock via _clock_settime_()
           shall have no effect on any thread that is blocked on a relative
           _clock_nanosleep_() call. Consequently, the call shall return when
           the requested relative interval elapses, independently of the new
           or old value of the clock.
    
           Appropriate privileges to set a particular clock are
           implementation-defined.
    
           If _POSIX_CPUTIME is defined, implementations shall support clock
           ID values obtained by invoking _clock_getcpuclockid_(), which
           represent the CPU-time clock of a given process. Implementations
           shall also support the special **clockid_t** value
           CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock of
           the calling process when invoking one of the _clock_*_() or
           _timer_*_() functions. For these clock IDs, the values returned by
           _clock_gettime_() and specified by _clock_settime_() represent the
           amount of execution time of the process associated with the clock.
           Changing the value of a CPU-time clock via _clock_settime_() shall
           have no effect on the behavior of the sporadic server scheduling
           policy (see _Scheduling Policies_).
    
           If _POSIX_THREAD_CPUTIME is defined, implementations shall support
           clock ID values obtained by invoking _pthread_getcpuclockid_(),
           which represent the CPU-time clock of a given thread.
           Implementations shall also support the special **clockid_t** value
           CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock of
           the calling thread when invoking one of the _clock_*_() or _timer_*_()
           functions. For these clock IDs, the values returned by
           _clock_gettime_() and specified by _clock_settime_() shall represent
           the amount of execution time of the thread associated with the
           clock. Changing the value of a CPU-time clock via _clock_settime_()
           shall have no effect on the behavior of the sporadic server
           scheduling policy (see _Scheduling Policies_).
    


## RETURN VALUE



           A return value of 0 shall indicate that the call succeeded. A
           return value of -1 shall indicate that an error occurred, and
           _errno_ shall be set to indicate the error.
    


## ERRORS



           The _clock_getres_(), _clock_gettime_(), and _clock_settime_() functions
           shall fail if:
    
           **EINVAL** The _clock_id_ argument does not specify a known clock.
    
           The _clock_gettime_() function shall fail if:
    
           **EOVERFLOW**
                  The number of seconds will not fit in an object of type
                  **time_t**.
    
           The _clock_settime_() function shall fail if:
    
           **EINVAL** The _tp_ argument to _clock_settime_() is outside the range for
                  the given clock ID.
    
           **EINVAL** The _tp_ argument specified a nanosecond value less than zero
                  or greater than or equal to 1000 million.
    
           **EINVAL** The value of the _clock_id_ argument is CLOCK_MONOTONIC.
    
           The _clock_settime_() function may fail if:
    
           **EPERM** The requesting process does not have appropriate privileges
                  to set the specified clock.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           Note that the absolute value of the monotonic clock is meaningless
           (because its origin is arbitrary), and thus there is no need to
           set it.  Furthermore, realtime applications can rely on the fact
           that the value of this clock is never set and, therefore, that
           time intervals measured with this clock will not be affected by
           calls to _clock_settime_().
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *