Definitions and functions for related to library time values. More...

Macros
#define	NSTMODULUS 1000000000
	Define the high precision time tick interval as 1/modulus seconds corresponding to nanoseconds.

#define	NSTERROR -2145916800000000000LL
	Error code for routines that normally return a high precision time. The time value corresponds to '1902-01-01T00:00:00.000000000Z'.

#define	NSTUNSET -2145916799999999999LL
	Special nstime_t value meaning "unset". The time value corresponds to '1902-01-01T00:00:00.000000001Z'.

#define	MS_EPOCH2NSTIME(X) (X) * (nstime_t) NSTMODULUS
	macro to convert Unix/POSIX epoch time to high precision epoch time

#define	MS_NSTIME2EPOCH(X) (X) / NSTMODULUS
	Macro to convert high precision epoch time to Unix/POSIX epoch time.

#define	MS_HPTIME2NSTIME(X) (X) * (nstime_t) 1000
	Convert a hptime_t value (used by previous releases) to nstime_t.

#define	MS_NSTIME2HPTIME(X) (X) / 1000
	Convert an nstime_t value to hptime_t (used by previous releases)

Typedefs
typedef int64_t	nstime_t
	libmseed time type, integer nanoseconds since the Unix/POSIX epoch (00:00:00 Thursday, 1 January 1970)

Enumerations
enum	ms_timeformat_t { ISOMONTHDAY = 0 , ISOMONTHDAY_Z = 1 , ISOMONTHDAY_DOY = 2 , ISOMONTHDAY_DOY_Z = 3 , ISOMONTHDAY_SPACE = 4 , ISOMONTHDAY_SPACE_Z = 5 , SEEDORDINAL = 6 , UNIXEPOCH = 7 , NANOSECONDEPOCH = 8 }
	Time format identifiers. More...

enum	ms_subseconds_t { NONE = 0 , MICRO = 1 , NANO = 2 , MICRO_NONE = 3 , NANO_NONE = 4 , NANO_MICRO = 5 , NANO_MICRO_NONE = 6 }
	Subsecond format identifiers. More...

Functions
int	ms_nstime2time (nstime_t nstime, uint16_t year, uint16_t yday, uint8_t hour, uint8_t min, uint8_t sec, uint32_t nsec)
	Convert an nstime_t to individual date-time components.

char *	ms_nstime2timestr (nstime_t nstime, char *timestr, ms_timeformat_t timeformat, ms_subseconds_t subsecond)
	Convert an nstime_t to a time string.

DEPRECATED char *	ms_nstime2timestrz (nstime_t nstime, char *timestr, ms_timeformat_t timeformat, ms_subseconds_t subsecond)
	Convert an nstime_t to a time string with 'Z' suffix.

nstime_t	ms_time2nstime (int year, int yday, int hour, int min, int sec, uint32_t nsec)
	Convert specified date-time values to a high precision epoch time.

nstime_t	ms_timestr2nstime (const char *timestr)
	Convert a time string to a high precision epoch time.

nstime_t	ms_mdtimestr2nstime (const char *timestr)
	Convert a time string (year-month-day) to a high precision epoch time.

nstime_t	ms_seedtimestr2nstime (const char *seedtimestr)
	Convert an SEED-style (ordinate date, i.e. day-of-year) time string to a high precision epoch time.

int	ms_doy2md (int year, int yday, int month, int mday)
	Compute the month and day-of-month from a year and day-of-year.

int	ms_md2doy (int year, int month, int mday, int *yday)
	Compute the day-of-year from a year, month and day-of-month.

Detailed Description

Definitions and functions for related to library time values.

Internally the library uses an integer value to represent time as the number of nanoseconds since the Unix/POSIX epoch (Jan 1 1970).

Macro Definition Documentation

◆ MS_HPTIME2NSTIME

#define MS_HPTIME2NSTIME ( X ) (X) * (nstime_t) 1000

Convert a hptime_t value (used by previous releases) to nstime_t.

An HTPTIME/hptime_t value, used by libmseed major version <= 2, defines microsecond ticks. An NSTIME/nstime_t value, used by this version of the library, defines nanosecond ticks.

◆ MS_NSTIME2HPTIME

#define MS_NSTIME2HPTIME ( X ) (X) / 1000

Convert an nstime_t value to hptime_t (used by previous releases)

An HTPTIME/hptime_t value, used by libmseed major version <= 2, defines microsecond ticks. An NSTIME/nstime_t value, used by this version of the library, defines nanosecond ticks.

Typedef Documentation

◆ nstime_t

typedef int64_t nstime_t

libmseed time type, integer nanoseconds since the Unix/POSIX epoch (00:00:00 Thursday, 1 January 1970)

This time scale can represent a range from before year 0 through mid-year 2262.

Enumeration Type Documentation

