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 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
|
.TH MS_TIME 3 2013/02/22 "Libmseed API"
.SH NAME
ms_time - Time conversion and string generation
.SH SYNOPSIS
.nf
.B #include <libmseed.h>
.BI "MS_EPOCH2HPTIME(X) X * (hptime_t) HPTMODULUS"
.BI "MS_HPTIME2EPOCH(X) X / HPTMODULUS"
.BI "hptime_t \fBms_btime2hptime\fP ( BTime *" btime " );"
.BI "char *\fBms_btime2isotimestr\fP ( BTime *" btime ", char *" isotimestr " );"
.BI "char *\fBms_btime2mdtimestr\fP ( BTime *" btime ", char *" mdtimestr " );"
.BI "char *\fBms_btime2seedtimestr\fP ( BTime *" btime ", char *" seedtimestr " );"
.BI "int \fBms_hptime2btime\fP ( hptime_t " hptime ", BTime *" btime " );"
.BI "char *\fBms_hptime2isotimestr\fP ( hptime_t " hptime ", char *" isotimestr ","
.BI " flag " subseconds " );"
.BI "char *\fBms_hptime2mdtimestr\fP ( hptime_t " hptime ", char *" mdtimestr ","
.BI " flag " subseconds " );"
.BI "char *\fBms_hptime2seedtimestr\fP ( hptime_t " hptime ", char *" seedtimestr ","
.BI " flag " subseconds " );"
.BI "hptime_t \fBms_time2hptime\fP ( int " year ", int " day ", int " hour ", int " min ","
.BI " int " sec ", int " usec " );"
.BI "hptime_t \fBms_seedtimestr2hptime\fP ( char *" seedtimestr " );"
.BI "hptime_t \fBms_timestr2hptime\fP ( char *" timestr " );"
.fi
.SH DESCRIPTION
These routines convert between various time formats. Internally,
libmseed represents time values as high precision epoch times
(hptime), the number of ticks from the epoch: 00:00:00.00 1 January
1970. By default a tick is defined as a microsecond (0.000001
seconds). See \fBINTERNAL HPTIME\fP below for more details. Also
used is the SEED binary time represented by the following data
structure (defined in libmseed.h):
.sp
.nf
typedef struct btime_s
{
uint16_t year; /* year with century */
uint16_t day; /* day, 1 - 366 */
uint8_t hour; /* hour, 0 - 23 */
uint8_t min; /* minute, 0 - 59 */
uint8_t sec; /* second, 0 - 60 (60 = leap second) */
uint8_t unused; /* unused alignment byte */
uint16_t fract; /* fractional seconds, 0 - 9999 */
} BTime;
.fi
\fBMS_EPOCH2HPTIME\fP is a macro which converts a Unix/POSIX epoch
time (elapsed seconds since 1 January 1970) to a hptime which are
related by a simple scaling factor.
\fBMS_HPTIME2EPOCH\fP is a macro which converts an hptime to a
Unix/POSIX epoch time (elapsed seconds since 1 January 1970) which are
related by a simple scaling factor. The result can be cast to an
integer, in which cast no rounding is performed and sub-second
precision is truncated, or can be cast into a double to get a double
precision epoch time.
\fBms_btime2hptime\fP converts a \fIbtime\fP to a hptime.
\fBms_btime2isotimestr\fP generates an ISO recommended format time
string from a \fIbtime\fP. Example: '2001-07-29T12:38:00.0000'. The
\fIisotimestr\fP must have enough room for 25 characters. The
resulting string will be NULL terminated.
\fBms_btime2mdtimestr\fP generates a month-day formatted time string
from a \fIbtime\fP. Example: '2001-07-29 12:38:00.0000'. The
\fImdtimestr\fP must have enough room for 25 characters. The
resulting string will be NULL terminated.
\fBms_btime2seedtimestr\fP generates a SEED format time string from a
\fIbtime\fP. Example: '2001,195,12:38:00.0000'. The
\fIseedtimestr\fP must have enough room for 23 characters. The
resulting string will be NULL terminated.
\fBms_hptime2btime\fP converts a \fIhptime\fP to a \fIbtime\fP. By
default, hptime has microsecond precision whereas a BTime structure
can only represent time to 0.0001 seconds. The precision will be lost
during this conversion, it will not be accounted for by rounding but
will be truncated. This behavior is by design.
\fBms_hptime2isotimestr\fP generates an ISO recommended format time
string from a \fIhptime\fP. Example: '2001-07-29T12:38:00.000000'
or '2001-07-29T12:38:00'. The \fIisotimestr\fP must have enough room
for 27 characters. The \fIsubseconds\fP flag controls whether the
sub-second precision is included or not. The resulting string will be
NULL terminated.
\fBms_hptime2mdtimestr\fP generates a month-day formatted time string
from a \fIhptime\fP. Example: '2001-07-29 12:38:00.000000'
or '2001-07-29 12:38:00'. The \fIisotimestr\fP must have enough room
for 27 characters. The \fIsubseconds\fP flag controls whether the
sub-second precision is included or not. The resulting string will be
NULL terminated.
\fBms_hptime2seedtimestr\fP generates a SEED format time string from a
\fIhptime\fP. Example: '2001,195,12:38:00.000000'
or '2001,195,12:38:00'. The \fIseedtimestr\fP must have enough room
for 25 characters. The \fIsubseconds\fP flag controls whether the
sub-second precision is included or not. The resulting string will be
NULL terminated.
\fBms_time2hptime\fP converts the time represented by the specified
\fIyear\fP, \fIday\fP, \fIhour\fP, \fImin\fP, \fIsec\fP and \fIusec\fP
(microseconds) to an hptime. The range expected for each value is as
follows:
.sp
.nf
year : 1800 - 5000
day : 1 - 366 (366 = last day of leap year)
hour : 0 - 23
min : 0 - 59
sec : 0 - 60 (60 = leap second)
usec : 0 - 999999
.fi
\fBNOTE:\fP miniSEED data records are only supported by limbseed with
a year range between 1900 and 2100. These routines allow a wider
range to support times for metadata, etc.
\fBms_seedtimestr2hptime\fP converts a SEED time string (day-of-year
style) to a high precision epoch time. The time format expected is
"YYYY[,DDD,HH,MM,SS.FFFFFF]", the delimiter can be a comma [,], dash
[-], colon [:] or period [.]. Additionally a 'T' or space may be used
to seprate the day and hour fields. The fractional seconds ("FFFFFF")
must begin with a period [.] if present.
\fBms_timestr2hptime\fP converts a generic time string to a high
precision epoch time. SEED time format is
"YYYY[/MM/DD HH:MM:SS.FFFF]", the delimiter can be a dash [-],
comma[,], slash [/], colon [:], or period [.]. Additionally a 'T' or
space may be used between the date and time fields. The fractional
seconds ("FFFFFF") must begin with a period [.] if present.
For both \fBms_seedtimestr2hptime\fP and \fBms_timestr2hptime\fP the
input time string may be "short", in which case the vales omitted on
the right hand side are assumed to be 0 (with the exception of month
and day which are assumed to be 1). The year is always required.
This characteristic means that these time string parsers are very
lenient and should not be used for validation or considered to be
applying any strict validation.
.SH RETURN VALUES
\fBms_btime2hptime\fP, \fBms_time2hptime\fP,
\fBms_seedtimestr2hptime\fP and \fBms_timestr2hptime\fP return a
hptime on success and HPTERROR on error.
\fBms_btime2isotimestr\fP, \fBms_btime2mdtimestr\fP,
\fBms_btime2seedtimestr\fP, \fBms_hptime2isotimestr\fP,
\fBms_hptime2mdtimestr\fP and \fBms_hptime2seedtimestr\fP return a
pointer to the resulting string or NULL on error.
\fBms_hptime2btime\fP returns 0 on success and -1 on error.
.SH INTERNAL HPTIME
The time values internal to libmseed are defined as the number of
ticks from the epoch: 00:00:00.00 1 January 1970 and often referred to
as hptime. By default a tick is defined as a microsecond (0.000001
seconds). The tick interval, and thus hptime precision, is controlled
by the definition of HPTMODULUS in libmseed.h. It is not recommended
to change HPTMODULUS from the default value of 1000000.
This epoch time system is similar to the Unix/POSIX epoch times except
that the ticks are higher precision than the 1-second ticks used in
POSIX. An hptime can always be converted to a Unix/POSIX epoch time
by dividing hptime by HPTMODULUS (reducing the hptime to second
precision) and vise-versa, see the documentation for the
MS_HPTIME2EPOCH and MS_EPOCH2HPTIME macros above.
As long as the system's \fPgmtime\fP function supports negative epoch
times the internal time routines will be able to represent times
earlier than the epoch, i.e. times earlier than 1 January 1970.
The hptime values are stored as 64-bit integers to allow high
precision and avoid accumulation errors associated with floating point
values.
A special value defined as HPTERROR in libmseed.h is used to represent
errors for routines returning hptime.
.SH ACKNOWLEDGEMENTS
With software provided by http://2038bug.com/ (site offline, checked Oct. 2017)
.SH AUTHOR
.nf
Chad Trabant
IRIS Data Management Center
.fi
|