MICROTIME(9) | Kernel Developer's Manual | 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)

December 28, 2022 | Debian