◆ ms_timeformat_t

enum ms_timeformat_t

Time format identifiers.

Formats values:

ISOMONTHDAY - "YYYY-MM-DDThh:mm:ss.sssssssss", ISO 8601 in month-day format
ISOMONTHDAY_Z - "YYYY-MM-DDThh:mm:ss.sssssssss", ISO 8601 in month-day format with trailing Z
ISOMONTHDAY_DOY - "YYYY-MM-DD hh:mm:ss.sssssssss (doy)", ISOMONTHDAY with day-of-year
ISOMONTHDAY_DOY_Z - "YYYY-MM-DD hh:mm:ss.sssssssss (doy)", ISOMONTHDAY with day-of-year and trailing Z
ISOMONTHDAY_SPACE - "YYYY-MM-DD hh:mm:ss.sssssssss", same as ISOMONTHDAY with space separator
ISOMONTHDAY_SPACE_Z - "YYYY-MM-DD hh:mm:ss.sssssssss", same as ISOMONTHDAY with space separator and trailing Z
SEEDORDINAL - "YYYY,DDD,hh:mm:ss.sssssssss", SEED day-of-year format
UNIXEPOCH - "ssssssssss.sssssssss", Unix epoch value
NANOSECONDEPOCH - "sssssssssssssssssss", Nanosecond epoch value

◆ ms_subseconds_t

enum ms_subseconds_t

Subsecond format identifiers.

Formats values:

NONE - No subseconds
MICRO - Microsecond resolution
NANO - Nanosecond resolution
MICRO_NONE - Microsecond resolution if subseconds are non-zero, otherwise no subseconds
NANO_NONE - Nanosecond resolution if subseconds are non-zero, otherwise no subseconds
NANO_MICRO - Nanosecond resolution if there are sub-microseconds, otherwise microseconds resolution
NANO_MICRO_NONE - Nanosecond resolution if present, microsecond if present, otherwise no subseconds

Function Documentation

◆ ms_nstime2time()

int ms_nstime2time	(	nstime_t	nstime,
		uint16_t *	year,
		uint16_t *	yday,
		uint8_t *	hour,
		uint8_t *	min,
		uint8_t *	sec,
		uint32_t *	nsec )

extern

Convert an nstime_t to individual date-time components.

Each of the destination date-time are optional, pass NULL if the value is not desired.

Parameters

[in]	nstime	Time value to convert
[out]	year	Year with century, like 2018
[out]	yday	Day of year, 1 - 366
[out]	hour	Hour, 0 - 23
[out]	min	Minute, 0 - 59
[out]	sec	Second, 0 - 60, where 60 is a leap second
[out]	nsec	Nanoseconds, 0 - 999999999

Return values

0	on success
-1	on error

◆ ms_nstime2timestr()

char * ms_nstime2timestr	(	nstime_t	nstime,
		char *	timestr,
		ms_timeformat_t	timeformat,
		ms_subseconds_t	subseconds )

extern

Convert an nstime_t to a time string.

Create a time string representation of a high precision epoch time in ISO 8601 and SEED formats.

The provided timestr buffer must have enough room for the resulting time string, a maximum of 36 characters + terminating NULL.

The subseconds flag controls whether the subsecond portion of the time is included or not. The value of subseconds is ignored when the format is NANOSECONDEPOCH. When non-zero subseconds are "trimmed" using these flags there is no rounding, instead it is simple truncation.

Parameters

[in]	nstime	Time value to convert
[out]	timestr	Buffer for ISO time string
	timeformat	Time string format, one of ms_timeformat_t
	subseconds	Inclusion of subseconds, one of ms_subseconds_t

Returns: Pointer to the resulting string or NULL on error.

MessageOnError - this function logs a message on error

◆ ms_nstime2timestrz()

DEPRECATED char * ms_nstime2timestrz	(	nstime_t	nstime,
		char *	timestr,
		ms_timeformat_t	timeformat,
		ms_subseconds_t	subseconds )

extern

Convert an nstime_t to a time string with 'Z' suffix.

Deprecated: This function should be replaced with desired use of timeformat values with the '_Z' designator.

This function is a thin wrapper of ms_nstime2timestr

Parameters

[in]	nstime	Time value to convert
[out]	timestr	Buffer for ISO time string
	timeformat	Time string format, one of ms_timeformat_t
	subseconds	Inclusion of subseconds, one of ms_subseconds_t

Returns: Pointer to the resulting string or NULL on error.

MessageOnError - this function logs a message on error

◆ ms_time2nstime()

nstime_t ms_time2nstime	(	int	year,
		int	yday,
		int	hour,
		int	min,
		int	sec,
		uint32_t	nsec )

extern

Convert specified date-time values to a high precision epoch time.

Parameters

