libiso8601  0.3.14
Functions
Leap second support.

Functions

int iso8601_seconds_leap (const struct iso8601_date *date)
 Return number of seconds in day, taking leap seconds into account. More...
 
int iso8601_leap_elapsed (const struct iso8601_date *start, const struct iso8601_date *end)
 Return number of leap seconds elapsed between two days. More...
 
void iso8601_leap_table_set (int *new_table, int new_size)
 Update table of leap seconds. More...
 
int iso8601_leap_table_load (const char *fname)
 Load new table of leap seconds from disk. More...
 

Detailed Description

A set of functions for explicitly dealing with leap seconds. All library functions are implicitly leap second aware, but there are occasions when leap seconds must be dealt with explicitly. These functions permit this.

Internally, leap seconds are represented as a table of day numbers; each day number present in the table means that the corresponding day has 86401 seconds (a leap second).

Note
The library does not (yet) have support for negative leap seconds. This support will be added should a day with a negative leap second ever come. This will need to addressed in the API as the current API does not support loading a table of negative leap seconds.

It is possible to create a disk file containing an updated table and to load that file using iso8601_leap_table_load (or to explicitly use an existing in-memory table with iso8601_leap_table_set). The format of the on-disk file is:

# integers are stored big-endian
[8*char] signature, "/O9PdPZI"
[uint32] number of entries, 'n'

entries are repeated 'n' times, and stored lowest day number first

[uint32] day number of entry

Function Documentation

◆ iso8601_seconds_leap()

int iso8601_seconds_leap ( const struct iso8601_date date)

Return number of seconds in day, taking leap seconds into account.

Parameters
dateThe date to return the number of seconds for.
Return values
86399day with a negative leap second.
86400day with no leap second.
86401day with one leap second.

Returns the duration of a day date, in seconds. This function takes leap seconds into account and may be used to determine if a day contains a leap second or not.

Note
There have not yet been any days requiring a negative leap second, so at present 86399 will never be returned.

◆ iso8601_leap_elapsed()

int iso8601_leap_elapsed ( const struct iso8601_date start,
const struct iso8601_date end 
)

Return number of leap seconds elapsed between two days.

Parameters
startThe start date.
endThe end date.
Returns
Number of leap seconds elapsed.

Computes the number of leap seconds that have elapsed between two days. Note that this is the sum of such leap seconds, so it will be 0 if (for example) there is one positive leap second and one negative leap second. The ordering of the dates is important; if start is after end, then the value returned will be negative (for positive leap seconds).

◆ iso8601_leap_table_set()

void iso8601_leap_table_set ( int *  new_table,
int  new_size 
)

Update table of leap seconds.

Parameters
new_tableArray of day numbers on which leap seconds occur.
new_sizeNumber of entries in array.

This function can be used to update the table of leap seconds at runtime. The new_table argument points to an array of integers, each entry being the day number containing a leap second. The array must be sorted so that lower day numbers appear towards the start of the array. new_size gives the number of entries in the array. new_table must persist in memory as long as library functions are in use.

Warning
If negative leap seconds are ever used, this function will not support them. There may need to be an ABI change in future to solve this problem.

◆ iso8601_leap_table_load()

int iso8601_leap_table_load ( const char *  fname)

Load new table of leap seconds from disk.

Parameters
fnameFilename. May be 0 for system default.
Return values
0on success.
-1on error (and see errno).

This function attempts to load a new table of leap seconds from disk, using the filename fname. If fname is not specified, the system default (set at compile time) will be used.

If the table is loaded successfully, it will be set with iso8601_leap_table_set(). On any error, -1 will be returned, and errno will be set appropriately. If errno is EINVAL, then the file does not contain a valid leap second table.