1=pod 2 3=head1 NAME 4 5OSSL_TIME, OSSL_TIME_SECOND, ossl_time_infinite, ossl_time_zero, 6ossl_ticks2time, ossl_time2ticks, 7ossl_time_now, ossl_time_time_to_timeval, ossl_time_compare, 8ossl_time_add, ossl_time_subtract, ossl_time_multiply, 9ossl_time_divide, ossl_time_abs_difference, ossl_time_max, 10ossl_time_min - times and durations 11 12=head1 SYNOPSIS 13 14 #include "internal/time.h" 15 16 typedef struct OSSL_TIME; 17 18 #define OSSL_TIME_SECOND /* Ticks per second */ 19 20 OSSL_TIME ossl_ticks2time(uint64_t); 21 uint64_t ossl_time2ticks(OSSL_TIME t); 22 23 OSSL_TIME ossl_time_zero(void); 24 OSSL_TIME ossl_time_infinite(void); 25 OSSL_TIME ossl_time_now(void); 26 27 void ossl_time_time_to_timeval(OSSL_TIME t, struct timeval *out); 28 29 int ossl_time_compare(OSSL_TIME a, OSSL_TIME b); 30 OSSL_TIME ossl_time_add(OSSL_TIME a, OSSL_TIME b); 31 OSSL_TIME ossl_time_subtract(OSSL_TIME a, OSSL_TIME b); 32 OSSL_TIME ossl_time_multiply(OSSL_TIME a, uint64_t b); 33 OSSL_TIME ossl_time_divide(OSSL_TIME a, uint64_t b); 34 OSSL_TIME ossl_time_abs_difference(OSSL_TIME a, OSSL_TIME b); 35 OSSL_TIME ossl_time_max(OSSL_TIME a, OSSL_TIME b); 36 OSSL_TIME ossl_time_min(OSSL_TIME a, OSSL_TIME b); 37 38=head1 DESCRIPTION 39 40These functions allow the current time to be obtained and for basic 41arithmetic operations to be safely performed with times and durations. 42 43B<OSSL_TIME> can represent a duration, or a point in time. Where it is 44used to represent a point in time, it does so by expressing a duration 45relative to some reference Epoch. The OSSL_TIME structure itself does 46not contain information about the Epoch used; thus, interpretation of 47an OSSL_TIME requires that the Epoch it is to be interpreted relative 48to is contextually understood. 49 50B<OSSL_TIME_SECOND> is an integer that indicates the precision of an 51B<OSSL_TIME>. Specifically, it is the number of counts per second that 52a time can represent. The accuracy is independent of this and is system 53dependent. 54 55B<ossl_ticks2time> converts an integral number of counts to a time. 56 57B<ossl_time2ticks> converts a time to an integral number of counts. 58 59B<ossl_time_zero> returns the smallest representable B<OSSL_TIME>. 60This value represents the time Epoch and it is returned when an underflow 61would otherwise occur. 62 63B<ossl_time_infinite> returns the largest representable B<OSSL_TIME>. 64This value is returned when an overflow would otherwise occur. 65 66B<ossl_time_now> returns the current time relative to an Epoch which 67is undefined but unchanging for at least the duration of program 68execution. The time returned is monotonic and need not represent 69wall-clock time. The time returned by this function is useful for 70scheduling timeouts, deadlines and recurring events, but due to its 71undefined Epoch and monotonic nature, is not suitable for other uses. 72 73B<ossl_time_time_to_timeval> converts a time to a I<struct timeval>. 74 75B<ossl_time_compare> compares I<a> with I<b> and returns -1 if I<a> 76is smaller than I<b>, 0 if they are equal and +1 if I<a> is 77larger than I<b>. 78 79B<ossl_time_add> performs a saturating addition of the two times, 80returning I<a> + I<b>. 81If the summation would overflow B<OSSL_TIME_INFINITY> is returned. 82 83B<ossl_time_subtract> performs a saturating subtraction of the two items, 84returning I<a> - I<b>. 85If the difference would be negative, B<0> is returned. 86 87B<ossl_time_multiply> performs a saturating multiplication of a time value by a 88given integer multiplier. 89 90B<ossl_time_divide> performs floor division of a time value by a given integer 91divisor. 92 93B<ossl_time_abs_difference> returns the magnitude of the difference between two 94time values. 95 96B<ossl_time_min> returns the lesser of two time values. 97 98B<ossl_time_max> returns the greater of two time values. 99 100=head1 NOTES 101 102The largest representable duration is guaranteed to be at least 500 years. 103 104=head1 RETURN VALUES 105 106B<ossl_time_now> returns the current time, or the time of the Epoch on error. 107 108B<ossl_time_zero> returns the time of the Epoch. 109 110B<ossl_time_infinite> returns the last representable time. 111 112B<ossl_ticks2time> return the duration specified. 113 114B<ossl_time2ticks> returns the ticks since Epoch. 115 116B<ossl_time_compare> returns -1, 0 or 1 depending on the comparison. 117 118B<ossl_time_add> returns the summation of the two times or 119the last representable time on overflow. 120 121B<ossl_time_subtract> returns the difference of the two times or the 122time of the Epoch on underflow. 123 124B<ossl_time_multiply> returns the result of multiplying the given time by the 125given integral multiplier, or B<OSSL_TIME_INFINITY> on overflow. 126 127B<ossl_time_divide> returns the result of dividing the given time by the given 128integral divisor. 129 130B<ossl_time_abs_difference> returns the magnitude of the difference between the 131input time values. 132 133B<ossl_time_min> and B<ossl_time_max> choose and return one of the input values. 134 135=head1 HISTORY 136 137This functionality was added in OpenSSL 3.1. 138 139=head1 COPYRIGHT 140 141Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. 142 143Licensed under the Apache License 2.0 (the "License"). You may not use this 144file except in compliance with the License. You can obtain a copy in the file 145LICENSE in the source distribution or at 146L<https://www.openssl.org/source/license.html>. 147 148=cut 149
