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