mirror of
https://github.com/openssl/openssl.git
synced 2024-12-15 06:01:37 +08:00
45ada6b92b
3.1 has been decided to be a FIPS 140-3 release, springing from the branch openssl-3.0, and the master branch to continue with the development of OpenSSL 3.2. Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> Reviewed-by: Tim Hudson <tjh@openssl.org> (Merged from https://github.com/openssl/openssl/pull/19350)
204 lines
7.4 KiB
Plaintext
204 lines
7.4 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSL_TIME, OSSL_TIME_SECOND, OSSL_TIME_MS, OSSL_TIME_US,
|
|
ossl_time_infinite, ossl_time_zero, ossl_time_now,
|
|
ossl_ticks2time, ossl_time2ticks, ossl_seconds2time, ossl_time2seconds,
|
|
ossl_ms2time, ossl_us2time, ossl_time2ms, ossl_time2us,
|
|
ossl_time_to_timeval, ossl_time_from_timeval,
|
|
ossl_time_to_time_t, ossl_time_from_time_t,
|
|
ossl_time_compare, ossl_time_is_zero, ossl_time_is_infinite,
|
|
ossl_time_add, ossl_time_subtract,
|
|
ossl_time_multiply, ossl_time_divide, ossl_time_muldiv,
|
|
ossl_time_abs_difference, ossl_time_max,
|
|
ossl_time_min - times and durations
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include "internal/time.h"
|
|
|
|
typedef struct OSSL_TIME;
|
|
|
|
#define OSSL_TIME_SECOND /* Ticks per second */
|
|
#define OSSL_TIME_MS /* Ticks per millisecond */
|
|
#define OSSL_TIME_US /* Ticks per microsecond */
|
|
|
|
OSSL_TIME ossl_ticks2time(uint64_t);
|
|
uint64_t ossl_time2ticks(OSSL_TIME t);
|
|
OSSL_TIME ossl_seconds2time(uint64_t);
|
|
uint64_t ossl_time2seconds(OSSL_TIME t);
|
|
OSSL_TIME ossl_ms2time(uint64_t);
|
|
uint64_t ossl_time2ms(OSSL_TIME t);
|
|
OSSL_TIME ossl_us2time(uint64_t);
|
|
uint64_t ossl_time2us(OSSL_TIME t);
|
|
|
|
OSSL_TIME ossl_time_zero(void);
|
|
OSSL_TIME ossl_time_infinite(void);
|
|
OSSL_TIME ossl_time_now(void);
|
|
|
|
struct timeval ossl_time_to_timeval(OSSL_TIME t);
|
|
OSSL_TIME ossl_time_from_timeval(struct timeval tv);
|
|
time_t ossl_time_to_time_t(OSSL_TIME t);
|
|
OSSL_TIME ossl_time_from_time_t(time_t t);
|
|
|
|
int ossl_time_compare(OSSL_TIME a, OSSL_TIME b);
|
|
int ossl_time_is_zero(OSSL_TIME t);
|
|
int ossl_time_is_infinite(OSSL_TIME t);
|
|
|
|
OSSL_TIME ossl_time_add(OSSL_TIME a, OSSL_TIME b);
|
|
OSSL_TIME ossl_time_subtract(OSSL_TIME a, OSSL_TIME b);
|
|
OSSL_TIME ossl_time_multiply(OSSL_TIME a, uint64_t b);
|
|
OSSL_TIME ossl_time_divide(OSSL_TIME a, uint64_t b);
|
|
OSSL_TIME ossl_time_muldiv(OSSL_TIME a, uint64_t b, uint64_t c);
|
|
OSSL_TIME ossl_time_abs_difference(OSSL_TIME a, OSSL_TIME b);
|
|
OSSL_TIME ossl_time_max(OSSL_TIME a, OSSL_TIME b);
|
|
OSSL_TIME ossl_time_min(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_seconds2time>, B<ossl_ms2time> and B<ossl_us2time> convert an
|
|
integral number of seconds, milliseconds and microseconds respectively
|
|
to a time. These functions are implemented as macros.
|
|
|
|
B<ossl_time2seconds>, B<ossl_time2ms> and B<ossl_time2us> convert a
|
|
time to an integral number of second, milliseconds and microseconds
|
|
respectively. These functions truncates any fractional seconds and are
|
|
implemented as macros.
|
|
|
|
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_to_timeval> converts a time to a I<struct timeval>.
|
|
|
|
B<ossl_time_from_timeval> converts a I<struct timeval> to a time.
|
|
|
|
B<ossl_time_to_time_t> converts a time to a I<time_t>.
|
|
|
|
B<ossl_time_from_time_t> converts a I<time_t> to a time.
|
|
|
|
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_is_zero> returns 1 if the time I<t> is zero and 0 otherwise.
|
|
|
|
B<ossl_time_is_infinite> returns 1 if the time I<t> is infinite and 0 otherwise.
|
|
|
|
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.
|
|
|
|
B<ossl_time_multiply> performs a saturating multiplication of a time value by a
|
|
given integer multiplier returning I<a> × I<b>.
|
|
|
|
B<ossl_time_divide> performs division of a time value by a given integer
|
|
divisor returning ⌊I<a> ÷ I<b>⌋.
|
|
|
|
B<ossl_time_muldiv> performs a fused multiplication and division operation.
|
|
The result is equal to ⌊I<a> × I<b> ÷ I<c>⌋.
|
|
|
|
B<ossl_time_abs_difference> returns the magnitude of the difference between two
|
|
time values.
|
|
|
|
B<ossl_time_min> returns the lesser of two time values.
|
|
|
|
B<ossl_time_max> returns the greater of two time values.
|
|
|
|
=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>, B<ossl_seconds2time>, B<ossl_ms2time> and B<ossl_us2time>
|
|
return the duration specified in ticks, seconds, milliseconds and microseconds
|
|
respectively.
|
|
|
|
B<ossl_time2ticks>, B<ossl_time2seconds>, B<ossl_time2ms> and B<ossl_time2us>
|
|
return the number of ticks, seconds, microseconds and microseconds respectively
|
|
that the time object represents.
|
|
|
|
B<ossl_time_to_timeval>, B<ossl_time_from_timeval>, B<ossl_time_to_time_t> and
|
|
B<ossl_time_from_time_t> all return the converted time.
|
|
|
|
B<ossl_time_compare> returns -1, 0 or 1 depending on the comparison.
|
|
|
|
B<ossl_time_is_zero> and B<ossl_time_is_infinite> return 1 if the condition
|
|
is true and 0 otherwise.
|
|
|
|
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.
|
|
|
|
B<ossl_time_multiply> returns the result of multiplying the given time by the
|
|
given integral multiplier, or B<OSSL_TIME_INFINITY> on overflow.
|
|
|
|
B<ossl_time_divide> returns the result of dividing the given time by the given
|
|
integral divisor.
|
|
|
|
B<ossl_time_muldiv> returns the fused multiplication and division of the given
|
|
time and the two integral values.
|
|
|
|
B<ossl_time_abs_difference> returns the magnitude of the difference between the
|
|
input time values.
|
|
|
|
B<ossl_time_min> and B<ossl_time_max> choose and return one of the input values.
|
|
|
|
=head1 HISTORY
|
|
|
|
This functionality was added in OpenSSL 3.2.
|
|
|
|
=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
|