wsutil/nstime.h

   1 /* nstime.h
   2  * Definition of data structure to hold time values with nanosecond resolution
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11 #ifndef __NSTIME_H__
  12 #define __NSTIME_H__
  13
  14 #include <wireshark.h>
  15 #include <time.h>
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif /* __cplusplus */
  20
  21 /** @file
  22  * Definition of data structure to hold time values with nanosecond resolution
  23  */
  24
  25 /** data structure to hold time values with nanosecond resolution*/
  26 typedef struct {
  27         time_t  secs;
  28         int     nsecs;
  29 } nstime_t;
  30
  31 /* Macros that expand to nstime_t initializers */
  32
  33 /* Initialize to zero */
  34 #define NSTIME_INIT_ZERO {0, 0}
  35
  36 /* Initialize to unset */
  37 #define NSTIME_INIT_UNSET {0, INT_MAX}
  38
  39 /* Initialize to a specified number of seconds and nanoseconds */
  40 #define NSTIME_INIT_SECS_NSECS(secs, nsecs)     {secs, nsecs}
  41
  42 /* Initialize to a specified number of seconds and microseconds */
  43 #define NSTIME_INIT_SECS_USECS(secs, usecs)     {secs, usecs*1000}
  44
  45 /* Initialize to a specified number of seconds and milliseconds */
  46 #define NSTIME_INIT_SECS_MSECS(secs, msecs)     {secs, msecs*1000000}
  47
  48 /* Initialize to a specified number of seconds */
  49 #define NSTIME_INIT_SECS(secs)                  {secs, 0}
  50
  51 /* Initialize to the maximum possible value */
  52 #define NSTIME_INIT_MAX {sizeof(time_t) > sizeof(int) ? LONG_MAX : INT_MAX, INT_MAX}
  53
  54 /* functions */
  55
  56 /** set the given nstime_t to zero */
  57 WS_DLL_PUBLIC void nstime_set_zero(nstime_t *nstime);
  58
  59 /** is the given nstime_t currently zero? */
  60 WS_DLL_PUBLIC bool nstime_is_zero(const nstime_t *nstime);
  61
  62 /** set the given nstime_t to (0,maxint) to mark it as "unset"
  63  * That way we can find the first frame even when a timestamp
  64  * is zero (fix for bug 1056)
  65  */
  66 WS_DLL_PUBLIC void nstime_set_unset(nstime_t *nstime);
  67
  68 /* is the given nstime_t currently (0,maxint)? */
  69 WS_DLL_PUBLIC bool nstime_is_unset(const nstime_t *nstime);
  70
  71 /** duplicate the current time
  72  *
  73  * a = b
  74  */
  75 WS_DLL_PUBLIC void nstime_copy(nstime_t *a, const nstime_t *b);
  76
  77 /** calculate the delta between two times (can be negative!)
  78  *
  79  * delta = b-a
  80  *
  81  * Note that it is acceptable for two or more of the arguments to point at the
  82  * same structure.
  83  */
  84 WS_DLL_PUBLIC void nstime_delta(nstime_t *delta, const nstime_t *b, const nstime_t *a );
  85
  86 /** calculate the sum of two times
  87  *
  88  * sum = a+b
  89  *
  90  * Note that it is acceptable for two or more of the arguments to point at the
  91  * same structure.
  92  */
  93 WS_DLL_PUBLIC void nstime_sum(nstime_t *sum, const nstime_t *a, const nstime_t *b );
  94
  95 /** sum += a */
  96 #define nstime_add(sum, a) nstime_sum(sum, sum, a)
  97
  98 /** sum -= a */
  99 #define nstime_subtract(sum, a) nstime_delta(sum, sum, a)
 100
 101 /** compare two times are return a value similar to memcmp() or strcmp().
 102  *
 103  * a > b : > 0
 104  * a = b : 0
 105  * a < b : < 0
 106  */
 107 WS_DLL_PUBLIC int nstime_cmp (const nstime_t *a, const nstime_t *b );
 108
 109 WS_DLL_PUBLIC unsigned nstime_hash(const nstime_t *nstime);
 110
 111 /** converts nstime to double, time base is milli seconds */
 112 WS_DLL_PUBLIC double nstime_to_msec(const nstime_t *nstime);
 113
 114 /** converts nstime to double, time base is seconds */
 115 WS_DLL_PUBLIC double nstime_to_sec(const nstime_t *nstime);
 116
 117 /** converts Windows FILETIME to nstime, returns true on success,
 118     false on failure */
 119 WS_DLL_PUBLIC bool filetime_to_nstime(nstime_t *nstime, uint64_t filetime);
 120
 121 /** converts time like Windows FILETIME, but expressed in nanoseconds
 122     rather than tenths of microseconds, to nstime, returns true on success,
 123     false on failure */
 124 WS_DLL_PUBLIC bool filetime_ns_to_nstime(nstime_t *nstime, uint64_t nsfiletime);
 125
 126 /** converts time like Windows FILETIME, but expressed in seconds
 127     rather than tenths of microseconds, to nstime, returns true on success,
 128     false on failure */
 129 WS_DLL_PUBLIC bool filetime_1sec_to_nstime(nstime_t *nstime, uint64_t filetime);
 130
 131 typedef enum {
 132     ISO8601_DATETIME,       /** e.g. 2014-07-04T12:34:56.789+00:00 */
 133     ISO8601_DATETIME_BASIC, /** ISO8601 Basic format, i.e. no - : separators */
 134     ISO8601_DATETIME_AUTO,  /** Autodetect the presence of separators */
 135 } iso8601_fmt_e;
 136
 137 /** parse an ISO 8601 format datetime string to nstime, returns pointer
 138     to the first character after the last character, NULL on failure
 139     Note that nstime is set to unset in the case of failure */
 140 WS_DLL_PUBLIC const char * iso8601_to_nstime(nstime_t *nstime, const char *ptr, iso8601_fmt_e format);
 141
 142 /** parse an Unix epoch timestamp format datetime string to nstime, returns
 143     pointer to the first character after the last character, NULL on failure
 144     Note that nstime is set to unset in the case of failure */
 145 WS_DLL_PUBLIC const char * unix_epoch_to_nstime(nstime_t *nstime, const char *ptr);
 146
 147 #define NSTIME_ISO8601_BUFSIZE  sizeof("YYYY-MM-DDTHH:MM:SS.123456789Z")
 148
 149 WS_DLL_PUBLIC size_t nstime_to_iso8601(char *buf, size_t buf_size, const nstime_t *nstime);
 150
 151 /* 64 bit signed number plus nanosecond fractional part */
 152 #define NSTIME_UNIX_BUFSIZE  (20+10+1)
 153
 154 WS_DLL_PUBLIC void nstime_to_unix(char *buf, size_t buf_size, const nstime_t *nstime);
 155
 156 /*
 157  * Timestamp precision values.
 158  *
 159  * The value is the number of digits of precision after the integral part.
 160  */
 161 typedef enum {
 162     WS_TSPREC_SEC      = 0,
 163     WS_TSPREC_100_MSEC = 1,
 164     WS_TSPREC_10_MSEC  = 2,
 165     WS_TSPREC_MSEC     = 3,
 166     WS_TSPREC_100_USEC = 4,
 167     WS_TSPREC_10_USEC  = 5,
 168     WS_TSPREC_USEC     = 6,
 169     WS_TSPREC_100_NSEC = 7,
 170     WS_TSPREC_10_NSEC  = 8,
 171     WS_TSPREC_NSEC     = 9
 172 } ws_tsprec_e;
 173
 174 /*
 175  * Maximum time stamp precision supported.
 176  * Note that going beyond nanosecond precision would require expanding
 177  * the fractional part of an nstime_t to 64 bits, and changing code
 178  * that currently only handles second to nanosecond precision.
 179  */
 180 #define WS_TSPREC_MAX 9
 181
 182 /*
 183  * Total number of valid precision values.
 184  */
 185 #define NUM_WS_TSPREC_VALS (WS_TSPREC_MAX + 1)
 186
 187 #ifdef __cplusplus
 188 }
 189 #endif /* __cplusplus */
 190
 191 #endif /* __NSTIME_H__  */