1MS_TIME(3) Library Functions Manual MS_TIME(3)
2
6 ms_time - Time conversion and string generation
7
10 #include <libmseed.h>
11 MS_EPOCH2HPTIME(X) X * (hptime_t) HPTMODULUS
13 MS_HPTIME2EPOCH(X) X / HPTMODULUS
14 hptime_t ms_btime2hptime ( BTime *btime );
16 char *ms_btime2isotimestr ( BTime *btime, char *isotimestr );
18 char *ms_btime2mdtimestr ( BTime *btime, char *mdtimestr );
20 char *ms_btime2seedtimestr ( BTime *btime, char *seedtimestr );
22 int ms_hptime2btime ( hptime_t hptime, BTime *btime );
24 char *ms_hptime2isotimestr ( hptime_t hptime, char *isotimestr,
26 flag subseconds );
27 char *ms_hptime2mdtimestr ( hptime_t hptime, char *mdtimestr,
29 flag subseconds );
30 char *ms_hptime2seedtimestr ( hptime_t hptime, char *seedtimestr,
32 flag subseconds );
33 hptime_t ms_time2hptime ( int year, int day, int hour, int min,
35 int sec, int usec );
36 hptime_t ms_seedtimestr2hptime ( char *seedtimestr );
38 hptime_t ms_timestr2hptime ( char *timestr );
40
43 These routines convert between various time formats. Internally, libm‐
44 seed represents time values as high precision epoch times (hptime), the
45 number of ticks from the epoch: 00:00:00.00 1 January 1970. By default
46 a tick is defined as a microsecond (0.000001 seconds). See INTERNAL
47 HPTIME below for more details. Also used is the SEED binary time rep‐
48 resented by the following data structure (defined in libmseed.h):
49 typedef struct btime_s
51 {
52 uint16_t year; /* year with century */
53 uint16_t day; /* day, 1 - 366 */
54 uint8_t hour; /* hour, 0 - 23 */
55 uint8_t min; /* minute, 0 - 59 */
56 uint8_t sec; /* second, 0 - 60 (60 = leap second) */
57 uint8_t unused; /* unused alignment byte */
58 uint16_t fract; /* fractional seconds, 0 - 9999 */
59 } BTime;
60 MS_EPOCH2HPTIME is a macro which converts a Unix/POSIX epoch time
62 (elapsed seconds since 1 January 1970) to a hptime which are related by
63 a simple scaling factor.
64 MS_HPTIME2EPOCH is a macro which converts an hptime to a Unix/POSIX
66 epoch time (elapsed seconds since 1 January 1970) which are related by
67 a simple scaling factor. The result can be cast to an integer, in
68 which cast no rounding is performed and sub-second precision is trun‐
69 cated, or can be cast into a double to get a double precision epoch
70 time.
71 ms_btime2hptime converts a btime to a hptime.
73 ms_btime2isotimestr generates an ISO recommended format time string
75 from a btime. Example: '2001-07-29T12:38:00.0000'. The isotimestr
76 must have enough room for 25 characters. The resulting string will be
77 NULL terminated.
78 ms_btime2mdtimestr generates a month-day formatted time string from a
80 btime. Example: '2001-07-29 12:38:00.0000'. The mdtimestr must have
81 enough room for 25 characters. The resulting string will be NULL ter‐
82 minated.
83 ms_btime2seedtimestr generates a SEED format time string from a btime.
85 Example: '2001,195,12:38:00.0000'. The seedtimestr must have enough
86 room for 23 characters. The resulting string will be NULL terminated.
87 ms_hptime2btime converts a hptime to a btime. By default, hptime has
89 microsecond precision whereas a BTime structure can only represent time
90 to 0.0001 seconds. The precision will be lost during this conversion,
91 it will not be accounted for by rounding but will be truncated. This
92 behavior is by design.
93 ms_hptime2isotimestr generates an ISO recommended format time string
95 from a hptime. Example: '2001-07-29T12:38:00.000000' or
96 '2001-07-29T12:38:00'. The isotimestr must have enough room for 27
97 characters. The subseconds flag controls whether the sub-second preci‐
98 sion is included or not. The resulting string will be NULL terminated.
99 ms_hptime2mdtimestr generates a month-day formatted time string from a
101 hptime. Example: '2001-07-29 12:38:00.000000' or '2001-07-29
102 12:38:00'. The isotimestr must have enough room for 27 characters.
103 The subseconds flag controls whether the sub-second precision is
104 included or not. The resulting string will be NULL terminated.
105 ms_hptime2seedtimestr generates a SEED format time string from a
107 hptime. Example: '2001,195,12:38:00.000000' or '2001,195,12:38:00'.
108 The seedtimestr must have enough room for 25 characters. The subsec‐
109 onds flag controls whether the sub-second precision is included or not.
110 The resulting string will be NULL terminated.
111 ms_time2hptime converts the time represented by the specified year,
113 day, hour, min, sec and usec (microseconds) to an hptime. The range
114 expected for each value is as follows:
115 year : 1800 - 5000
117 day : 1 - 366 (366 = last day of leap year)
118 hour : 0 - 23
119 min : 0 - 59
120 sec : 0 - 60 (60 = leap second)
121 usec : 0 - 999999
122 NOTE: miniSEED data records are only supported by limbseed with a year
124 range between 1900 and 2100. These routines allow a wider range to
125 support times for metadata, etc.
126 ms_seedtimestr2hptime converts a SEED time string (day-of-year style)
128 to a high precision epoch time. The time format expected is
129 "YYYY[,DDD,HH,MM,SS.FFFFFF]", the delimiter can be a comma [,], dash
130 [-], colon [:] or period [.]. Additionally a 'T' or space may be used
131 to seprate the day and hour fields. The fractional seconds ("FFFFFF")
132 must begin with a period [.] if present.
133 ms_timestr2hptime converts a generic time string to a high precision
135 epoch time. SEED time format is "YYYY[/MM/DD HH:MM:SS.FFFF]", the
136 delimiter can be a dash [-], comma[,], slash [/], colon [:], or period
137 [.]. Additionally a 'T' or space may be used between the date and time
138 fields. The fractional seconds ("FFFFFF") must begin with a period [.]
139 if present.
140 For both ms_seedtimestr2hptime and ms_timestr2hptime the input time
142 string may be "short", in which case the vales omitted on the right
143 hand side are assumed to be 0 (with the exception of month and day
144 which are assumed to be 1). The year is always required. This charac‐
145 teristic means that these time string parsers are very lenient and
146 should not be used for validation or considered to be applying any
147 strict validation.
148
151 ms_btime2hptime, ms_time2hptime, ms_seedtimestr2hptime and
152 ms_timestr2hptime return a hptime on success and HPTERROR on error.
153 ms_btime2isotimestr, ms_btime2mdtimestr, ms_btime2seedtimestr,
155 ms_hptime2isotimestr, ms_hptime2mdtimestr and ms_hptime2seedtimestr
156 return a pointer to the resulting string or NULL on error.
157 ms_hptime2btime returns 0 on success and -1 on error.
159
162 The time values internal to libmseed are defined as the number of ticks
163 from the epoch: 00:00:00.00 1 January 1970 and often referred to as
164 hptime. By default a tick is defined as a microsecond (0.000001 sec‐
165 onds). The tick interval, and thus hptime precision, is controlled by
166 the definition of HPTMODULUS in libmseed.h. It is not recommended to
167 change HPTMODULUS from the default value of 1000000.
168 This epoch time system is similar to the Unix/POSIX epoch times except
170 that the ticks are higher precision than the 1-second ticks used in
171 POSIX. An hptime can always be converted to a Unix/POSIX epoch time by
172 dividing hptime by HPTMODULUS (reducing the hptime to second precision)
173 and vise-versa, see the documentation for the MS_HPTIME2EPOCH and
174 MS_EPOCH2HPTIME macros above.
175 As long as the system's gmtime function supports negative epoch times
177 the internal time routines will be able to represent times earlier than
178 the epoch, i.e. times earlier than 1 January 1970.
179 The hptime values are stored as 64-bit integers to allow high precision
181 and avoid accumulation errors associated with floating point values.
182 A special value defined as HPTERROR in libmseed.h is used to represent
184 errors for routines returning hptime.
185
188 With software provided by http://2038bug.com/ (site offline, checked
189 Oct. 2017)
190
193 Chad Trabant
194 IRIS Data Management Center
195Libmseed API 2013/02/22 MS_TIME(3)