leapsecs_init

## Name

leapsecs_init, leapsecs_sub, leapsecs_add, leapsecs_read — handle UTC leap seconds

## Synopsis

    #include <leapsecs.h>

`int leapsecs_sub(` | t`)`; |

`struct tai * t`;

`void leapsecs_add(` | t, |
| hit`)`; |

`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`.

### Warning

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.

### Warning

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.