Make OSSL_TIME a structure

[thirdparty/openssl.git] / doc / internal / man3 / OSSL_TIME.pod

=pod

=head1 NAME

OSSL_TIME, OSSL_TIME_SECOND, ossl_time_infinite, ossl_time_zero,
ossl_ticks2time, ossl_time2ticks,
ossl_time_now, ossl_time_time_to_timeval, ossl_time_compare,
ossl_time_add, ossl_time_subtract
- times and durations

=head1 SYNOPSIS

 #include "internal/time.h"

 typedef struct OSSL_TIME;

 #define OSSL_TIME_SECOND   /* Ticks per second */

 OSSL_TIME ossl_ticks2time(uint64_t);
 uint64_t ossl_time2ticks(OSSL_TIME t);

 OSSL_TIME ossl_time_zero(void);
 OSSL_TIME ossl_time_infinite(void);
 OSSL_TIME ossl_time_now(void);

 void ossl_time_time_to_timeval(OSSL_TIME t, struct timeval *out);

 int ossl_time_compare(OSSL_TIME a, OSSL_TIME b);
 OSSL_TIME ossl_time_add(OSSL_TIME a, OSSL_TIME b);
 OSSL_TIME ossl_time_subtract(OSSL_TIME a, OSSL_TIME b);

=head1 DESCRIPTION

These functions allow the current time to be obtained and for basic
arithmetic operations to be safely performed with times and durations.

B<OSSL_TIME> can represent a duration, or a point in time. Where it is
used to represent a point in time, it does so by expressing a duration
relative to some reference Epoch.  The OSSL_TIME structure itself does
not contain information about the Epoch used; thus, interpretation of
an OSSL_TIME requires that the Epoch it is to be interpreted relative
to is contextually understood.

B<OSSL_TIME_SECOND> is an integer that indicates the precision of an
B<OSSL_TIME>.  Specifically, it is the number of counts per second that
a time can represent.  The accuracy is independent of this and is system
dependent.

B<ossl_ticks2time> converts an integral number of counts to a time.

B<ossl_time2ticks> converts a time to an integral number of counts.

B<ossl_time_zero> returns the smallest representable B<OSSL_TIME>.
This value represents the time Epoch and it is returned when an underflow
would otherwise occur.

B<ossl_time_infinite> returns the largest representable B<OSSL_TIME>.
This value is returned when an overflow would otherwise occur.

B<ossl_time_now> returns the current time relative to an Epoch which
is undefined but unchanging for at least the duration of program
execution.  The time returned is monotonic and need not represent
wall-clock time.  The time returned by this function is useful for
scheduling timeouts, deadlines and recurring events, but due to its
undefined Epoch and monotonic nature, is not suitable for other uses.

B<ossl_time_time_to_timeval> converts a time to a I<struct timeval>.

B<ossl_time_compare> compares I<a> with I<b> and returns -1 if I<a>
is smaller than I<b>, 0 if they are equal and +1 if I<a> is
larger than I<b>.

B<ossl_time_add> performs a saturating addition of the two times,
returning I<a> + I<b>.
If the summation would overflow B<OSSL_TIME_INFINITY> is returned.

B<ossl_time_subtract> performs a saturating subtraction of the two items,
returning I<a> - I<b>.
If the difference would be negative,  B<0> is returned.

=head1 NOTES

The largest representable duration is guaranteed to be at least 500 years.

=head1 RETURN VALUES

B<ossl_time_now> returns the current time, or the time of the Epoch on error.

B<ossl_time_zero> returns the time of the Epoch.

B<ossl_time_infinite> returns the last representable time.

B<ossl_ticks2time> return the duration specified.

B<ossl_time2ticks> returns the ticks since Epoch.

B<ossl_time_compare> returns -1, 0 or 1 depending on the comparison.

B<ossl_time_add> returns the summation of the two times or
the last representable time on overflow.

B<ossl_time_subtract> returns the difference of the two times or the
time of the Epoch on underflow.

=head1 HISTORY

This functionality was added in OpenSSL 3.1.

=head1 COPYRIGHT

Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use this
file except in compliance with the License.  You can obtain a copy in the file
LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut