fix: Better documentation on DTLS_set_timer_cb()

Also more precise description of DTLS timeout mechanism.

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/27800)

diff --git a/doc/man3/DTLS_set_timer_cb.pod b/doc/man3/DTLS_set_timer_cb.pod
index 5014e77d0fc892940f6e025f047b2890071eec8e..cf9e295394e5a0e2834738ee473a80ce6ed14da6 100644 (file)
--- a/doc/man3/DTLS_set_timer_cb.pod
+++ b/doc/man3/DTLS_set_timer_cb.pod
@@ -20,6 +20,17 @@ This function sets an optional callback function for controlling the
 timeout interval on the DTLS protocol. The callback function will be
 called by DTLS for every new DTLS packet that is sent.
 
+The callback should return the timeout interval in micro seconds.
+
+The I<timer_us> parameter of the callback is the last set timeout
+interval returned. On the first invocation of the callback,
+this value will be 0.
+
+At the beginning of the connection, if no timeout callback has been
+set via DTLS_set_timer_cb(), the default timeout value is 1 second.
+For all subsequent timeouts, the default behavior is to double the
+duration up to a maximum of 1 minute.
+
 =head1 RETURN VALUES
 
 Returns void.