D. J. Bernstein

Time

libtai
# The tai library interface

## Times with 1-second precision

#include <tai.h>
struct tai *t*;

A `struct tai` value is
an integer between 0 inclusive and 2^64 exclusive.
The format of `struct tai`
is designed to speed up common operations;
applications should not look inside `struct tai`.
A `struct tai` variable
is commonly used to store a
TAI64 label.
Each TAI64 label refers to one second of real time.
TAI64 labels span a range of hundreds of billions of years.

A `struct tai` variable
may also be used to store the numerical difference between two TAI64 labels.

## Current time

#include <tai.h>
struct tai *t*;
tai_now(&*t*);

`tai_now`
puts the current time into
*t*.
More precisely:
`tai_now`
puts into *t*
its best guess as to the TAI64 label for the 1-second interval
that contains the current time.
This implementation of `tai_now`
assumes that the `time_t` returned from the `time` function
represents the number of TAI seconds since 1970-01-01 00:00:10 TAI.
This matches the convention used by
the Olson tz library in ``right'' mode.

## Binary input and output

#include <tai.h>
struct tai *t*;
char *buf*[TAI_PACK];
tai_pack(*buf*,&*t*);
tai_unpack(*buf*,&*t*);

`tai_pack` converts a TAI64 label from internal format
in *t* to
external TAI64 format
in *buf*.
`tai_unpack` converts a TAI64 label from
external TAI64 format
in *buf*
to internal format
in *t*.

TAI_PACK is 8.

## Arithmetic

#include <tai.h>
struct tai *t*;
struct tai *a*;
struct tai *b*;
double *d*;
int *i*;
*d* = tai_approx(&*t*);
*i* = tai_less(&*a*,&*b*);
tai_add(&*t*,&*a*,&*b*);
tai_sub(&*t*,&*a*,&*b*);

`tai_approx`
returns a double-precision approximation to *t*.
The result of `tai_approx` is always nonnegative.
`tai_less`
returns 1 if
*a*
is less than
*b*,
0 otherwise.

`tai_add`
adds
*a*
to
*b*
modulo 2^64 and puts the result into
*t*.
The inputs and output may overlap.

`tai_sub`
subtracts
*b*
from
*a*
modulo 2^64 and puts the result into
*t*.
The inputs and output may overlap.