MICROTIME(9)

NAME
microuptime, getmicrouptime, nanouptime, getnanouptime, nsecuptime, getnsecuptime, getuptime, nanoruntime, getnsecruntime, microtime, getmicrotime, nanotime, getnanotime, gettime, microboottime, nanoboottime - get the time

SYNOPSIS
#include <sys/time.h>
void
microuptime(struct timeval *tv);
void
getmicrouptime(struct timeval *tv);
void
nanouptime(struct timespec *ts);
void
getnanouptime(struct timespec *ts);
uint64_t
nsecuptime(void);
uint64_t
getnsecuptime(void);
time_t
getuptime(void);
void
nanoruntime(struct timespec *ts);
uint64_t
getnsecruntime(void);
void
microtime(struct timeval *tv);
void
getmicrotime(struct timeval *tv);
void
nanotime(struct timespec *ts);
void
getnanotime(struct timespec *ts);
time_t
gettime(void);
void
microboottime(struct timeval *tv);
void
nanoboottime(struct timespec *ts);

DESCRIPTION
The kernel has three clocks and a variety of interfaces for reading them.

The uptime clock measures the time elapsed since the system booted. It begins at zero and advances monotonically. The uptime clock may be read with the following functions:
Name | Output Format | Source
microuptime() | struct timeval | hardware
getmicrouptime() | struct timeval | timestamp
nanouptime() | struct timespec | hardware
getnanouptime() | struct timespec | timestamp
nsecuptime() | uint64_t | hardware
getnsecuptime() | uint64_t | timestamp
getuptime() | time_t | timestamp

The runtime clock measures the time elapsed since the system booted, less any time the system is suspended or hibernating. It begins at zero and normally advances monotonically, but pauses while the system is suspended or hibernating. The runtime clock may be read with the following functions:
Name | Output Format | Source
nanoruntime() | struct timespec | hardware
getnsecruntime() | uint64_t | timestamp

The UTC clock measures the time elapsed since Jan 1 1970 00:00:00 (the Unix Epoch). The clock normally advances monotonically, but jumps when a process calls clock_settime(2) or settimeofday(2). The UTC clock may be read with the following functions:
Name | Output Format | Source
microtime() | struct timeval | hardware
getmicrotime() | struct timeval | timestamp
nanotime() | struct timespec | hardware
getnanotime() | struct timespec | timestamp
gettime() | time_t | timestamp

The kernel also maintains a boot timestamp. It is the moment on the UTC clock when the system booted. The timestamp jumps when a process calls clock_settime(2) or settimeofday(2). The boot timestamp may be read with the following functions:
Name | Output Format | Source
microboottime() | struct timeval | timestamp
nanoboottime() | struct timespec | timestamp

Functions that source from the hardware provide the most precise result possible. Functions that source from a timestamp provide a far less precise result, but do so very quickly. On most platforms, timestamps are updated approximately 100 times per second.

CONTEXT
These functions may be called during autoconf, from process context, or from any interrupt context.

RETURN VALUES
nsecuptime(), getnsecuptime(), and getnsecruntime() return a count of nanoseconds.

getuptime() and gettime() return a count of seconds.

ERRORS
These functions are always successful, and no return value is reserved to indicate an error.

CODE REFERENCES
sys/kern/kern_tc.c

SEE ALSO
clock_settime(2), settimeofday(2), timeradd(3), hardclock(9), hz(9), inittodr(9), tc_init(9)