MS_TIME(3)

💖 NAME 💖

okay bestie, welcome to MS_TIME(3) from the Library Functions Manual — yes, the whole page is about time, and it's giving Time conversion and string generation energy. No cap.

ms_time - Time conversion and string generation

✨ SYNOPSIS ✨

here's the include and every single signature, copied character for character because we do not play with prototypes in this house:

#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 🌸

so 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;

now the functions and macros, one by one, because we leave no detail behind:

• MS_EPOCH2HPTIME — a macro that converts a Unix/POSIX epoch time (elapsed seconds since 1 January 1970) to a hptime, and they're related by a simple scaling factor. iconic behavior.
• MS_HPTIME2EPOCH — a macro that converts an hptime to a Unix/POSIX epoch time (elapsed seconds since 1 January 1970), also related by a simple scaling factor. You can cast the result to an integer — in that cast, no rounding is performed and sub-second precision is truncated — or you can cast it into a double to get a double precision epoch time. choose your destiny.
• 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. periodt.
• 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. so don't use them as your bouncer, bestie.

🫶 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. like, leave it alone, she's doing great.

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. throwback era, literally.

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

okay bestie, that's the whole page. this absolute icon is from the Libmseed API, dated 2013/02/22, and its manual page name is MS_TIME(3). go forth and convert time, you gorgeous nerd 💖✨🦋👑