libiso8601
0.3.14
|
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... | |
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).
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
int iso8601_seconds_leap | ( | const struct iso8601_date * | date | ) |
Return number of seconds in day, taking leap seconds into account.
date | The date to return the number of seconds for. |
86399 | day with a negative leap second. |
86400 | day with no leap second. |
86401 | day 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.
int iso8601_leap_elapsed | ( | const struct iso8601_date * | start, |
const struct iso8601_date * | end | ||
) |
Return number of leap seconds elapsed between two days.
start | The start date. |
end | The end date. |
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).
void iso8601_leap_table_set | ( | int * | new_table, |
int | new_size | ||
) |
Update table of leap seconds.
new_table | Array of day numbers on which leap seconds occur. |
new_size | Number 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.
int iso8601_leap_table_load | ( | const char * | fname | ) |
Load new table of leap seconds from disk.
fname | Filename. May be 0 for system default. |
0 | on success. |
-1 | on 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.