From b626a0f1fdd306845e5ff7632329d32d5f9e2fba Mon Sep 17 00:00:00 2001 From: Hugo Landau Date: Wed, 24 May 2023 16:06:22 +0100 Subject: [PATCH] SSL_handle_events(): Minor fixes to documentation Reviewed-by: Matt Caswell Reviewed-by: Tim Hudson Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/20879) --- doc/man3/DTLSv1_handle_timeout.pod | 2 +- doc/man3/SSL_get_event_timeout.pod | 9 +++++---- doc/man3/SSL_handle_events.pod | 8 ++++---- ssl/quic/quic_impl.c | 9 +++++---- 4 files changed, 15 insertions(+), 13 deletions(-) diff --git a/doc/man3/DTLSv1_handle_timeout.pod b/doc/man3/DTLSv1_handle_timeout.pod index bb2bafe4e4..4c7dfff7f8 100644 --- a/doc/man3/DTLSv1_handle_timeout.pod +++ b/doc/man3/DTLSv1_handle_timeout.pod @@ -22,7 +22,7 @@ when to call DTLSv1_handle_timeout(). This function is only applicable to DTLS or QUIC SSL objects. It returns 0 if called on any other kind of SSL object. -L supersedes all use cases for this this function and may +L supersedes all use cases for this function and may be used instead of it. =head1 RETURN VALUES diff --git a/doc/man3/SSL_get_event_timeout.pod b/doc/man3/SSL_get_event_timeout.pod index e0a1c46556..8649cb4f03 100644 --- a/doc/man3/SSL_get_event_timeout.pod +++ b/doc/man3/SSL_get_event_timeout.pod @@ -2,7 +2,8 @@ =head1 NAME -SSL_get_event_timeout - determine when an SSL object next needs to be ticked +SSL_get_event_timeout - determine when an SSL object next needs to have events +handled =head1 SYNOPSIS @@ -24,8 +25,8 @@ cases applies: =item -The SSL object has events which need to be handled immediately; I<*tv> is set to -zero and I<*is_infinite> is set to 0. +The SSL object has events which need to be handled immediately; The fields of +I<*tv> are set to 0 and I<*is_infinite> is set to 0. =item @@ -53,7 +54,7 @@ considered a success condition. Note that the value output by a call to SSL_get_event_timeout() may change as a result of other calls to the SSL object. -Once the timeout expires, SSL_handle_events() should be called to handle any +Once the timeout expires, L should be called to handle any internal processing which is due; for more information, see L. diff --git a/doc/man3/SSL_handle_events.pod b/doc/man3/SSL_handle_events.pod index 85184ec8eb..e02eb33ee1 100644 --- a/doc/man3/SSL_handle_events.pod +++ b/doc/man3/SSL_handle_events.pod @@ -38,10 +38,10 @@ cases of L, it should be preferred for new applications which do not require support for OpenSSL 3.1 or older. When using DTLS, an application must call SSL_handle_events() as indicated by -calls to L; ticking is not performed automatically by -calls to other SSL functions such as L or L. Note -that this is different to QUIC which also performs ticking implicitly; see -below. +calls to L; event handling is not performed +automatically by calls to other SSL functions such as L or +L. Note that this is different to QUIC which also performs event +handling implicitly; see below. =item QUIC connection SSL objects diff --git a/ssl/quic/quic_impl.c b/ssl/quic/quic_impl.c index d9ee5cf96e..d00f4455b0 100644 --- a/ssl/quic/quic_impl.c +++ b/ssl/quic/quic_impl.c @@ -839,7 +839,7 @@ static int xso_blocking_mode(const QUIC_XSO *xso) && xso->conn->can_poll_net_wbio; } -/* SSL_handle_events; handles events by ticking the reactor. */ +/* SSL_handle_events; performs QUIC I/O and timeout processing. */ QUIC_TAKES_LOCK int ossl_quic_handle_events(SSL *s) { @@ -856,9 +856,10 @@ int ossl_quic_handle_events(SSL *s) /* * SSL_get_event_timeout. Get the time in milliseconds until the SSL object - * should be ticked by the application by calling SSL_handle_events(). tv is set - * to 0 if the object should be ticked immediately. If no timeout is currently - * active, *is_infinite is set to 1 and the value of *tv is undefined. + * should next have events handled by the application by calling + * SSL_handle_events(). tv is set to 0 if the object should have events handled + * immediately. If no timeout is currently active, *is_infinite is set to 1 and + * the value of *tv is undefined. */ QUIC_TAKES_LOCK int ossl_quic_get_event_timeout(SSL *s, struct timeval *tv, int *is_infinite)