High-precision timestamps

#include <libcork/core.h>

uint64_t cork_timestamp

A high-precision timestamp type. A timestamp is represented by a 64-bit integer, whose unit is the gammasecond (γsec), where \(1~\textrm{γsec} = \frac{1}{2^{32}} \textrm{sec}\). With this representation, the upper 32 bits of a timestamp value represent the timestamp truncated (towards zero) to seconds.

For this type, we don’t concern ourselves with any higher-level issues of clock synchronization or time zones. cork_timestamp values can be used to represent any time quantity, regardless of which time standard (UTC, GMT, TAI) you use, or whether it takes into account the local time zone.

void cork_timestamp_init_sec(cork_timestamp *ts, uint32_t sec)

void cork_timestamp_init_gsec(cork_timestamp *ts, uint32_t sec, uint32_t gsec)

void cork_timestamp_init_msec(cork_timestamp *ts, uint32_t sec, uint32_t msec)

void cork_timestamp_init_usec(cork_timestamp *ts, uint32_t sec, uint32_t usec)

void cork_timestamp_init_nsec(cork_timestamp *ts, uint32_t sec, uint32_t nsec)

Initializes a timestamp from a separate seconds part and fractional part. For the _sec variant, the fractional part will be set to 0. For the _gsec variant, you provide the fractional part in gammaseconds. For the _msec, _usec, and _nsec variants, the fractional part will be translated into gammaseconds from milliseconds, microseconds, or nanoseconds, respectively.

void cork_timestamp_init_now(cork_timestamp *ts)

Initializes a timestamp with the current UTC time of day.

Note

The resolution of this function is system-dependent.

uint32_t cork_timestamp_sec(const cork_timestamp ts)

Returns the seconds portion of a timestamp.

uint32_t cork_timestamp_gsec(const cork_timestamp ts)

uint32_t cork_timestamp_msec(const cork_timestamp ts)

uint32_t cork_timestamp_usec(const cork_timestamp ts)

uint32_t cork_timestamp_nsec(const cork_timestamp ts)

Returns the fractional portion of a timestamp. The variants return the fractional portion in, respectively, gammaseconds, milliseconds, microseconds, or nanoseconds.

int cork_timestamp_format_utc(const cork_timestamp ts, const char *format, struct cork_buffer *buf)

int cork_timestamp_format_local(const cork_timestamp ts, const char *format, struct cork_buffer *buf)

Create the string representation of the given timestamp according to format, appending the result to the current contents of buf.

The _utc variant assumes that ts represents a UTC time, whereas the _local variant assumes that it represents a time in the local time zone.

format is a format string whose syntax is similar to that of the POSIX strftime function. format must contain arbitrary text interspersed with % specifiers, which will be replaced with portions of the timestamp. The following specifiers are recognized (note that this list does not include all of the specifiers supported by strftime):

Specifier	Replacement
%%	A literal % character
%d	Day of month (01-31)
%[width]f	Fractional seconds (zero-padded, limited to [width] digits)
%H	Hour in current day (00-23)
%m	Month (01-12)
%M	Minute in current hour (00-59)
%s	Number of seconds since Unix epoch
%S	Second in current minute (00-60)
%Y	Four-digit year (including century)

If the format string is invalid, we will return an error condition.