iers.c File Reference

Macros
#define	IERS_DATACENTER   "datacenter.iers.org"
	IERS EOP server name.

Functions
int	novas_fetch_eop (double jd, long timeout_millis, novas_eop *eop)
	Obtains interpolated Earth Orientation Parameter data from the International Earth Rotation and Reference Systems Service (IERS).
int	novas_fetch_eop_unix (time_t t, long timeout_millis, novas_eop *eop)
	Obtains interpolated Earth Orientation Parameter data from the International Earth Rotation and Reference Systems Service (IERS) around the current system time, using the rapid service data (finals.all).
int	novas_get_eop_itrf_year (enum novas_eop_series series)
	Returns the ITRF realization year for a given IERS Earth Orientation Parameter (EOP) series.
const char *	novas_get_eop_url (enum novas_eop_series series)
	Returns the URL currently configured for a given IERS Earth Orientation Parameter (EOP) series.
int	novas_is_auto_fetch_eop ()
	Checks if automatic fetching of Earth Orientation Parameter values from IERS is allowed.
int	novas_leap_for_jd (double jd_utc)
	Returns the leap seconds for the given (UTC-based) Julian date.
int	novas_lookup_leap (time_t t)
	Returns the leap seconds for the given UNIX timestamp.
void	novas_reset_eop ()
	Releases resources used by URL handles used for obtaining Earth Orientation Parameter (EOP) data from the International Earth Rotation and Reference Systems Service (IERS), including the leap seconds list supplied earlier or obtained from IERS.
int	novas_set_auto_fetch_eop (int enabled)
	Disable or Re-enabled the automatic fetching of Earth Orientation Parameter values from IERS, when these are left undefined (NAN) when initializing astrometric time or observing frame instances.
int	novas_set_eop_url (enum novas_eop_series series, int itrf_year, const char *url)
	Specify a URL to use for a given IERS Earth Orientation Parameter (EOP) series.
int	novas_set_leap_list (const char *filename)
	Obsoleted function to specify a file containing the leap seconds list.

Detailed Description

Date

Created on Apr 18, 2026

Author

Attila Kovacs and Kiran Shila

Functions to obtain and manage Earth Orientation data from the International Earth Rotation and Reference Systems Service (IERS) via HTTPS, or using other (remote or local) URLs.

The functions in this module are generally thread-safe. That is, you may call all functions from concurrent threads without data corruption. However, note that the EOP resources (URLs and/or local files), and the setting that enables/disables automatic fetching, are global settings. Thus, changing these in one thread will affect subsequent EOP fetch calls in other threads also.

See also

Earth orientation

Macro Definition Documentation

IERS_DATACENTER

#define IERS_DATACENTER   "datacenter.iers.org"

IERS EOP server name.

Function Documentation

novas_fetch_eop()

int novas_fetch_eop	(	double	jd,
		long	timeout_millis,
		novas_eop *	eop )

Obtains interpolated Earth Orientation Parameter data from the International Earth Rotation and Reference Systems Service (IERS).

For dates since 1972 or for prediction for up to a year ahead, the rapid service data is used (finals.all), otherwise for dates after 1962 the C04 series is used, and for dates all the way back to 1846, the C01 series is used. All of the mentioned data are retrieved relative to the IAU2000 precession-nutation model.

You should always check the return status when using this function, since the fetching of EOP values may fail for a host of different reasons.

NOTES:

