1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
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``.
|
