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