From 711872660bb7d8507c522ea14ba520ab27b5a15c Mon Sep 17 00:00:00 2001
From: Laurence Withers <lwithers@amethyst.(none)>
Date: Sat, 3 Jan 2009 19:40:16 +0000
Subject: [PATCH] Add documentation for leap second table functions

---
 src/libiso8601/400_leap.h | 59 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 57 insertions(+), 2 deletions(-)

diff --git a/src/libiso8601/400_leap.h b/src/libiso8601/400_leap.h
index 4d64522..05304ca 100644
--- a/src/libiso8601/400_leap.h
+++ b/src/libiso8601/400_leap.h
@@ -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
 */