1/* timespec -- System time interface
2
3 Copyright (C) 2000, 2002, 2004-2005, 2007, 2009-2019 Free Software
4 Foundation, Inc.
5
6 This program is free software: you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 3 of the License, or
9 (at your option) any later version.
10
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with this program. If not, see <https://www.gnu.org/licenses/>. */
18
19#if ! defined TIMESPEC_H
20#define TIMESPEC_H
21
22#include <time.h>
23
24#ifndef _GL_INLINE_HEADER_BEGIN
25 #error "Please include config.h first."
26#endif
27_GL_INLINE_HEADER_BEGIN
28#ifndef _GL_TIMESPEC_INLINE
29# define _GL_TIMESPEC_INLINE _GL_INLINE
30#endif
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
36#include "arg-nonnull.h"
37#include "verify.h"
38
39/* Inverse resolution of timespec timestamps (in units per second),
40 and log base 10 of the inverse resolution. */
41
42enum { TIMESPEC_HZ = 1000000000 };
43enum { LOG10_TIMESPEC_HZ = 9 };
44
45/* Obsolescent names for backward compatibility.
46 They are misnomers, because TIMESPEC_RESOLUTION is not a resolution. */
47
48enum { TIMESPEC_RESOLUTION = TIMESPEC_HZ };
49enum { LOG10_TIMESPEC_RESOLUTION = LOG10_TIMESPEC_HZ };
50
51/* Return a timespec with seconds S and nanoseconds NS. */
52
53_GL_TIMESPEC_INLINE struct timespec
54make_timespec (time_t s, long int ns)
55{
56 struct timespec r;
57 r.tv_sec = s;
58 r.tv_nsec = ns;
59 return r;
60}
61
62/* Return negative, zero, positive if A < B, A == B, A > B, respectively.
63
64 For each timestamp T, this code assumes that either:
65
66 * T.tv_nsec is in the range 0..999999999; or
67 * T.tv_sec corresponds to a valid leap second on a host that supports
68 leap seconds, and T.tv_nsec is in the range 1000000000..1999999999; or
69 * T.tv_sec is the minimum time_t value and T.tv_nsec is -1; or
70 T.tv_sec is the maximum time_t value and T.tv_nsec is 2000000000.
71 This allows for special struct timespec values that are less or
72 greater than all possible valid timestamps.
73
74 In all these cases, it is safe to subtract two tv_nsec values and
75 convert the result to integer without worrying about overflow on
76 any platform of interest to the GNU project, since all such
77 platforms have 32-bit int or wider.
78
79 Replacing "a.tv_nsec - b.tv_nsec" with something like
80 "a.tv_nsec < b.tv_nsec ? -1 : a.tv_nsec > b.tv_nsec" would cause
81 this function to work in some cases where the above assumption is
82 violated, but not in all cases (e.g., a.tv_sec==1, a.tv_nsec==-2,
83 b.tv_sec==0, b.tv_nsec==999999999) and is arguably not worth the
84 extra instructions. Using a subtraction has the advantage of
85 detecting some invalid cases on platforms that detect integer
86 overflow. */
87
88_GL_TIMESPEC_INLINE int _GL_ATTRIBUTE_PURE
89timespec_cmp (struct timespec a, struct timespec b)
90{
91 if (a.tv_sec < b.tv_sec)
92 return -1;
93 if (a.tv_sec > b.tv_sec)
94 return 1;
95
96 /* Pacify gcc -Wstrict-overflow (bleeding-edge circa 2017-10-02). See:
97 https://lists.gnu.org/r/bug-gnulib/2017-10/msg00006.html */
98 assume (-1 <= a.tv_nsec && a.tv_nsec <= 2 * TIMESPEC_HZ);
99 assume (-1 <= b.tv_nsec && b.tv_nsec <= 2 * TIMESPEC_HZ);
100
101 return a.tv_nsec - b.tv_nsec;
102}
103
104/* Return -1, 0, 1, depending on the sign of A. A.tv_nsec must be
105 nonnegative. */
106_GL_TIMESPEC_INLINE int _GL_ATTRIBUTE_PURE
107timespec_sign (struct timespec a)
108{
109 return a.tv_sec < 0 ? -1 : a.tv_sec || a.tv_nsec;
110}
111
112struct timespec timespec_add (struct timespec, struct timespec)
113 _GL_ATTRIBUTE_CONST;
114struct timespec timespec_sub (struct timespec, struct timespec)
115 _GL_ATTRIBUTE_CONST;
116struct timespec dtotimespec (double)
117 _GL_ATTRIBUTE_CONST;
118
119/* Return an approximation to A, of type 'double'. */
120_GL_TIMESPEC_INLINE double
121timespectod (struct timespec a)
122{
123 return a.tv_sec + a.tv_nsec / 1e9;
124}
125
126struct timespec current_timespec (void);
127void gettime (struct timespec *) _GL_ARG_NONNULL ((1));
128int settime (struct timespec const *) _GL_ARG_NONNULL ((1));
129
130#ifdef __cplusplus
131}
132#endif
133
134_GL_INLINE_HEADER_END
135
136#endif
137