1*e7be843bSPierre Pronchery=pod 2*e7be843bSPierre Pronchery 3*e7be843bSPierre Pronchery=head1 NAME 4*e7be843bSPierre Pronchery 5*e7be843bSPierre ProncherySSL_get_event_timeout - determine when an SSL object next needs to have events 6*e7be843bSPierre Proncheryhandled 7*e7be843bSPierre Pronchery 8*e7be843bSPierre Pronchery=head1 SYNOPSIS 9*e7be843bSPierre Pronchery 10*e7be843bSPierre Pronchery #include <openssl/ssl.h> 11*e7be843bSPierre Pronchery 12*e7be843bSPierre Pronchery int SSL_get_event_timeout(SSL *s, struct timeval *tv, int *is_infinite); 13*e7be843bSPierre Pronchery 14*e7be843bSPierre Pronchery=head1 DESCRIPTION 15*e7be843bSPierre Pronchery 16*e7be843bSPierre ProncherySSL_get_event_timeout() determines when the SSL object next needs to perform 17*e7be843bSPierre Proncheryinternal processing due to the passage of time. 18*e7be843bSPierre Pronchery 19*e7be843bSPierre ProncheryAll arguments are required; I<tv> and I<is_infinite> must be non-NULL. 20*e7be843bSPierre Pronchery 21*e7be843bSPierre ProncheryUpon the successful return of SSL_get_event_timeout(), one of the following 22*e7be843bSPierre Proncherycases applies: 23*e7be843bSPierre Pronchery 24*e7be843bSPierre Pronchery=over 4 25*e7be843bSPierre Pronchery 26*e7be843bSPierre Pronchery=item 27*e7be843bSPierre Pronchery 28*e7be843bSPierre ProncheryThe SSL object has events which need to be handled immediately; The fields of 29*e7be843bSPierre ProncheryI<*tv> are set to 0 and I<*is_infinite> is set to 0. 30*e7be843bSPierre Pronchery 31*e7be843bSPierre Pronchery=item 32*e7be843bSPierre Pronchery 33*e7be843bSPierre ProncheryThe SSL object has events which need to be handled after some amount of time 34*e7be843bSPierre Pronchery(relative to the time at which SSL_get_event_timeout() was called). I<*tv> is 35*e7be843bSPierre Proncheryset to the amount of time after which L<SSL_handle_events(3)> should be called 36*e7be843bSPierre Proncheryand I<*is_infinite> is set to 0. 37*e7be843bSPierre Pronchery 38*e7be843bSPierre Pronchery=item 39*e7be843bSPierre Pronchery 40*e7be843bSPierre ProncheryThere are currently no timer events which require handling in the future. The 41*e7be843bSPierre Proncheryvalue of I<*tv> is unspecified and I<*is_infinite> is set to 1. 42*e7be843bSPierre Pronchery 43*e7be843bSPierre Pronchery=back 44*e7be843bSPierre Pronchery 45*e7be843bSPierre ProncheryThis function is currently applicable only to DTLS and QUIC connection SSL 46*e7be843bSPierre Proncheryobjects. If it is called on any other kind of SSL object, it always outputs 47*e7be843bSPierre Proncheryinfinity. This is considered a success condition. 48*e7be843bSPierre Pronchery 49*e7be843bSPierre ProncheryFor DTLS, this function can be used instead of the older 50*e7be843bSPierre ProncheryL<DTLSv1_get_timeout(3)> function. Note that this function differs from 51*e7be843bSPierre ProncheryL<DTLSv1_get_timeout(3)> in that the case where no timeout is active is 52*e7be843bSPierre Proncheryconsidered a success condition. 53*e7be843bSPierre Pronchery 54*e7be843bSPierre ProncheryNote that the value output by a call to SSL_get_event_timeout() may change as a 55*e7be843bSPierre Proncheryresult of other calls to the SSL object. 56*e7be843bSPierre Pronchery 57*e7be843bSPierre ProncheryOnce the timeout expires, L<SSL_handle_events(3)> should be called to handle any 58*e7be843bSPierre Proncheryinternal processing which is due; for more information, see 59*e7be843bSPierre ProncheryL<SSL_handle_events(3)>. 60*e7be843bSPierre Pronchery 61*e7be843bSPierre ProncheryNote that SSL_get_event_timeout() supersedes the older L<DTLSv1_get_timeout(3)> 62*e7be843bSPierre Proncheryfunction for all use cases. 63*e7be843bSPierre Pronchery 64*e7be843bSPierre ProncheryIf the call to SSL_get_event_timeout() fails, the values of I<*tv> and 65*e7be843bSPierre ProncheryI<*is_infinite> may still be changed and their values become unspecified. 66*e7be843bSPierre Pronchery 67*e7be843bSPierre Pronchery=head1 RETURN VALUES 68*e7be843bSPierre Pronchery 69*e7be843bSPierre ProncheryReturns 1 on success and 0 on failure. 70*e7be843bSPierre Pronchery 71*e7be843bSPierre Pronchery=head1 SEE ALSO 72*e7be843bSPierre Pronchery 73*e7be843bSPierre ProncheryL<SSL_handle_events(3)>, L<DTLSv1_get_timeout(3)>, L<ssl(7)> 74*e7be843bSPierre Pronchery 75*e7be843bSPierre Pronchery=head1 HISTORY 76*e7be843bSPierre Pronchery 77*e7be843bSPierre ProncheryThe SSL_get_event_timeout() function was added in OpenSSL 3.2. 78*e7be843bSPierre Pronchery 79*e7be843bSPierre Pronchery=head1 COPYRIGHT 80*e7be843bSPierre Pronchery 81*e7be843bSPierre ProncheryCopyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved. 82*e7be843bSPierre Pronchery 83*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 84*e7be843bSPierre Proncherythis file except in compliance with the License. You can obtain a copy 85*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at 86*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>. 87*e7be843bSPierre Pronchery 88*e7be843bSPierre Pronchery=cut 89