1*e7be843bSPierre Pronchery=pod 2*e7be843bSPierre Pronchery 3*e7be843bSPierre Pronchery=head1 NAME 4*e7be843bSPierre Pronchery 5*e7be843bSPierre ProncheryOSSL_TIME, OSSL_TIME_SECOND, OSSL_TIME_MS, OSSL_TIME_US, 6*e7be843bSPierre Proncheryossl_time_infinite, ossl_time_zero, ossl_time_now, 7*e7be843bSPierre Proncheryossl_ticks2time, ossl_time2ticks, ossl_seconds2time, ossl_time2seconds, 8*e7be843bSPierre Proncheryossl_ms2time, ossl_us2time, ossl_time2ms, ossl_time2us, 9*e7be843bSPierre Proncheryossl_time_to_timeval, ossl_time_from_timeval, 10*e7be843bSPierre Proncheryossl_time_to_time_t, ossl_time_from_time_t, 11*e7be843bSPierre Proncheryossl_time_compare, ossl_time_is_zero, ossl_time_is_infinite, 12*e7be843bSPierre Proncheryossl_time_add, ossl_time_subtract, 13*e7be843bSPierre Proncheryossl_time_multiply, ossl_time_divide, ossl_time_muldiv, 14*e7be843bSPierre Proncheryossl_time_abs_difference, ossl_time_max, 15*e7be843bSPierre Proncheryossl_time_min - times and durations 16*e7be843bSPierre Pronchery 17*e7be843bSPierre Pronchery=head1 SYNOPSIS 18*e7be843bSPierre Pronchery 19*e7be843bSPierre Pronchery #include "internal/time.h" 20*e7be843bSPierre Pronchery 21*e7be843bSPierre Pronchery typedef struct OSSL_TIME; 22*e7be843bSPierre Pronchery 23*e7be843bSPierre Pronchery #define OSSL_TIME_SECOND /* Ticks per second */ 24*e7be843bSPierre Pronchery #define OSSL_TIME_MS /* Ticks per millisecond */ 25*e7be843bSPierre Pronchery #define OSSL_TIME_US /* Ticks per microsecond */ 26*e7be843bSPierre Pronchery 27*e7be843bSPierre Pronchery OSSL_TIME ossl_ticks2time(uint64_t); 28*e7be843bSPierre Pronchery uint64_t ossl_time2ticks(OSSL_TIME t); 29*e7be843bSPierre Pronchery OSSL_TIME ossl_seconds2time(uint64_t); 30*e7be843bSPierre Pronchery uint64_t ossl_time2seconds(OSSL_TIME t); 31*e7be843bSPierre Pronchery OSSL_TIME ossl_ms2time(uint64_t); 32*e7be843bSPierre Pronchery uint64_t ossl_time2ms(OSSL_TIME t); 33*e7be843bSPierre Pronchery OSSL_TIME ossl_us2time(uint64_t); 34*e7be843bSPierre Pronchery uint64_t ossl_time2us(OSSL_TIME t); 35*e7be843bSPierre Pronchery 36*e7be843bSPierre Pronchery OSSL_TIME ossl_time_zero(void); 37*e7be843bSPierre Pronchery OSSL_TIME ossl_time_infinite(void); 38*e7be843bSPierre Pronchery OSSL_TIME ossl_time_now(void); 39*e7be843bSPierre Pronchery 40*e7be843bSPierre Pronchery struct timeval ossl_time_to_timeval(OSSL_TIME t); 41*e7be843bSPierre Pronchery OSSL_TIME ossl_time_from_timeval(struct timeval tv); 42*e7be843bSPierre Pronchery time_t ossl_time_to_time_t(OSSL_TIME t); 43*e7be843bSPierre Pronchery OSSL_TIME ossl_time_from_time_t(time_t t); 44*e7be843bSPierre Pronchery 45*e7be843bSPierre Pronchery int ossl_time_compare(OSSL_TIME a, OSSL_TIME b); 46*e7be843bSPierre Pronchery int ossl_time_is_zero(OSSL_TIME t); 47*e7be843bSPierre Pronchery int ossl_time_is_infinite(OSSL_TIME t); 48*e7be843bSPierre Pronchery 49*e7be843bSPierre Pronchery OSSL_TIME ossl_time_add(OSSL_TIME a, OSSL_TIME b); 50*e7be843bSPierre Pronchery OSSL_TIME ossl_time_subtract(OSSL_TIME a, OSSL_TIME b); 51*e7be843bSPierre Pronchery OSSL_TIME ossl_time_multiply(OSSL_TIME a, uint64_t b); 52*e7be843bSPierre Pronchery OSSL_TIME ossl_time_divide(OSSL_TIME a, uint64_t b); 53*e7be843bSPierre Pronchery OSSL_TIME ossl_time_muldiv(OSSL_TIME a, uint64_t b, uint64_t c); 54*e7be843bSPierre Pronchery OSSL_TIME ossl_time_abs_difference(OSSL_TIME a, OSSL_TIME b); 55*e7be843bSPierre Pronchery OSSL_TIME ossl_time_max(OSSL_TIME a, OSSL_TIME b); 56*e7be843bSPierre Pronchery OSSL_TIME ossl_time_min(OSSL_TIME a, OSSL_TIME b); 57*e7be843bSPierre Pronchery 58*e7be843bSPierre Pronchery=head1 DESCRIPTION 59*e7be843bSPierre Pronchery 60*e7be843bSPierre ProncheryThese functions allow the current time to be obtained and for basic 61*e7be843bSPierre Proncheryarithmetic operations to be safely performed with times and durations. 62*e7be843bSPierre Pronchery 63*e7be843bSPierre ProncheryB<OSSL_TIME> can represent a duration, or a point in time. Where it is 64*e7be843bSPierre Proncheryused to represent a point in time, it does so by expressing a duration 65*e7be843bSPierre Proncheryrelative to some reference Epoch. The OSSL_TIME structure itself does 66*e7be843bSPierre Proncherynot contain information about the Epoch used; thus, interpretation of 67*e7be843bSPierre Proncheryan OSSL_TIME requires that the Epoch it is to be interpreted relative 68*e7be843bSPierre Proncheryto is contextually understood. 69*e7be843bSPierre Pronchery 70*e7be843bSPierre ProncheryB<OSSL_TIME_SECOND> is an integer that indicates the precision of an 71*e7be843bSPierre ProncheryB<OSSL_TIME>. Specifically, it is the number of counts per second that 72*e7be843bSPierre Proncherya time can represent. The accuracy is independent of this and is system 73*e7be843bSPierre Proncherydependent. 74*e7be843bSPierre Pronchery 75*e7be843bSPierre ProncheryB<ossl_ticks2time> converts an integral number of counts to a time. 76*e7be843bSPierre Pronchery 77*e7be843bSPierre ProncheryB<ossl_time2ticks> converts a time to an integral number of counts. 78*e7be843bSPierre Pronchery 79*e7be843bSPierre ProncheryB<ossl_seconds2time>, B<ossl_ms2time> and B<ossl_us2time> convert an 80*e7be843bSPierre Proncheryintegral number of seconds, milliseconds and microseconds respectively 81*e7be843bSPierre Proncheryto a time. These functions are implemented as macros. 82*e7be843bSPierre Pronchery 83*e7be843bSPierre ProncheryB<ossl_time2seconds>, B<ossl_time2ms> and B<ossl_time2us> convert a 84*e7be843bSPierre Proncherytime to an integral number of second, milliseconds and microseconds 85*e7be843bSPierre Proncheryrespectively. These functions truncates any fractional seconds and are 86*e7be843bSPierre Proncheryimplemented as macros. 87*e7be843bSPierre Pronchery 88*e7be843bSPierre ProncheryB<ossl_time_zero> returns the smallest representable B<OSSL_TIME>. 89*e7be843bSPierre ProncheryThis value represents the time Epoch and it is returned when an underflow 90*e7be843bSPierre Proncherywould otherwise occur. 91*e7be843bSPierre Pronchery 92*e7be843bSPierre ProncheryB<ossl_time_infinite> returns the largest representable B<OSSL_TIME>. 93*e7be843bSPierre ProncheryThis value is returned when an overflow would otherwise occur. 94*e7be843bSPierre Pronchery 95*e7be843bSPierre ProncheryB<ossl_time_now> returns the current time relative to an Epoch which 96*e7be843bSPierre Proncheryis undefined but unchanging for at least the duration of program 97*e7be843bSPierre Proncheryexecution. The time returned is monotonic and need not represent 98*e7be843bSPierre Proncherywall-clock time. The time returned by this function is useful for 99*e7be843bSPierre Proncheryscheduling timeouts, deadlines and recurring events, but due to its 100*e7be843bSPierre Proncheryundefined Epoch and monotonic nature, is not suitable for other uses. 101*e7be843bSPierre Pronchery 102*e7be843bSPierre ProncheryB<ossl_time_to_timeval> converts a time to a I<struct timeval>. 103*e7be843bSPierre Pronchery 104*e7be843bSPierre ProncheryB<ossl_time_from_timeval> converts a I<struct timeval> to a time. 105*e7be843bSPierre Pronchery 106*e7be843bSPierre ProncheryB<ossl_time_to_time_t> converts a time to a I<time_t>. 107*e7be843bSPierre Pronchery 108*e7be843bSPierre ProncheryB<ossl_time_from_time_t> converts a I<time_t> to a time. 109*e7be843bSPierre Pronchery 110*e7be843bSPierre ProncheryB<ossl_time_compare> compares I<a> with I<b> and returns -1 if I<a> 111*e7be843bSPierre Proncheryis smaller than I<b>, 0 if they are equal and +1 if I<a> is 112*e7be843bSPierre Proncherylarger than I<b>. 113*e7be843bSPierre Pronchery 114*e7be843bSPierre ProncheryB<ossl_time_is_zero> returns 1 if the time I<t> is zero and 0 otherwise. 115*e7be843bSPierre Pronchery 116*e7be843bSPierre ProncheryB<ossl_time_is_infinite> returns 1 if the time I<t> is infinite and 0 otherwise. 117*e7be843bSPierre Pronchery 118*e7be843bSPierre ProncheryB<ossl_time_add> performs a saturating addition of the two times, 119*e7be843bSPierre Proncheryreturning I<a> + I<b>. 120*e7be843bSPierre ProncheryIf the summation would overflow B<OSSL_TIME_INFINITY> is returned. 121*e7be843bSPierre Pronchery 122*e7be843bSPierre ProncheryB<ossl_time_subtract> performs a saturating subtraction of the two items, 123*e7be843bSPierre Proncheryreturning I<a> - I<b>. 124*e7be843bSPierre ProncheryIf the difference would be negative, B<0> is returned. 125*e7be843bSPierre Pronchery 126*e7be843bSPierre ProncheryB<ossl_time_multiply> performs a saturating multiplication of a time value by a 127*e7be843bSPierre Proncherygiven integer multiplier returning I<a> × I<b>. 128*e7be843bSPierre Pronchery 129*e7be843bSPierre ProncheryB<ossl_time_divide> performs division of a time value by a given integer 130*e7be843bSPierre Proncherydivisor returning ⌊I<a> ÷ I<b>⌋. 131*e7be843bSPierre Pronchery 132*e7be843bSPierre ProncheryB<ossl_time_muldiv> performs a fused multiplication and division operation. 133*e7be843bSPierre ProncheryThe result is equal to ⌊I<a> × I<b> ÷ I<c>⌋. 134*e7be843bSPierre Pronchery 135*e7be843bSPierre ProncheryB<ossl_time_abs_difference> returns the magnitude of the difference between two 136*e7be843bSPierre Proncherytime values. 137*e7be843bSPierre Pronchery 138*e7be843bSPierre ProncheryB<ossl_time_min> returns the lesser of two time values. 139*e7be843bSPierre Pronchery 140*e7be843bSPierre ProncheryB<ossl_time_max> returns the greater of two time values. 141*e7be843bSPierre Pronchery 142*e7be843bSPierre Pronchery=head1 NOTES 143*e7be843bSPierre Pronchery 144*e7be843bSPierre ProncheryThe largest representable duration is guaranteed to be at least 500 years. 145*e7be843bSPierre Pronchery 146*e7be843bSPierre Pronchery=head1 RETURN VALUES 147*e7be843bSPierre Pronchery 148*e7be843bSPierre ProncheryB<ossl_time_now> returns the current time, or the time of the Epoch on error. 149*e7be843bSPierre Pronchery 150*e7be843bSPierre ProncheryB<ossl_time_zero> returns the time of the Epoch. 151*e7be843bSPierre Pronchery 152*e7be843bSPierre ProncheryB<ossl_time_infinite> returns the last representable time. 153*e7be843bSPierre Pronchery 154*e7be843bSPierre ProncheryB<ossl_ticks2time>, B<ossl_seconds2time>, B<ossl_ms2time> and B<ossl_us2time> 155*e7be843bSPierre Proncheryreturn the duration specified in ticks, seconds, milliseconds and microseconds 156*e7be843bSPierre Proncheryrespectively. 157*e7be843bSPierre Pronchery 158*e7be843bSPierre ProncheryB<ossl_time2ticks>, B<ossl_time2seconds>, B<ossl_time2ms> and B<ossl_time2us> 159*e7be843bSPierre Proncheryreturn the number of ticks, seconds, microseconds and microseconds respectively 160*e7be843bSPierre Proncherythat the time object represents. 161*e7be843bSPierre Pronchery 162*e7be843bSPierre ProncheryB<ossl_time_to_timeval>, B<ossl_time_from_timeval>, B<ossl_time_to_time_t> and 163*e7be843bSPierre ProncheryB<ossl_time_from_time_t> all return the converted time. 164*e7be843bSPierre Pronchery 165*e7be843bSPierre ProncheryB<ossl_time_compare> returns -1, 0 or 1 depending on the comparison. 166*e7be843bSPierre Pronchery 167*e7be843bSPierre ProncheryB<ossl_time_is_zero> and B<ossl_time_is_infinite> return 1 if the condition 168*e7be843bSPierre Proncheryis true and 0 otherwise. 169*e7be843bSPierre Pronchery 170*e7be843bSPierre ProncheryB<ossl_time_add> returns the summation of the two times or 171*e7be843bSPierre Proncherythe last representable time on overflow. 172*e7be843bSPierre Pronchery 173*e7be843bSPierre ProncheryB<ossl_time_subtract> returns the difference of the two times or the 174*e7be843bSPierre Proncherytime of the Epoch on underflow. 175*e7be843bSPierre Pronchery 176*e7be843bSPierre ProncheryB<ossl_time_multiply> returns the result of multiplying the given time by the 177*e7be843bSPierre Proncherygiven integral multiplier, or B<OSSL_TIME_INFINITY> on overflow. 178*e7be843bSPierre Pronchery 179*e7be843bSPierre ProncheryB<ossl_time_divide> returns the result of dividing the given time by the given 180*e7be843bSPierre Proncheryintegral divisor. 181*e7be843bSPierre Pronchery 182*e7be843bSPierre ProncheryB<ossl_time_muldiv> returns the fused multiplication and division of the given 183*e7be843bSPierre Proncherytime and the two integral values. 184*e7be843bSPierre Pronchery 185*e7be843bSPierre ProncheryB<ossl_time_abs_difference> returns the magnitude of the difference between the 186*e7be843bSPierre Proncheryinput time values. 187*e7be843bSPierre Pronchery 188*e7be843bSPierre ProncheryB<ossl_time_min> and B<ossl_time_max> choose and return one of the input values. 189*e7be843bSPierre Pronchery 190*e7be843bSPierre Pronchery=head1 HISTORY 191*e7be843bSPierre Pronchery 192*e7be843bSPierre ProncheryThis functionality was added in OpenSSL 3.2. 193*e7be843bSPierre Pronchery 194*e7be843bSPierre Pronchery=head1 COPYRIGHT 195*e7be843bSPierre Pronchery 196*e7be843bSPierre ProncheryCopyright 2022 The OpenSSL Project Authors. All Rights Reserved. 197*e7be843bSPierre Pronchery 198*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use this 199*e7be843bSPierre Proncheryfile except in compliance with the License. You can obtain a copy in the file 200*e7be843bSPierre ProncheryLICENSE in the source distribution or at 201*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>. 202*e7be843bSPierre Pronchery 203*e7be843bSPierre Pronchery=cut 204