[in]	year	Year with century, like 2018
[in]	yday	Day of year, 1 - 366
[in]	hour	Hour, 0 - 23
[in]	min	Minute, 0 - 59
[in]	sec	Second, 0 - 60, where 60 is a leap second
[in]	nsec	Nanoseconds, 0 - 999999999

Returns: epoch time on success and NSTERROR on error.

MessageOnError - this function logs a message on error

◆ ms_timestr2nstime()

nstime_t ms_timestr2nstime ( const char * timestr )

extern

Convert a time string to a high precision epoch time.

Detected time formats:

ISO month-day as "YYYY-MM-DD[THH:MM:SS.FFFFFFFFF]"
ISO ordinal as "YYYY-DDD[THH:MM:SS.FFFFFFFFF]"
SEED ordinal as "YYYY,DDD[,HH,MM,SS,FFFFFFFFF]"
Year as "YYYY"
Unix/POSIX epoch time value as "[+-]#########.#########"

Following determination of the format, non-epoch value conversion is performed by the ms_mdtimestr2nstime() and ms_seedtimestr2nstime() routines.

Four-digit values are treated as a year, unless a sign [+-] is specified and then they are treated as epoch values. For consistency, a caller is recommened to always include a sign with epoch values.

Note that this routine does some sanity checking of the time string contents, but does not perform robust date-time validation.

Parameters

[in] timestr Time string to convert

Returns: epoch time on success and NSTERROR on error.

MessageOnError - this function logs a message on error

See also: ms_mdtimestr2nstime(); ms_seedtimestr2nstime()

◆ ms_mdtimestr2nstime()

nstime_t ms_mdtimestr2nstime ( const char * timestr )

extern

Convert a time string (year-month-day) to a high precision epoch time.

The time format expected is "YYYY[-MM-DD HH:MM:SS.FFFFFFFFF]", 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 ("FFFFFFFFF") must begin with a period [.] if present.

The time string can be "short" in which case the omitted values are assumed to be zero (with the exception of month and day which are assumed to be 1). For example, specifying "YYYY-MM-DD" assumes HH, MM, SS and FFFF are 0. The year is required, otherwise there wouldn't be much for a date.

Parameters

[in] timestr Time string in ISO-style, month-day format

Returns: epoch time on success and NSTERROR on error.

MessageOnError - this function logs a message on error

◆ ms_seedtimestr2nstime()

nstime_t ms_seedtimestr2nstime ( const char * seedtimestr )

extern

Convert an SEED-style (ordinate date, i.e. day-of-year) time string to a high precision epoch time.

The time format expected is "YYYY[,DDD,HH,MM,SS.FFFFFFFFF]", the delimiter can be a dash [-], comma [,], colon [:] or period [.]. Additionally a [T] or space may be used to seprate the day and hour fields. The fractional seconds ("FFFFFFFFF") must begin with a period [.] if present.

The time string can be "short" in which case the omitted values are assumed to be zero (with the exception of DDD which is assumed to be 1): "YYYY,DDD,HH" assumes MM, SS and FFFFFFFF are 0. The year is required, otherwise there wouldn't be much for a date.

Parameters

[in] seedtimestr Time string in SEED-style, ordinal date format

Returns: epoch time on success and NSTERROR on error.

MessageOnError - this function logs a message on error

◆ ms_doy2md()

int ms_doy2md	(	int	year,
		int	yday,
		int *	month,
		int *	mday )

extern

Compute the month and day-of-month from a year and day-of-year.

Parameters

[in]	year	Year in range 1000-2262
[in]	yday	Day of year in range 1-365 or 366 for leap year
[out]	month	Month in range 1-12
[out]	mday	Day of month in range 1-31

Return values

0	on success
-1	on error

MessageOnError - this function logs a message on error

◆ ms_md2doy()

int ms_md2doy	(	int	year,
		int	month,
		int	mday,
		int *	yday )

extern

Compute the day-of-year from a year, month and day-of-month.

Parameters

[in]	year	Year in range 1000-2262
[in]	month	Month in range 1-12
[in]	mday	Day of month in range 1-31 (or appropriate last day)
[out]	yday	Day of year in range 1-366 or 366 for leap year

Return values

0	on success
-1	on error

MessageOnError - this function logs a message on error

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MS_HPTIME2NSTIME

◆ MS_NSTIME2HPTIME

Typedef Documentation

◆ nstime_t

Enumeration Type Documentation

◆ ms_timeformat_t

◆ ms_subseconds_t

Function Documentation

◆ ms_nstime2time()

◆ ms_nstime2timestr()

◆ ms_nstime2timestrz()

◆ ms_time2nstime()

◆ ms_timestr2nstime()

◆ ms_mdtimestr2nstime()

◆ ms_seedtimestr2nstime()

◆ ms_doy2md()

◆ ms_md2doy()