CLOCK_GETRES(3)            POSIX Programmer's Manual           CLOCK_GETRES(3)



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


NNAAMMEE
       clock_getres, clock_gettime, clock_settime -- clock and timer functions

SSYYNNOOPPSSIISS
       #include <time.h>

       int clock_getres(clockid_t _c_l_o_c_k___i_d, struct timespec *_r_e_s);
       int clock_gettime(clockid_t _c_l_o_c_k___i_d, struct timespec *_t_p);
       int clock_settime(clockid_t _c_l_o_c_k___i_d, const struct timespec *_t_p);

DDEESSCCRRIIPPTTIIOONN
       The _c_l_o_c_k___g_e_t_r_e_s() function shall return the resolution of any clock.
       Clock resolutions are implementation-defined and cannot be set by a
       process. If the argument _r_e_s is not NULL, the resolution of the
       specified clock shall be stored in the location pointed to by _r_e_s.  If
       _r_e_s is NULL, the clock resolution is not returned. If the _t_i_m_e argument
       of _c_l_o_c_k___s_e_t_t_i_m_e() is not a multiple of _r_e_s, then the value is
       truncated to a multiple of _r_e_s.

       The _c_l_o_c_k___g_e_t_t_i_m_e() function shall return the current value _t_p for the
       specified clock, _c_l_o_c_k___i_d.

       The _c_l_o_c_k___s_e_t_t_i_m_e() function shall set the specified clock, _c_l_o_c_k___i_d,
       to the value specified by _t_p.  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 _c_l_o_c_k___i_d of CLOCK_REALTIME as defined
       in _<_t_i_m_e_._h_>.  This clock represents the clock measuring real time for
       the system.  For this clock, the values returned by _c_l_o_c_k___g_e_t_t_i_m_e() and
       specified by _c_l_o_c_k___s_e_t_t_i_m_e() 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 _c_l_o_c_k___s_e_t_t_i_m_e(),
       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 _c_l_o_c_k___s_e_t_t_i_m_e() shall
       have no effect on threads that are blocked waiting for a relative time
       service based upon this clock, including the _n_a_n_o_s_l_e_e_p() 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 _c_l_o_c_k___i_d of CLOCK_MONOTONIC defined in _<_t_i_m_e_._h_>.  This clock
       represents the monotonic clock for the system. For this clock, the
       value returned by _c_l_o_c_k___g_e_t_t_i_m_e() 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 _c_l_o_c_k___s_e_t_t_i_m_e().  This function shall fail if
       it is invoked with a _c_l_o_c_k___i_d argument of CLOCK_MONOTONIC.

       The effect of setting a clock via _c_l_o_c_k___s_e_t_t_i_m_e() 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 _c_l_o_c_k___s_e_t_t_i_m_e(),
       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
       _c_l_o_c_k___n_a_n_o_s_l_e_e_p() 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 _c_l_o_c_k___s_e_t_t_i_m_e() shall
       have no effect on any thread that is blocked on a relative
       _c_l_o_c_k___n_a_n_o_s_l_e_e_p() 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 _c_l_o_c_k___g_e_t_c_p_u_c_l_o_c_k_i_d(), which represent the
       CPU-time clock of a given process. Implementations shall also support
       the special cclloocckkiidd__tt value CLOCK_PROCESS_CPUTIME_ID, which represents
       the CPU-time clock of the calling process when invoking one of the
       _c_l_o_c_k___*() or _t_i_m_e_r___*() functions. For these clock IDs, the values
       returned by _c_l_o_c_k___g_e_t_t_i_m_e() and specified by _c_l_o_c_k___s_e_t_t_i_m_e() represent
       the amount of execution time of the process associated with the clock.
       Changing the value of a CPU-time clock via _c_l_o_c_k___s_e_t_t_i_m_e() shall have
       no effect on the behavior of the sporadic server scheduling policy (see
       _S_c_h_e_d_u_l_i_n_g _P_o_l_i_c_i_e_s).

       If _POSIX_THREAD_CPUTIME is defined, implementations shall support
       clock ID values obtained by invoking _p_t_h_r_e_a_d___g_e_t_c_p_u_c_l_o_c_k_i_d(), which
       represent the CPU-time clock of a given thread. Implementations shall
       also support the special cclloocckkiidd__tt value CLOCK_THREAD_CPUTIME_ID, which
       represents the CPU-time clock of the calling thread when invoking one
       of the _c_l_o_c_k___*() or _t_i_m_e_r___*() functions. For these clock IDs, the
       values returned by _c_l_o_c_k___g_e_t_t_i_m_e() and specified by _c_l_o_c_k___s_e_t_t_i_m_e()
       shall represent the amount of execution time of the thread associated
       with the clock. Changing the value of a CPU-time clock via
       _c_l_o_c_k___s_e_t_t_i_m_e() shall have no effect on the behavior of the sporadic
       server scheduling policy (see _S_c_h_e_d_u_l_i_n_g _P_o_l_i_c_i_e_s).

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

EERRRROORRSS
       The _c_l_o_c_k___g_e_t_r_e_s(), _c_l_o_c_k___g_e_t_t_i_m_e(), and _c_l_o_c_k___s_e_t_t_i_m_e() functions
       shall fail if:

       EEIINNVVAALL The _c_l_o_c_k___i_d argument does not specify a known clock.

       The _c_l_o_c_k___g_e_t_t_i_m_e() function shall fail if:

       EEOOVVEERRFFLLOOWW
              The number of seconds will not fit in an object of type ttiimmee__tt.

       The _c_l_o_c_k___s_e_t_t_i_m_e() function shall fail if:

       EEIINNVVAALL The _t_p argument to _c_l_o_c_k___s_e_t_t_i_m_e() is outside the range for the
              given clock ID.

       EEIINNVVAALL The _t_p argument specified a nanosecond value less than zero or
              greater than or equal to 1000 million.

       EEIINNVVAALL The value of the _c_l_o_c_k___i_d argument is CLOCK_MONOTONIC.

       The _c_l_o_c_k___s_e_t_t_i_m_e() function may fail if:

       EEPPEERRMM  The requesting process does not have appropriate privileges to
              set the specified clock.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       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 _c_l_o_c_k___s_e_t_t_i_m_e().

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _S_c_h_e_d_u_l_i_n_g _P_o_l_i_c_i_e_s, _c_l_o_c_k___g_e_t_c_p_u_c_l_o_c_k_i_d(), _c_l_o_c_k___n_a_n_o_s_l_e_e_p(), _c_t_i_m_e(),
       _m_q___r_e_c_e_i_v_e(), _m_q___s_e_n_d(), _n_a_n_o_s_l_e_e_p(), _p_t_h_r_e_a_d___m_u_t_e_x___t_i_m_e_d_l_o_c_k(),
       _s_e_m___t_i_m_e_d_w_a_i_t(), _t_i_m_e(), _t_i_m_e_r___c_r_e_a_t_e(), _t_i_m_e_r___g_e_t_o_v_e_r_r_u_n()

       The Base Definitions volume of POSIX.1-2008, <<ttiimmee..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                      CLOCK_GETRES(3)
