summaryrefslogtreecommitdiff
path: root/doc/time_functions.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/time_functions.rst')
-rw-r--r--doc/time_functions.rst125
1 files changed, 125 insertions, 0 deletions
diff --git a/doc/time_functions.rst b/doc/time_functions.rst
new file mode 100644
index 0000000..d9a57a1
--- /dev/null
+++ b/doc/time_functions.rst
@@ -0,0 +1,125 @@
+==============
+Time functions
+==============
+
+Time in POSIX systems is represented in ``struct timespec``. This structure is
+composed of two members: one integer for the number of full seconds in the time
+value, and one integer for the number of nanoseconds that remain when
+subtracting the full seconds from the time value. POSIX leaves it unspecified
+how negative time is to be represented with this structure, so I have devised
+an algebra for use with the same struct that gives negative time support.
+
+Since integers often cannot store negative zero (due to e.g. use of 2s
+complements in the language implementation), we will store the minus sign in
+the nanosecond member if the integral second part is zero. This gives us the
+property that we can test for negative time by looking for whether at least one
+member of the structure is negative. Also, we want to avoid storing the minus
+in both members to somewhat aid the pretty-printing construct often seen,
+
+.. code-block:: c
+
+ printf("%ld.%09ld\n", (long)ts.tv_sec, ts.tv_nsec);
+
+The number of combinations of a (non-zero) negative number, zero and a
+(non-zero) positive number is small, so we can actually just exhaustively list
+them all.
+
++----------------+------------+
+| Representation | Time value |
++================+============+
+| {-1, -1} | illegal |
++----------------+------------+
+| {-1, 0} | -1.0 s |
++----------------+------------+
+| {-1, 1} | -1.1 s |
++----------------+------------+
+| { 0, -1} | -0.1 s |
++----------------+------------+
+| { 0, 0} | 0.0 s |
++----------------+------------+
+| { 0, 1} | 0.1 s |
++----------------+------------+
+| { 1, -1} | illegal |
++----------------+------------+
+| { 1, 0} | 1.0 s |
++----------------+------------+
+| { 1, 1} | 1.1 s |
++----------------+------------+
+
+Function list
+=============
+
+.. code-block:: c
+
+ #include <libHX/misc.h>
+
+ bool HX_timespec_isneg(const struct timespec *p);
+
+ struct timespec *HX_timespec_neg(struct timespec *result,
+ const struct timespec *p);
+
+ struct timespec *HX_timespec_add(struct timespec *result,
+ const struct timespec *p, const struct timespec *q);
+
+ struct timespec *HX_timespec_sub(struct timespec *delta,
+ const struct timespec *p, const struct timespec *q);
+
+ struct timespec *HX_timespec_mul(struct timespec *delta,
+ const struct timespec *p, int f);
+
+ struct timespec *HX_timespec_mulf(struct timespec *delta,
+ const struct timespec *p, double f);
+
+ struct timeval *HX_timeval_sub(struct timeval *delta,
+ const struct timeval *p, const struct timeval *q);
+
+ int HX_time_compare(const struct stat *a, const struct stat *b,
+ int mode);
+
+``HX_timespec_isneg``
+ Determines whether a timespec structure represents (non-zero) negative
+ time.
+
+``HX_timespec_neg``
+ Computes the negation of the time specified by ``p``. ``result`` and
+ ``p`` may point to the same structure.
+
+``HX_timespec_add``
+ Calculates the sum of the two times specified by ``p`` and ``q``, which
+ are of type ``struct timespec``. Any and all of ``result``, ``p`` and
+ ``q`` may point to the same structure.
+
+``HX_timespec_sub``
+ Calculates the difference between the two timepoints ``p`` and ``q``,
+ which are of type ``struct timespec`` (nanosecond granularity).
+
+``HX_timespec_mul``
+ Multiplies the time quantum in ``p`` by ``f``.
+
+``HX_timespec_mulf``
+ Multiplies the time quantum in ``p`` by ``f``.
+
+``HX_timeval_sub``
+ Calculates the difference between the two timepoints ``p`` and ``q``,
+ which are of type ``struct timeval`` (microsecnod granularity).
+
+``HX_time_compare``
+ Compares the timestamps from two struct stats. ``mode`` indicates which
+ field is compared, which can either be ``'a'`` for the access time,
+ ``'c'`` for the inode change time, ``'m'`` for the modification time,
+ or ``'o'`` for the creation time (where available). Returns a negative
+ number if the time in ``a`` is less than ``b``, zero when they are
+ equal, or a positive number greater than zero if ``a`` is greater than
+ ``b``.
+
+The macros ``HX_TIMESPEC_FMT`` and ``HX_TIMESPEC_EXP`` can be used for passing
+and printing a ``struct timespec`` using the ``*printf`` function family:
+
+.. code-block:: c
+
+ struct timespec p;
+ clock_gettime(CLOCK_MONOTONIC, &p);
+ printf("Now: " HX_TIMESPEC_FMT, HX_TIMESPEC_EXP(&p));
+
+Similarly, ``HX_TIMEVAL_FMT`` and ``HX_TIMEVAL_EXP`` exist for the older
+``struct timeval``.