From: noctuelles <plouvel@student.42.fr>
Date: Tue, 10 Jun 2025 20:37:46 +0000 (+0200)
Subject: fix: Better documentation on DTLS_set_timer_cb()
X-Git-Tag: openssl-3.5.1~27
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5b2a1b6f309634f78cdb05f3ffdf7e353c56afab;p=thirdparty%2Fopenssl.git

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)

(cherry picked from commit 49885aebe7cafc5caaa6929d0ed5a946e7f09c45)
---

diff --git a/doc/man3/DTLS_set_timer_cb.pod b/doc/man3/DTLS_set_timer_cb.pod
index 5014e77d0fc..cf9e295394e 100644
--- 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.