Date and Time

Monotonic timing and wall-clock date/time operations. More...

Collaboration diagram for Date and Time:

Files
file	date.h
	Defines date and wall-clock time APIs.

Data Structures
struct	sys_date_t
	Represents a system date and time. More...

Typedefs
typedef struct sys_date_t	sys_date_t
	Represents a system date and time.

Enumerations
enum	sys_date_format_t { sys_date_format_iso8601 = 0, sys_date_format_rfc2822 = 1, sys_date_format_log = 2 }
	Common human-readable date/time string formats. More...

Functions
uint64_t	sys_timestamp_ms (void)
	Gets the number of milliseconds since the process launched.

Methods
bool	sys_date_get_now (sys_date_t *date)
	Get the current system date and time. More...
bool	sys_date_set_now (const sys_date_t *date)
	Set the current system date and time. More...
bool	sys_date_get_time_utc (const sys_date_t *date, uint8_t *hours, uint8_t *minutes, uint8_t *seconds)
	Extract UTC time components from a date. More...
bool	sys_date_get_time_local (const sys_date_t *date, uint8_t *hours, uint8_t *minutes, uint8_t *seconds)
	Extract local time components from a date. More...
bool	sys_date_get_date_utc (const sys_date_t *date, uint16_t *year, uint8_t *month, uint8_t *day, uint8_t *weekday)
	Extract UTC date components from a date. More...
bool	sys_date_get_date_local (const sys_date_t *date, uint16_t *year, uint8_t *month, uint8_t *day, uint8_t *weekday)
	Extract local date components from a date. More...
bool	sys_date_set_time_utc (sys_date_t *date, uint8_t hours, uint8_t minutes, uint8_t seconds)
	Set UTC time components on an existing date. More...
bool	sys_date_set_date_utc (sys_date_t *date, uint16_t year, uint8_t month, uint8_t day)
	Set UTC date components on an existing date. More...
int64_t	sys_date_compare_ns (const sys_date_t *start, const sys_date_t *end)
	Compare two dates in nanoseconds. More...
size_t	sys_date_to_string (const sys_date_t *date, sys_date_format_t format, char *buf, size_t buf_size)
	Format a date as a human-readable string. More...

Detailed Description

Monotonic timing and wall-clock date/time operations.

The SystemTime module provides monotonic timing and wall-clock date/time operations for scheduling, time measurement, and timestamped application logic.

Enumeration Type Documentation

sys_date_format_t

enum sys_date_format_t

Common human-readable date/time string formats.

Enumerator
sys_date_format_iso8601	"2026-09-06T11:37:05Z" - or, when tzoffset is non-zero, an explicit "+HH:MM"/"-HH:MM" offset instead of "Z".
sys_date_format_rfc2822	"Sun, 06 Sep 2026 11:37:05 GMT" - the HTTP-date format (RFC 7231 7.1.1.1), always rendered in UTC regardless of the date's own tzoffset.
sys_date_format_log	"2026-09-06 11:37:05" - a plain, sortable form for logs/debug output, in whatever timezone tzoffset represents.

Definition at line 35 of file date.h.

             {
  sys_date_format_iso8601 = 0, 
  sys_date_format_rfc2822 = 1, 
  sys_date_format_log = 2,     
} sys_date_format_t;

Function Documentation

sys_date_compare_ns()

int64_t sys_date_compare_ns	(	const sys_date_t *	start,
		const sys_date_t *	end
	)

Compare two dates in nanoseconds.

Parameters

start	Start time, or NULL to use the current system time.
end	End time, or NULL to return 0.

Returns

Signed nanosecond difference between start and end, or 0 when end is NULL.

sys_date_get_date_local()

bool sys_date_get_date_local	(	const sys_date_t *	date,
		uint16_t *	year,
		uint8_t *	month,
		uint8_t *	day,
		uint8_t *	weekday
	)

Extract local date components from a date.

Parameters

date	Date to extract from, or NULL to use the current system time.
year	Receives the full year when non-NULL.
month	Receives the month in the range 1-12 when non-NULL.
day	Receives the day of month in the range 1-31 when non-NULL.
weekday	Receives the weekday in the range 0-6 when non-NULL.

Returns

true on success, false on error.

sys_date_get_date_utc()

bool sys_date_get_date_utc	(	const sys_date_t *	date,
		uint16_t *	year,
		uint8_t *	month,
		uint8_t *	day,
		uint8_t *	weekday
	)

Extract UTC date components from a date.

Parameters

date	Date to extract from, or NULL to use the current system time.
year	Receives the full year when non-NULL.
month	Receives the month in the range 1-12 when non-NULL.
day	Receives the day of month in the range 1-31 when non-NULL.
weekday	Receives the weekday in the range 0-6 when non-NULL.

Returns

true on success, false on error.

sys_date_get_now()

bool sys_date_get_now

(

sys_date_t *

date

)

Get the current system date and time.

Parameters

date	Structure to populate with the current time and timezone.

Returns

true on success, false on error.

sys_date_get_time_local()

bool sys_date_get_time_local	(	const sys_date_t *	date,
		uint8_t *	hours,
		uint8_t *	minutes,
		uint8_t *	seconds
	)

Extract local time components from a date.

Parameters

date	Date to extract from, or NULL to use the current system time.
hours	Receives hours in the range 0-23 when non-NULL.
minutes	Receives minutes in the range 0-59 when non-NULL.
seconds	Receives seconds in the range 0-59 when non-NULL.

Returns

true on success, false on error.

sys_date_get_time_utc()

bool sys_date_get_time_utc	(	const sys_date_t *	date,
		uint8_t *	hours,
		uint8_t *	minutes,
		uint8_t *	seconds
	)

Extract UTC time components from a date.

Parameters

date	Date to extract from, or NULL to use the current system time.
hours	Receives hours in the range 0-23 when non-NULL.
minutes	Receives minutes in the range 0-59 when non-NULL.
seconds	Receives seconds in the range 0-59 when non-NULL.

Returns

true on success, false on error.

sys_date_set_date_utc()

bool sys_date_set_date_utc	(	sys_date_t *	date,
		uint16_t	year,
		uint8_t	month,
		uint8_t	day
	)

Set UTC date components on an existing date.

Parameters

date	Date structure to modify.
year	Full year value.
month	Month in the range 1-12.
day	Day of month in the range 1-31.

Returns

true on success, false on invalid parameters.

sys_date_set_now()

bool sys_date_set_now

(

const sys_date_t *

date

)

Set the current system date and time.

Parameters

date	Structure containing the new time and timezone offset.

Returns

true on success, false on error.

sys_date_set_time_utc()

bool sys_date_set_time_utc	(	sys_date_t *	date,
		uint8_t	hours,
		uint8_t	minutes,
		uint8_t	seconds
	)

Set UTC time components on an existing date.

Parameters

date	Date structure to modify.
hours	Hours in the range 0-23.
minutes	Minutes in the range 0-59.
seconds	Seconds in the range 0-59.

Returns

true on success, false on invalid parameters.

sys_date_to_string()

size_t sys_date_to_string	(	const sys_date_t *	date,
		sys_date_format_t	format,
		char *	buf,
		size_t	buf_size
	)

Format a date as a human-readable string.

Parameters

date	Date to format, or NULL to use the current system time.
format	Which format to render - see sys_date_format_t.
buf	Destination buffer.
buf_size	Size of buf in bytes.

Returns

Number of characters that would have been written to buf, not counting the null terminator, same truncation semantics as sys_sprintf() - or 0 if date was NULL and the current time couldn't be read.