leapsecs_init 3 user commands djbwares
leapsecs_init leapsecs_sub leapsecs_add leapsecs_read handle UTC leap seconds

    #include <leapsecs.h>

int `leapsecs_sub` struct tai * t void `leapsecs_add` struct tai * t int hit int `leapsecs_read` int `leapsecs_init`

## Description

`leapsecs_sub` changes a seconds-since-epoch count into a non-leap-seconds-since-epoch count. It interprets t as a TAI64 label, subtracts from t the number of leap seconds that have occurred before or at t, and places the result back into t.

`leapsecs_sub` returns 1 if t was a leap second, 0 otherwise.

`leapsecs_add` reverses the effect of `leapsecs_sub`. hit must be 1 for a leap second, 0 otherwise.

## Leap-second table

The current implementation of `leapsecs_sub` and `leapsecs_add` uses a leap-second table read from disk.

`leapsecs_read` reads the leap-second table from `/etc/leapsecs.dat`. It returns 0 on success, -1 on error. If `/etc/leapsecs.dat` does not exist, `leapsecs_read` treats it as an empty file.

`leapsecs_init` is a one-time version of `leapsecs_read`. Initially it is the same as `leapsecs_read`; however, once `leapsecs_read` returns 0, `leapsecs_init` will always return 0 without calling `leapsecs_read` again.

`leapsecs_add` and `leapsecs_sub` call `leapsecs_init`.

If `leapsecs_init` returns failure, `leapsecs_add` and `leapsecs_sub` will proceed without a leap-second table. For reliability, all programs should call `leapsecs_init` at startup and check for errors.
New entries are added to the leap-second table on disk every 12 to 18 months. `leapsecs_read` may be called repeatedly. It leaves the old table alone on error. For reliability, all long-running programs should call `leapsecs_read` at least once every month.

## See also

tai 3

## Author

Original code and documentation by Daniel J. Bernstein. Converted to DocBook XML by Jonathan de Boyne Pollard.