1. You must have built SuperNOVAS with cURL support. Otherwise, this function will return -1, with errno set to ENOSYS.
2. You will need an internet connection and the IERS server must be online and accessible, unless you have changed the necessary URLs to use local copies instead (see novas_set_eop_url()).
3. Obtaining values from IERS can have arbitrary latencies, and can impact the performance severely. For performance critical applications, you should consider specifying the EOP values more directly, or using local files instead (see also novas_set_eop_url()).
4. This function assumes that the files served from IERS remain accessible and their format does not change over time. As such what works today, may not work the same in the future. The IERS website also encounters outages occasionally (see novas_set_eop_url() for alternative sources.).
5. This function caches EOP data from the last query. As such repeated calls within the same date bracket (typically the same MJD day) will return fast and will interpolate from the data last obtained from the IERS.
6. This function uses cubic spline interpolation around the published data points. As such, it needs at least two data points at the same time or before, and two points after, the date for which interpolated values are requested.
7. Prior to 1 Jan 1956, the UT1-UTC time difference, and length-of-day (LOD) are not provided by IERS, as they were not measured prior to the age of atomic clocks. Hence, for dates prior to 1956 the returned EOP will have dut1 and lod (and their uncertainties) set to NAN. (However, the polar the offsets x_p and y_p can be provided all the way back to 1846, with some precision.)
8. If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then this function will return an error (errno set to ENOSYS).

Parameters

	jd	Julian Date (in any timescale, with a preference for UTC)
	timeout_millis	[ms] HTTP connection timeout, or <=0 to leave unchanged.
[out]	eop	Output EOP data structure to populate

Returns

0 if successful or else -1 (errno will indicate the type of error).

Since

1.7

Author

Attila Kovacs

See also

https://www.iers.org/IERS/EN/DataProducts/EarthOrientationData/eop

novas_fetch_current_eop(), novas_set_eop_url(), novas_reset_eop()

novas_make_frame(), novas_set_time(), novas_set_auto_fetch_eop(), Earth orientation

References novas_eop::jd, novas_eop::leap, NOVAS_EOP_INVALID, and novas_leap_for_jd().

Referenced by supernovas::GeodeticObserver::eop_at(), supernovas::EOP::fetch_for_jd(), novas_fetch_eop_unix(), and novas_make_frame().

novas_fetch_eop_unix()

int novas_fetch_eop_unix	(	time_t	t,
		long	timeout_millis,
		novas_eop *	eop )

Obtains interpolated Earth Orientation Parameter data from the International Earth Rotation and Reference Systems Service (IERS) around the current system time, using the rapid service data (finals.all).

You should always check the return status when using this function, since the fetching of EOP values may fail for a host of different reasons.

NOTES:

1. You must have access to the curl library and built SuperNOVAS with CURL support. Otherwise this function will return -1, with errno set to ENOSYS.
2. You will need an internet connection and the IERS server must be online and accessible (at least for the initial call).
3. Obtaining values from IERS can have arbitrary latencies, and can impact performance severely. For performance critical applications, you should consider specifying the EOP values more directly, e.g. from a local file instead.
4. This function assumes that the files served from IERS remain accessible and their format does not change over time. As such what works today, may not work the same in the future. The IERS website also encounters outages occasionally (see novas_set_eop_url() for alternative sources.).
5. This function caches EOP data from the last online query. As such repeated calls within the same data bracket (typically the same MJD day) will return fast and will reuse the last data obtained from the IERS.
6. This function uses cubic spline interpolation of the published data points.
7. The returned EOP values are assumed to be ITRF 2020 values, which is appropriate at the time this SuperNOVAS module was written or last updated. If IERS later publishes data in some other future ITRF realization, this module may need to be updated, accordingly. However, the ITRF realization is unlikely to matter significantly.
8. If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then this function will return an error (errno set to ENOSYS).

Parameters

	t	[s] UNIX time (seconds since 0 UTC 1 Jan 1970).
	timeout_millis	[ms] HTTP connection timeout, or <=0 to leave unchanged.
[out]	eop	Output EOP data structure to populate

Returns

0 if successful or else -1 (errno will indicate the type of error).

Since

1.7

Author

Attila Kovacs

See also

https://www.iers.org/IERS/EN/DataProducts/EarthOrientationData/eop

novas_set_eop_url()

novas_make_frame(), novas_set_time(), novas_set_auto_fetch_eop(), Earth orientation

