CLOCK_GETTIME(3)         BSD Library Functions Manual         CLOCK_GETTIME(3)

NNAAMMEE
     cclloocckk__ggeettttiimmee, cclloocckk__sseettttiimmee, cclloocckk__ggeettrreess, cclloocckk__ggeettttiimmee__nnsseecc__nnpp --
     get/set date and time

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ttiimmee..hh>>

     _i_n_t
     cclloocckk__ggeettttiimmee(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p);

     _i_n_t
     cclloocckk__sseettttiimmee(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p);

     _i_n_t
     cclloocckk__ggeettrreess(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p);

     _u_i_n_t_6_4___t
     cclloocckk__ggeettttiimmee__nnsseecc__nnpp(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d);

DDEESSCCRRIIPPTTIIOONN
     The cclloocckk__ggeettttiimmee() and cclloocckk__sseettttiimmee() functions allow the calling
     process to retrieve or set the value used by a clock which is specified
     by _c_l_o_c_k___i_d.

     _c_l_o_c_k___i_d can be a value from one of 5 predefined values:

     CLOCK_REALTIME     the system's real time (i.e. wall time) clock,
                        expressed as the amount of time since the Epoch.  This
                        is the same as the value returned by gettimeofday(2).

     CLOCK_MONOTONIC    clock that increments monotonically, tracking the time
                        since an arbitrary point, and will continue to incre-
                        ment while the system is asleep.

     CLOCK_MONOTONIC_RAW
                        clock that increments monotonically, tracking the time
                        since an arbitrary point like CLOCK_MONOTONIC.  How-
                        ever, this clock is unaffected by frequency or time
                        adjustments.  It should not be compared to other sys-
                        tem time sources.

     CLOCK_MONOTONIC_RAW_APPROX
                        like CLOCK_MONOTONIC_RAW, but reads a value cached by
                        the system at context switch.  This can be read
                        faster, but at a loss of accuracy as it may return
                        values that are milliseconds old.

     CLOCK_UPTIME_RAW   clock that increments monotonically, in the same man-
                        ner as CLOCK_MONOTONIC_RAW, but that does not incre-
                        ment while the system is asleep.  The returned value
                        is identical to the result of mmaacchh__aabbssoolluuttee__ttiimmee()
                        after the appropriate mach_timebase conversion is
                        applied.

     CLOCK_UPTIME_RAW_APPROX
                        like CLOCK_UPTIME_RAW, but reads a value cached by the
                        system at context switch.  This can be read faster,
                        but at a loss of accuracy as it may return values that
                        are milliseconds old.

     CLOCK_PROCESS_CPUTIME_ID
                        clock that tracks the amount of CPU (in user- or ker-
                        nel-mode) used by the calling process.

     CLOCK_THREAD_CPUTIME_ID
                        clock that tracks the amount of CPU (in user- or ker-
                        nel-mode) used by the calling thread.

     The structure pointed to by _t_p is defined in <_s_y_s_/_t_i_m_e_._h> as:

           struct timespec {
               time_t  tv_sec;     /* seconds */
               long    tv_nsec;    /* and nanoseconds */
           };

     Only the CLOCK_REALTIME clock can be set, and only the superuser may do
     so.

     The resolution of a clock is returned by the cclloocckk__ggeettrreess() call.  This
     value is placed in a (non-null) _*_t_p.  This value may be smaller than the
     actual precision of the underlying clock, but represents a lower bound on
     the resolution.

     As a non-portable extension, the cclloocckk__ggeettttiimmee__nnsseecc__nnpp() function will
     return the clock value in 64-bit nanoseconds.

RREETTUURRNN VVAALLUUEESS
     A 0 return value indicates that the call succeeded.  A -1 return value
     indicates an error occurred, and in this case an error code is stored
     into the global variable _e_r_r_n_o.  For cclloocckk__ggeettttiimmee__nnsseecc__nnpp() a return
     value of non-0 indicates success.  A 0 return value indicates an error
     occurred and an error code is stored in _e_r_r_n_o.

EERRRROORRSS
     cclloocckk__ggeettttiimmee(), cclloocckk__sseettttiimmee(), cclloocckk__ggeettrreess(), and
     cclloocckk__ggeettttiimmee__nnsseecc__nnpp() will fail if:

     [EINVAL]           _c_l_o_c_k___i_d is not a valid value.

     [EFAULT]           The _t_p argument address referenced invalid memory.

     In addition, cclloocckk__sseettttiimmee() may return the following errors:

     [EPERM]            A user other than the superuser attempted to set the
                        time.

     [EINVAL]           _c_l_o_c_k___i_d specifies a clock that isn't settable, _t_p
                        specifies a nanosecond value less than zero or greater
                        than 1000 million, or a value outside the range of the
                        specified clock.

SSEEEE AALLSSOO
     date(1), getitimer(2), gettimeofday(2),

HHIISSTTOORRYY
     These functions first appeared in Mac OSX 10.12

SSTTAANNDDAARRDDSS
     The cclloocckk__ggeettttiimmee(), cclloocckk__sseettttiimmee(), and cclloocckk__ggeettrreess() system calls
     conform to IEEE Std 1003.1b-1993 (``POSIX.1'').  cclleecckk__ggeettttiimmee__nnsseecc__nnpp()
     is a non-portable Darwin extension.  The clock IDs _C_L_O_C_K___M_O_N_O_T_O_N_I_C___R_A_W
     and _C_L_O_C_K___U_P_T_I_M_E___R_A_W are extensions to the POSIX interface.

BSD                            January 26, 2016                            BSD