Asterisk - The Open Source Telephony Project  GIT-master-a24979a
time.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*! \file
20  * \brief Time-related functions and macros
21  */
22 
23 #ifndef _ASTERISK_TIME_H
24 #define _ASTERISK_TIME_H
25 
26 #include "asterisk/autoconfig.h"
27 
28 #ifdef HAVE_SYS_TIME_H
29 #include <sys/time.h>
30 #endif
31 
32 #ifdef HAVE_UNISTD_H
33 #include <unistd.h>
34 #endif
35 
36 #include "asterisk/inline_api.h"
37 
38 /* A time_t can be represented as an unsigned long long (or uint64_t).
39  * Formatted in base 10, UINT64_MAX is 20 digits long, plus one for NUL.
40  * This should be the size of the receiving char buffer for calls to
41  * ast_time_t_to_string().
42  */
43 #define AST_TIME_T_LEN 21
44 
45 /* We have to let the compiler learn what types to use for the elements of a
46  struct timeval since on linux, it's time_t and suseconds_t, but on *BSD,
47  they are just a long.
48  note:dummy_tv_var_for_types never actually gets exported, only used as
49  local place holder. */
50 extern struct timeval dummy_tv_var_for_types;
51 typedef typeof(dummy_tv_var_for_types.tv_sec) ast_time_t;
52 typedef typeof(dummy_tv_var_for_types.tv_usec) ast_suseconds_t;
53 
54 /*!
55  * \brief Computes the difference (in seconds) between two \c struct \c timeval instances.
56  * \param end the end of the time period
57  * \param start the beginning of the time period
58  * \return the difference in seconds
59  */
61 int64_t ast_tvdiff_sec(struct timeval end, struct timeval start),
62 {
63  int64_t result = end.tv_sec - start.tv_sec;
64  if (result > 0 && end.tv_usec < start.tv_usec)
65  result--;
66  else if (result < 0 && end.tv_usec > start.tv_usec)
67  result++;
68 
69  return result;
70 }
71 )
72 
73 /*!
74  * \brief Computes the difference (in microseconds) between two \c struct \c timeval instances.
75  * \param end the end of the time period
76  * \param start the beginning of the time period
77  * \return the difference in microseconds
78  */
80 int64_t ast_tvdiff_us(struct timeval end, struct timeval start),
81 {
82  return (end.tv_sec - start.tv_sec) * (int64_t) 1000000 +
83  end.tv_usec - start.tv_usec;
84 }
85 )
86 
87 /*!
88  * \brief Computes the difference (in milliseconds) between two \c struct \c timeval instances.
89  * \param end end of the time period
90  * \param start beginning of the time period
91  * \return the difference in milliseconds
92  */
94 int64_t ast_tvdiff_ms(struct timeval end, struct timeval start),
95 {
96  /* the offset by 1,000,000 below is intentional...
97  it avoids differences in the way that division
98  is handled for positive and negative numbers, by ensuring
99  that the divisor is always positive
100  */
101  int64_t sec_dif = (int64_t)(end.tv_sec - start.tv_sec) * 1000;
102  int64_t usec_dif = (1000000 + end.tv_usec - start.tv_usec) / 1000 - 1000;
103  return sec_dif + usec_dif;
104 }
105 )
106 
107 /*!
108  * \brief Returns true if the argument is 0,0
109  */
111 int ast_tvzero(const struct timeval t),
112 {
113  return (t.tv_sec == 0 && t.tv_usec == 0);
114 }
115 )
116 
117 /*!
118  * \brief Compress two \c struct \c timeval instances returning
119  * -1, 0, 1 if the first arg is smaller, equal or greater to the second.
120  */
122 int ast_tvcmp(struct timeval _a, struct timeval _b),
123 {
124  if (_a.tv_sec < _b.tv_sec)
125  return -1;
126  if (_a.tv_sec > _b.tv_sec)
127  return 1;
128  /* now seconds are equal */
129  if (_a.tv_usec < _b.tv_usec)
130  return -1;
131  if (_a.tv_usec > _b.tv_usec)
132  return 1;
133  return 0;
134 }
135 )
136 
137 /*!
138  * \brief Returns true if the two \c struct \c timeval arguments are equal.
139  */
141 int ast_tveq(struct timeval _a, struct timeval _b),
142 {
143  return (_a.tv_sec == _b.tv_sec && _a.tv_usec == _b.tv_usec);
144 }
145 )
146 
147 /*!
148  * \brief Returns current timeval. Meant to replace calls to gettimeofday().
149  */
151 struct timeval ast_tvnow(void),
152 {
153  struct timeval t;
154  gettimeofday(&t, NULL);
155  return t;
156 }
157 )
158 
159 /*!
160  * \brief Returns current timespec. Meant to avoid calling ast_tvnow() just to
161  * create a timespec from the timeval it returns.
162  */
163 #if defined _POSIX_TIMERS && _POSIX_TIMERS > 0
165 struct timespec ast_tsnow(void),
166 {
167  struct timespec ts;
168  clock_gettime(CLOCK_REALTIME, &ts);
169  return ts;
170 }
171 )
172 #else
174 struct timespec ast_tsnow(void),
175 {
176  struct timeval tv = ast_tvnow();
177  struct timespec ts;
178  /* Can't use designated initializer, because it does odd things with
179  * the AST_INLINE_API macro. Go figure. */
180  ts.tv_sec = tv.tv_sec;
181  ts.tv_nsec = tv.tv_usec * 1000;
182  return ts;
183 }
184 )
185 #endif
186 
187 /*!
188  * \brief Returns the sum of two timevals a + b
189  */
190 struct timeval ast_tvadd(struct timeval a, struct timeval b);
191 
192 /*!
193  * \brief Returns the difference of two timevals a - b
194  */
195 struct timeval ast_tvsub(struct timeval a, struct timeval b);
196 
197 /*!
198  * \since 12
199  * \brief Formats a duration into HH:MM:SS
200  *
201  * \param duration The time (in seconds) to format
202  * \param buf A buffer to hold the formatted string'
203  * \param length The size of the buffer
204  */
205 void ast_format_duration_hh_mm_ss(int duration, char *buf, size_t length);
206 
207 
208 /*!
209  * \brief Calculate remaining milliseconds given a starting timestamp
210  * and upper bound
211  *
212  * If the upper bound is negative, then this indicates that there is no
213  * upper bound on the amount of time to wait. This will result in a
214  * negative return.
215  *
216  * \param start When timing started being calculated
217  * \param max_ms The maximum number of milliseconds to wait from start. May be negative.
218  * \return The number of milliseconds left to wait for. May be negative.
219  */
220 int ast_remaining_ms(struct timeval start, int max_ms);
221 
222 /*!
223  * \brief Returns a timeval from sec, usec
224  */
226 struct timeval ast_tv(ast_time_t sec, ast_suseconds_t usec),
227 {
228  struct timeval t;
229  t.tv_sec = sec;
230  t.tv_usec = usec;
231  return t;
232 }
233 )
234 
235 /*!
236  * \brief Returns a timeval corresponding to the duration of n samples at rate r.
237  * Useful to convert samples to timevals, or even milliseconds to timevals
238  * in the form ast_samp2tv(milliseconds, 1000)
239  */
241 struct timeval ast_samp2tv(unsigned int _nsamp, unsigned int _rate),
242 {
243  return ast_tv(_nsamp / _rate, (_nsamp % _rate) * (1000000 / (float) _rate));
244 }
245 )
246 
247 /*!
248  * \brief Time units enumeration.
249  */
250 enum TIME_UNIT {
262 };
263 
264 /*!
265  * \brief Convert a string to a time unit enumeration value.
266  *
267  * This method attempts to be as flexible, and forgiving as possible when
268  * converting. In most cases the algorithm will match on the beginning of
269  * up to three strings (short, medium, long form). So that means if the
270  * given string at least starts with one of the form values it will match.
271  *
272  * For example: us, usec, microsecond will all map to TIME_UNIT_MICROSECOND.
273  * So will uss, usecs, microseconds, or even microsecondvals
274  *
275  * Matching is also not case sensitive.
276  *
277  * \param unit The string to map to an enumeration
278  *
279  * \return A time unit enumeration
280  */
281 enum TIME_UNIT ast_time_str_to_unit(const char *unit);
282 
283 /*!
284  * \brief Convert a timeval structure to microseconds
285  *
286  * \param tv The timeval to convert
287  *
288  * \return The time in microseconds
289  */
290 ast_suseconds_t ast_time_tv_to_usec(const struct timeval *tv);
291 
292 /*!
293  * \brief Create a timeval object initialized to given values.
294  *
295  * \param sec The timeval seconds value
296  * \param usec The timeval microseconds value
297  *
298  * \return A timeval object
299  */
300 struct timeval ast_time_create(ast_time_t sec, ast_suseconds_t usec);
301 
302 /*!
303  * \brief Convert the given unit value, and create a timeval object from it.
304  *
305  * \param val The value to convert to a timeval
306  * \param unit The time unit type of val
307  *
308  * \return A timeval object
309  */
310 struct timeval ast_time_create_by_unit(unsigned long val, enum TIME_UNIT unit);
311 
312 /*!
313  * \brief Convert the given unit value, and create a timeval object from it.
314  *
315  * This will first attempt to convert the unit from a string to a TIME_UNIT
316  * enumeration. If that conversion fails then a zeroed out timeval object
317  * is returned.
318  *
319  * \param val The value to convert to a timeval
320  * \param unit The time unit type of val
321  *
322  * \return A timeval object
323  */
324 struct timeval ast_time_create_by_unit_str(unsigned long val, const char *unit);
325 
326 /*!
327  * \brief Converts to a string representation of a time_t as decimal
328  * seconds since the epoch. Returns -1 on failure, zero otherwise.
329  *
330  * The buffer should be at least 22 bytes long.
331  */
332 int ast_time_t_to_string(time_t time, char *buf, size_t length);
333 
334 /*!
335  * \brief Returns a time_t from a string containing seconds since the epoch.
336  */
337 time_t ast_string_to_time_t(const char *str);
338 
339 #endif /* _ASTERISK_TIME_H */
const char * str
Definition: app_jack.c:147
static PGresult * result
Definition: cel_pgsql.c:84
char * end
Definition: eagi_proxy.c:73
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
Inlinable API function macro.
#define AST_INLINE_API(hdr, body)
Definition: inline_api.h:54
#define NULL
Definition: resample.c:96
Definition: ast_expr2.c:325
static struct test_val b
static struct test_val a
enum TIME_UNIT ast_time_str_to_unit(const char *unit)
Convert a string to a time unit enumeration value.
Definition: time.c:66
typedef typeof(dummy_tv_var_for_types.tv_sec) ast_time_t
int64_t ast_tvdiff_us(struct timeval end, struct timeval start)
Computes the difference (in microseconds) between two struct timeval instances.
Definition: time.h:85
int ast_time_t_to_string(time_t time, char *buf, size_t length)
Converts to a string representation of a time_t as decimal seconds since the epoch....
Definition: time.c:152
struct timeval ast_samp2tv(unsigned int _nsamp, unsigned int _rate)
Returns a timeval corresponding to the duration of n samples at rate r. Useful to convert samples to ...
Definition: time.h:245
struct timespec ast_tsnow(void)
Returns current timespec. Meant to avoid calling ast_tvnow() just to create a timespec from the timev...
Definition: time.h:184
int64_t ast_tvdiff_sec(struct timeval end, struct timeval start)
Computes the difference (in seconds) between two struct timeval instances.
Definition: time.h:71
int ast_tveq(struct timeval _a, struct timeval _b)
Returns true if the two struct timeval arguments are equal.
Definition: time.h:145
time_t ast_string_to_time_t(const char *str)
Returns a time_t from a string containing seconds since the epoch.
Definition: time.c:163
int ast_tvzero(const struct timeval t)
Returns true if the argument is 0,0.
Definition: time.h:115
TIME_UNIT
Time units enumeration.
Definition: time.h:250
@ TIME_UNIT_MONTH
Definition: time.h:260
@ TIME_UNIT_MICROSECOND
Definition: time.h:253
@ TIME_UNIT_WEEK
Definition: time.h:259
@ TIME_UNIT_MINUTE
Definition: time.h:256
@ TIME_UNIT_SECOND
Definition: time.h:255
@ TIME_UNIT_ERROR
Definition: time.h:251
@ TIME_UNIT_YEAR
Definition: time.h:261
@ TIME_UNIT_MILLISECOND
Definition: time.h:254
@ TIME_UNIT_HOUR
Definition: time.h:257
@ TIME_UNIT_DAY
Definition: time.h:258
@ TIME_UNIT_NANOSECOND
Definition: time.h:252
void ast_format_duration_hh_mm_ss(int duration, char *buf, size_t length)
Formats a duration into HH:MM:SS.
Definition: main/utils.c:2195
struct timeval ast_time_create(ast_time_t sec, ast_suseconds_t usec)
Create a timeval object initialized to given values.
Definition: time.c:95
int ast_tvcmp(struct timeval _a, struct timeval _b)
Compress two struct timeval instances returning -1, 0, 1 if the first arg is smaller,...
Definition: time.h:135
struct timeval ast_time_create_by_unit(unsigned long val, enum TIME_UNIT unit)
Convert the given unit value, and create a timeval object from it.
Definition: time.c:113
int ast_remaining_ms(struct timeval start, int max_ms)
Calculate remaining milliseconds given a starting timestamp and upper bound.
Definition: main/utils.c:2179
struct timeval ast_tvadd(struct timeval a, struct timeval b)
Returns the sum of two timevals a + b.
Definition: extconf.c:2282
struct timeval dummy_tv_var_for_types
struct timeval ast_time_create_by_unit_str(unsigned long val, const char *unit)
Convert the given unit value, and create a timeval object from it.
Definition: time.c:143
struct timeval ast_tvsub(struct timeval a, struct timeval b)
Returns the difference of two timevals a - b.
Definition: extconf.c:2297
ast_suseconds_t ast_time_tv_to_usec(const struct timeval *tv)
Convert a timeval structure to microseconds.
Definition: time.c:90
int64_t ast_tvdiff_ms(struct timeval end, struct timeval start)
Computes the difference (in milliseconds) between two struct timeval instances.
Definition: time.h:105
struct timeval ast_tvnow(void)
Returns current timeval. Meant to replace calls to gettimeofday().
Definition: time.h:157
struct timeval ast_tv(ast_time_t sec, ast_suseconds_t usec)
Returns a timeval from sec, usec.
Definition: time.h:233