References novas_fetch_eop(), NOVAS_JD_J2000, and UNIX_SECONDS_0UTC_1JAN2000.

novas_leap_for_jd()

int novas_leap_for_jd

(

double

jd_utc

)

Returns the leap seconds for the given (UTC-based) Julian date.

The UTC-based dates matter only in the immediate vicinity of the leap seconds changes, since leap seconds are introduced on specific UTC dates. If a minute-level fuzz around the times when leap seconds were introduced can be tolerated then the choice of timescale is not relevant.

Leap seconds were first introduced on 1 Jan 1972. Thus for date preceding the introduction, 0 is returned. The last leap of 27 seconds was introduced on 1 January 2017, and the decision has been made to not introduce further leap seconds as of 20 May 2027, leaving 37 seconds for the foreseeable future.

REFERENCES:

1. General Conference on Weights and Measures. "Resolution 5: On the adoption of a continuous UTC." Document presented at the 28th Meeting of the CGPM, Bureau International des Poids et Mesures (BIPM), Versailles, France, October 15, 2026. https://www.bipm.org/en/cgpm-2026/resolution-5.

Parameters

jd_utc

[day] Julian date (preferably UTC-based)

Returns

The leap seconds for the given time, or -1 if the input date is NAN (errno set to EINVAL).

Since

1.8

Author

Attila Kovacs

See also

novas_lookup_leap()

References NOVAS_DAY, NOVAS_JD_J2000, and novas_lookup_leap().

Referenced by novas_fetch_eop(), novas_set_split_time(), and novas_time_leap().

novas_reset_eop()

void novas_reset_eop

(

)

Releases resources used by URL handles used for obtaining Earth Orientation Parameter (EOP) data from the International Earth Rotation and Reference Systems Service (IERS), including the leap seconds list supplied earlier or obtained from IERS.

It also discards any custom URLs that may have been set previously, and restores the default IERS URLs for obtaining leap seconds and EOP from IERS. The cleanup performed by this function is automatic at normal program exit, but users may call it explicitly restore the initial state at any point.

NOTES:

• This call does not affect or destroy any thread-local data currently cached. As such, novas_fetch_eop() may continue to return EOP using the previously cached values, if the requested date falls within the same data bracket as the last call.
• This call is not thread-safe. You should avoid calling it from concurrent threads if you want it to have predictable behavior.

Since

1.7

Author

Attila Kovacs

See also

novas_fetch_eop()

novas_set_leap_list()

int novas_set_leap_list

(

const char *

filename

)

Obsoleted function to specify a file containing the leap seconds list.

There will be no more leap seconds as of 20 May 2027, so the final list of leap seconds is now hardcoded into SuperNOVAS as of v1.8. There will be leap hours instead, perhaps, in the distant future, but not for some millenia. If someone still uses SuperNOVAS then, well, they must make some modifications to handle it then...

REFERENCES:

1. General Conference on Weights and Measures. "Resolution 5: On the adoption of a continuous UTC." Document presented at the 28th Meeting of the CGPM, Bureau International des Poids et Mesures (BIPM), Versailles, France, October 15, 2026. https://www.bipm.org/en/cgpm-2026/resolution-5.

Parameters

filename

unused

Returns

0 is successful, or -1 if novas_debug() was called with NOVAS_DEBUG_EXTRA. In both cases errno will be set to ENOSYS.

Since

1.7

Author

Attila Kovacs

See also

https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list

novas_set_eop_url(), novas_lookup_leap(), novas_fetch_eop(), novas_reset_eop()

Deprecated

There will be no more leap seconds, so we readily know the final leap list, which is now hardcoded into SuperNOVAS as of v1.8. This function will return 0 (unless extra level debugging is enabled) to remain compatible with existing working code that uses this function, but it will no longer actually load the specified leap seconds file. It will always set errno to ENOSYS to indicate that the function is no longer meaningful.

References NOVAS_DEBUG_EXTRA, and novas_get_debug_mode().

Referenced by novas_set_eop_url().