Date and Time

Methods for manipulating time and date. More...

Collaboration diagram for Date and Time:

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

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

Functions
bool	sys_date_get_now (sys_date_t *date)
	Gets the current system time. More...
bool	sys_date_set_now (const sys_date_t *date)
	Sets the current system time. More...
bool	sys_date_get_time_utc (sys_date_t *date, uint8_t *hours, uint8_t *minutes, uint8_t *seconds)
	Extracts time components from a sys_date_t structure. More...
bool	sys_date_get_time_local (sys_date_t *date, uint8_t *hours, uint8_t *minutes, uint8_t *seconds)
	Extracts time components from a sys_date_t structure. More...
bool	sys_date_get_date_utc (sys_date_t *date, uint16_t *year, uint8_t *month, uint8_t *day, uint8_t *weekday)
	Extracts date components from a sys_date_t structure. More...
bool	sys_date_get_date_local (sys_date_t *date, uint16_t *year, uint8_t *month, uint8_t *day, uint8_t *weekday)
	Extracts date components from a sys_date_t structure. More...
bool	sys_date_set_time_utc (sys_date_t *date, uint8_t hours, uint8_t minutes, uint8_t seconds)
	Sets time components in a sys_date_t structure, preserving the date and timezone offset. More...
bool	sys_date_set_date_utc (sys_date_t *date, uint16_t year, uint8_t month, uint8_t day)
	Sets date components in a sys_date_t structure, preserving the time and timezone offset. More...
int64_t	sys_date_compare_ns (const sys_date_t *start, const sys_date_t *end)
	Calculate the difference in nanoseconds between two sys_date_t structures. More...
uint64_t	sys_date_get_timestamp ()
	Gets the number of milliseconds since the process started. More...

Detailed Description

Methods for manipulating time and date.

The structure sys_date_t represents a point in time with nanosecond precision, including timezone offset. It provides functions to get and set the current date and time, as well as to manipulate and format date and time values.

The calculation of current timezone offset is not considered in this implementation, since that requires a lot of additional complexity around daylight saving time, leap seconds, and other factors that affect timekeeping.

In addition, setting the system time is not supported on all platforms due to security and permission restrictions. However, on the Pico platform, it is possible to set the system time using the sys_date_set_now() function, and the current time can be retrieved using sys_date_get_now(), which offsets the time set with the number of seconds since the Pico was booted.

Typedef Documentation

sys_date_t

typedef struct sys_date_t sys_date_t

Represents a system date and time structure.

This structure is used to represent time in the system, including the current UTC time with nanosecond precision, and a timezone offset.

Function Documentation

sys_date_compare_ns()

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

Calculate the difference in nanoseconds between two sys_date_t structures.

Parameters

start	Pointer to the start time. If NULL, use the current system time.
end	Pointer to the end time. Cannot be NULL.

Returns

The difference in nanoseconds. If end is earlier than start, returns a negative value.

sys_date_get_date_local()

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

Extracts date components from a sys_date_t structure.

Parameters

date	Pointer to a sys_date_t structure to extract date from. If NULL, the date is extracted from the current system time.
year	Pointer to store year (e.g., 2025), or NULL to skip.
month	Pointer to store month (1-12), or NULL to skip.
day	Pointer to store day (1-31), or NULL to skip.
weekday	Pointer to store weekday (0-6, where 0=Sunday), or NULL to skip.

Returns

true on success, false on error.

This function extracts the year, month, day and weekday components from a sys_date_t structure in local time. The timezone offset is applied to the extracted date.

Examples:

clock/main.c.

sys_date_get_date_utc()

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

Extracts date components from a sys_date_t structure.

Parameters

date	Pointer to a sys_date_t structure to extract date from. If NULL, the date is extracted from the current system time.
year	Pointer to store year (e.g., 2025), or NULL to skip.
month	Pointer to store month (1-12), or NULL to skip.
day	Pointer to store day (1-31), or NULL to skip.
weekday	Pointer to store weekday (0-6, where 0=Sunday), or NULL to skip.

Returns

true on success, false on error.

This function extracts the year, month, day and weekday components from a sys_date_t structure, in universal time (UTC). The timezone offset is not applied to the extracted time.

sys_date_get_now()

bool sys_date_get_now

(

sys_date_t *

date

)

Gets the current system time.

Parameters

date	Pointer to a sys_date_t structure to fill with current date, time and timezone offset.

Returns

true on success, false on error.

Examples:

clock/main.c, and examples/runtime/ntp/main.c.

sys_date_get_time_local()

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

Extracts time components from a sys_date_t structure.

Parameters

date	Pointer to a sys_date_t structure to extract time from. If NULL, the time is extracted from the current system time.
hours	Pointer to store hours (0-23), or NULL to skip.
minutes	Pointer to store minutes (0-59), or NULL to skip.
seconds	Pointer to store seconds (0-59), or NULL to skip.

Returns

true on success, false on error.

This function extracts the time components from a sys_date_t structure, in local time. The timezone offset is applied to the extracted time.

Examples:

clock/main.c.

sys_date_get_time_utc()

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

Extracts time components from a sys_date_t structure.

Parameters

date	Pointer to a sys_date_t structure to extract time from. If NULL, the time is extracted from the current system time.
hours	Pointer to store hours (0-23), or NULL to skip.
minutes	Pointer to store minutes (0-59), or NULL to skip.
seconds	Pointer to store seconds (0-59), or NULL to skip.

Returns

true on success, false on error.

This function extracts the time components from a sys_date_t structure, in universal time (UTC). The timezone offset is not applied to the extracted time.

sys_date_get_timestamp()

uint64_t sys_date_get_timestamp

(

)

Gets the number of milliseconds since the process started.

Returns

The number of milliseconds since the process started, or zero 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
	)

Sets date components in a sys_date_t structure, preserving the time and timezone offset.

Parameters

date	Pointer to a sys_date_t structure to modify.
year	Year to set (1900 or later, supports historical dates).
month	Month to set (1-12).
day	Day to set (1-31).

Returns

true on success, false on invalid parameters.

This function updates the sys_date_t value by setting the date components in UTC. The time and timezone offset remain unchanged. Date components are interpreted as UTC date regardless of the timezone offset.

sys_date_set_now()

bool sys_date_set_now

(

const sys_date_t *

date

)

Sets the current system time.

Parameters

date	Pointer to a sys_date_t structure that contains the new time and timezone offset.

Returns

true on success, false on error.

This function sets the system time by automatically converting the input to UTC using the timezone offset (date->seconds - date->tzoffset). Many platforms do not allow setting the system time directly. This function may fail if the platform does not support setting the system time or if insufficient privileges are available.

Examples:

examples/runtime/ntp/main.c.

sys_date_set_time_utc()

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

Sets time components in a sys_date_t structure, preserving the date and timezone offset.

Parameters

date	Pointer to a sys_date_t structure to modify.
hours	Hours to set (0-23).
minutes	Minutes to set (0-59).
seconds	Seconds to set (0-59).

Returns

true on success, false on invalid parameters.

This function updates the sys_date_t value by setting the time components in UTC. The date and timezone offset remain unchanged. Time components are interpreted as UTC time regardless of the timezone offset.