Actually return the return value

[martinvonwittich]

(This is essentially copypasted from my bug report for busybox adjtimex.)

adjtimex can be used to query if the system time is synchronized, e.g. whether NTP is working or not. Example output of a machine where ntpd can't connect to any peers:

host ~ # adjtimex -p   
         mode: 0
       offset: 0
    frequency: 246768
     maxerror: 16000000
     esterror: 15
       status: 8257
time_constant: 9
    precision: 1
    tolerance: 32768000
         tick: 10000
     raw time:  1623077737s 410635507ns = 1623077737.410635507
 return value = 5

• status: 8257 is interpreted by busybox adjtimex as PLL | UNSYNC.

  adjtimex itself doesn't do this convenient interpretation, but 8257 can be interpreted as a combination of these flags documented in the manpage:

  • 1 PLL updates enabled
  • 64 clock unsynchronized
  • 8192 resolution (0 = us, 8192 = ns)

  which seems to indicate that busybox adjtimex interprets it correctly.

• return value = 5 is interpreted by busybox adjtimex as clock not synchronized.

  return value doesn't seem to be documented in the adjtimex manpage, but I believe it corresponds to these values?

         -p, --print
                Print the current values of the kernel time variables.  NOTE: The time is "raw", and may be off by up to one timer tick (10 msec).  "status" gives the
                value of the time_status variable in the kernel.  For Linux 1.0 and 1.2 kernels, the value is as follows:
                      0   clock is synchronized (so the kernel should
                          periodically set the CMOS clock to match the
                          system clock)
                      1   inserting a leap second at midnight
                      2   deleting a leap second at midnight
                      3   leap second in progress
                      4   leap second has occurred
                      5   clock not externally synchronized (so the
                          kernel should leave the CMOS clock alone)
  

  Which would also confirm that busybox adjtimex interprets this correctly.

Unfortunately neither adjtimex nor busybox adjtimex currently return the return value as an actual exit code, which means that scripts would have to parse it from the output. It would be useful if adjtimex had a flag for this purpose to actually return the call's return value. (I had originally suggested -r for busybox adjtimex, but this already has a different meaning for adjtimex. Maybe -x as in eXit which is still available in both tools?).

This would allow scripts to use adjtime -x / busybox adjtimex -qx (busybox adjtimex needs -q to suppress the output because it will print by default) to determine the synchronization state efficiently by examining the return code.