Add documentation for leap second table functions

This commit is contained in:
Laurence Withers 2009-01-03 19:40:16 +00:00
parent ddaa9a8f8d
commit 711872660b
1 changed files with 57 additions and 2 deletions

View File

@ -9,7 +9,27 @@
/*! \defgroup leap Leap second support.
A set of functions for explicitly dealing with leap seconds.
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
\ref iso8601_leap_table_load (or to explicitly use an existing in-memory table with
\ref iso8601_leap_table_set). The format of the on-disk file is:
<pre># 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</pre>
*/
/*!@{*/
@ -50,8 +70,43 @@ int iso8601_leap_elapsed(const struct iso8601_date* start, const struct iso8601_
/*! \brief Update table of leap seconds.
\param new_table Array of day numbers on which leap seconds occur.
\param new_size Number of entries in array.
This function can be used to update the table of leap seconds at runtime. The \a 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. \a new_size gives
the number of entries in the array. \a 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.
*/
void iso8601_leap_table_set(int* new_table, int new_size) __attribute__((nonnull));
/*! \brief Load new table of leap seconds from disk.
\param fname Filename.
\retval 0 on success.
\retval -1 on error (and see \a errno).
This function attempts to load a new table of leap seconds from disk, using the filename \a fname.
If the table is loaded successfully, it will be set with \ref iso8601_leap_table_set(). On any
error, -1 will be returned, and \a errno will be set appropriately. If \a errno is \c EINVAL, then
the file does not contain a valid leap second table.
*/
int iso8601_leap_table_load(const char* fname) __attribute__((nonnull));
/*!@}*/
/* options for text editors
kate: replace-trailing-space-save true; space-indent true; tab-width 4;
vim: expandtab:ts=4:sw=4
vim: expandtab:ts=4:sw=4:syntax=ch.doxygen
*/