Leap Second Handling

Utilities for handling leap seconds. More...

Data Structures
struct	LeapSecond
	Leap second list container. More...

Functions
int	ms_readleapseconds (const char *envvarname)
	Read leap second file specified by an environment variable.
int	ms_readleapsecondfile (const char *filename)
	Read leap second from the specified file.

Variables
LeapSecond *	leapsecondlist

Detailed Description

Utilities for handling leap seconds.

Note

The library contains an embedded list of leap seconds through year 2023. These functions are only needed if leap seconds are added in 2024 and beyond.

The library contains functionality to load a list of leap seconds into a global list, which is then used to determine when leap seconds occurred, ignoring any flags in the data itself regarding leap seconds. This is useful as past leap seconds are well known and leap second indicators in data are, historically, more often wrong than otherwise.

The library uses the leap second list (and any flags in the data, if no list is provided) to adjust the calculated time of the last sample in a record. This allows proper merging of continuous series generated through leap seconds.

Normally, calling programs do not need to do any particular handling of leap seconds after loading the leap second list.

Note

The library's internal, epoch-based time representation cannot distinguish a leap second. On the epoch time scale a leap second appears as repeat of the second that follows it, an apparent duplicated second. Since the library does not know if this value is a leap second or not, when converted to a time string, the non-leap second representation is used, i.e. no second values of "60" are generated.

---

Data Structure Documentation

LeapSecond

struct LeapSecond

Leap second list container.

Data Fields
nstime_t	leapsecond	Time of leap second as epoch since 1 January 1900.
int32_t	TAIdelta	TAI-UTC difference in seconds.
struct LeapSecond *	next	Pointer to next entry, NULL if the last.

Function Documentation

ms_readleapseconds()

int ms_readleapseconds ( const char * envvarname )

extern

Read leap second file specified by an environment variable.

Leap seconds are loaded into the library's global leapsecond list.

Parameters

[in]

envvarname

Environment variable that identifies the leap second file

Returns

positive number of leap seconds read

Return values

-1	on file read error
-2	when the environment variable is not set

MessageOnError - this function logs a message on error

ms_readleapsecondfile()

int ms_readleapsecondfile ( const char * filename )

extern

Read leap second from the specified file.

Leap seconds are loaded into the library's global leapsecond list.

The file is expected to be in NTP leap second list format. Some locations where this file can be obtained are indicated in RFC 8633 section 3.7: https://www.rfc-editor.org/rfc/rfc8633.html#section-3.7

Parameters

[in]

filename

File containing leap second list

Returns

positive number of leap seconds read on success

Return values

-1

on error

MessageOnError - this function logs a message on error

Variable Documentation

leapsecondlist

LeapSecond* leapsecondlist

extern

Global leap second list