NTP Status Checks

Unfortunately there is no API which can simply be called from a different application.

Some years ago there has been some effort to put the core functionality of the ntpq program into a shared library, and the goal was to change the ntpq program to use the API calls provided by this library. However, unfortunately the latter has never been worked upon, but instead, the ntpq program has been enhanced and modified since that time, so I don't know if the shared library would still work properly for all cases.

So the only reliable way is to run the command ntpq -c rv from within an application, and parse its output. The most important information is the system status code, so the application should scan the output for status= and decode the subsequent hex number, which is coded as a bit mask.

A description of the system status word encoding can be found here:

• https://www.meinbergglobal.com/download/ntp/docs/html/decode.html#sys

Please note that on that web page the most significant bit is labeled as bit 0. If you run the command ntpq -c rv manually in intervals after the NTP service has been just been started, the output from subsequent commands may look like:

associd=0 status=c016 leap_alarm, sync_unspec, 1 event, restart,

associd=0 status=c418 leap_alarm, sync_uhf_radio, 1 event, no_sys_peer,

associd=0 status=0415 leap_none, sync_uhf_radio, 1 event, clock_sync,

So an application could check the leap bits, where 11 means never synchronized, and 00 says that synchronization could be achieved before. However, please keep in mind that also 01 or 10 mean synchronized, in case a leap second is pending.

In the example above you can see that the 2 MSBs change from 11 (Cxxx) to 00 (0xxx).

If the leap bits are not 11 then you could check the 4 LSBs of the status word. Please keep in mind that this isn't really a current status, but the last event that happened. So normally the last event when going to synchronized state is clock_sync (0x05), but you need to keep in mind that e.g. across a leap second there may also be events like leap_armed (0x09), leap_disarmed (0x0A), and leap_event (0x0B), which are also perfectly fine during normal operation.

— Martin Burnicki martin.burnicki@meinberg.de, last updated 2023-01-25