Provided by: libmseed-doc_2.19.8-1ubuntu2_all bug

NAME

       ms_time - Time conversion and string generation

SYNOPSIS

       #include <libmseed.h>

       MS_EPOCH2HPTIME(X) X * (hptime_t) HPTMODULUS
       MS_HPTIME2EPOCH(X) X / HPTMODULUS

       hptime_t ms_btime2hptime ( BTime *btime );

       char    *ms_btime2isotimestr ( BTime *btime, char *isotimestr );

       char    *ms_btime2mdtimestr ( BTime *btime, char *mdtimestr );

       char    *ms_btime2seedtimestr ( BTime *btime, char *seedtimestr );

       int      ms_hptime2btime ( hptime_t hptime, BTime *btime );

       char    *ms_hptime2isotimestr ( hptime_t hptime, char *isotimestr,
                                       flag subseconds );

       char    *ms_hptime2mdtimestr ( hptime_t hptime, char *mdtimestr,
                                      flag subseconds );

       char    *ms_hptime2seedtimestr ( hptime_t hptime, char *seedtimestr,
                                        flag subseconds );

       hptime_t ms_time2hptime ( int year, int day, int hour, int min,
                                 int sec, int usec );

       hptime_t ms_seedtimestr2hptime ( char *seedtimestr );

       hptime_t ms_timestr2hptime ( char *timestr );

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 INTERNAL HPTIME below for more details.  Also used is the SEED binary  time
       represented by the following data structure (defined in libmseed.h):

       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;

       MS_EPOCH2HPTIME 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.

       MS_HPTIME2EPOCH 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.

       ms_btime2hptime converts a btime to a hptime.

       ms_btime2isotimestr  generates  an  ISO  recommended  format  time  string  from  a btime.
       Example:  '2001-07-29T12:38:00.0000'.   The  isotimestr  must  have  enough  room  for  25
       characters.  The resulting string will be NULL terminated.

       ms_btime2mdtimestr  generates  a  month-day  formatted time string from a btime.  Example:
       '2001-07-29 12:38:00.0000'.  The mdtimestr must have enough room for 25  characters.   The
       resulting string will be NULL terminated.

       ms_btime2seedtimestr  generates  a  SEED  format  time  string  from  a  btime.   Example:
       '2001,195,12:38:00.0000'.  The seedtimestr must have enough room for 23  characters.   The
       resulting string will be NULL terminated.

       ms_hptime2btime  converts  a  hptime  to  a  btime.   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.

       ms_hptime2isotimestr generates an ISO  recommended  format  time  string  from  a  hptime.
       Example:  '2001-07-29T12:38:00.000000' or '2001-07-29T12:38:00'.  The isotimestr must have
       enough room for 27 characters.   The  subseconds  flag  controls  whether  the  sub-second
       precision is included or not.  The resulting string will be NULL terminated.

       ms_hptime2mdtimestr  generates  a month-day formatted time string from a hptime.  Example:
       '2001-07-29 12:38:00.000000' or '2001-07-29 12:38:00'.  The isotimestr  must  have  enough
       room  for 27 characters.  The subseconds flag controls whether the sub-second precision is
       included or not.  The resulting string will be NULL terminated.

       ms_hptime2seedtimestr generates a  SEED  format  time  string  from  a  hptime.   Example:
       '2001,195,12:38:00.000000'  or '2001,195,12:38:00'.  The seedtimestr must have enough room
       for 25 characters.  The subseconds flag  controls  whether  the  sub-second  precision  is
       included or not.  The resulting string will be NULL terminated.

       ms_time2hptime  converts  the  time represented by the specified year, day, hour, min, sec
       and usec (microseconds) to an hptime.  The range expected for each value is as follows:

       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

       NOTE: 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.

       ms_seedtimestr2hptime  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.

       ms_timestr2hptime  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 ms_seedtimestr2hptime and ms_timestr2hptime 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.

RETURN VALUES

       ms_btime2hptime,  ms_time2hptime,  ms_seedtimestr2hptime  and  ms_timestr2hptime  return a
       hptime on success and HPTERROR on error.

       ms_btime2isotimestr,   ms_btime2mdtimestr,   ms_btime2seedtimestr,   ms_hptime2isotimestr,
       ms_hptime2mdtimestr  and ms_hptime2seedtimestr return a pointer to the resulting string or
       NULL on error.

       ms_hptime2btime returns 0 on success and -1 on error.

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 gmtime 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.

ACKNOWLEDGEMENTS

       With software provided by http://2038bug.com/ (site offline, checked Oct. 2017)

AUTHOR

       Chad Trabant
       IRIS Data Management Center