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 increment while the
			system is asleep.

     CLOCK_MONOTONIC_RAW
			clock that increments monotonically, tracking the time since an arbitrary point like CLOCK_MONOTONIC.  However, this clock
			is unaffected by frequency or time adjustments.  It should not be compared to other system 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 manner as CLOCK_MONOTONIC_RAW, but that does not increment while the sys-
			tem 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 kernel-mode) used by the calling process.

     CLOCK_THREAD_CPUTIME_ID
			clock that tracks the amount of CPU (in user- or kernel-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 mil-
			lion, 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