manpagez: man pages & more
man clock_gettime_nsec_np(3)
Home | html | info | man

clock_gettime(3)         BSD Library Functions Manual         clock_gettime(3)


NAME

     clock_gettime, clock_settime, clock_getres, clock_gettime_nsec_np --
     get/set date and time


SYNOPSIS

     #include <time.h>

     int
     clock_gettime(clockid_t clock_id, struct timespec *tp);

     int
     clock_settime(clockid_t clock_id, const struct timespec *tp);

     int
     clock_getres(clockid_t clock_id, struct timespec *tp);

     uint64_t
     clock_gettime_nsec_np(clockid_t clock_id);


DESCRIPTION

     The clock_gettime() and clock_settime() functions allow the calling
     process to retrieve or set the value used by a clock which is specified
     by clock_id.

     clock_id 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 mach_absolute_time()
                        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 tp is defined in <sys/time.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 clock_getres() call.  This
     value is placed in a (non-null) *tp.  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 clock_gettime_nsec_np() function will
     return the clock value in 64-bit nanoseconds.


RETURN VALUES

     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 errno.  For clock_gettime_nsec_np() a return
     value of non-0 indicates success.  A 0 return value indicates an error
     occurred and an error code is stored in errno.


ERRORS

     clock_gettime(), clock_settime(), clock_getres(), and
     clock_gettime_nsec_np() will fail if:

     [EINVAL]           clock_id is not a valid value.

     [EFAULT]           The tp argument address referenced invalid memory.

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

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

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


SEE ALSO

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


HISTORY

     These functions first appeared in Mac OSX 10.12


STANDARDS

     The clock_gettime(), clock_settime(), and clock_getres() system calls
     conform to IEEE Std 1003.1b-1993 (``POSIX.1'').  cleck_gettime_nsec_np()
     is a non-portable Darwin extension.  The clock IDs CLOCK_MONOTONIC_RAW
     and CLOCK_UPTIME_RAW are extensions to the POSIX interface.

BSD                            January 26, 2016                            BSD

Mac OS X 10.12.3 - Generated Wed Feb 8 05:51:11 CST 2017
© manpagez.com 2000-2019
Individual documents may contain additional copyright information.