Improve BIO_socket_wait(), BIO_wait(), BIO_connect_retry(), and their docs

Add/extend range check for 'fd' argument of BIO_socket_wait() and bio_wait()
Correct nap time calculations in bio_wait(), thus correcting also BIO_wait()
Update a type cast from 'unsigned long' to 'unsigned int'
Extend the comments and documentation of BIO_wait()

Rename BIO_connect_retry() to BIO_do_connect_retry()
Make its 'timeout' argument < 0 lead to BIO_do_connect() tried only once
Add optional 'nap_milliseconds' parameter determining the polling granularity
Correct and generalize the retry case checking
Extend the comments and documentation of BIO_do_connect_retry()

Reviewed-by: Bernd Edlinger <bernd.edlinger@hotmail.de>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11986)

3 files changed, 29 insertions, 18 deletions

diff --git a/doc/man3/BIO_socket_wait.pod b/doc/man3/BIO_socket_wait.pod
index d105dfe698..b00a878c9d 100644
--- a/doc/man3/BIO_socket_wait.pod
+++ b/doc/man3/BIO_socket_wait.pod
@@ -4,8 +4,8 @@
 
 BIO_socket_wait,
 BIO_wait,
-BIO_connect_retry
-- BIO socket utility functions
+BIO_do_connect_retry
+- BIO connection utility functions
 
 =head1 SYNOPSIS
 
@@ -14,8 +14,8 @@ BIO_connect_retry
  #ifndef OPENSSL_NO_SOCK
  int BIO_socket_wait(int fd, int for_read, time_t max_time);
  #endif
- int BIO_wait(BIO *bio, time_t max_time, unsigned int milliseconds);
- int BIO_connect_retry(BIO *bio, long timeout);
+ int BIO_wait(BIO *bio, time_t max_time, unsigned int nap_milliseconds);
+ int BIO_do_connect_retry(BIO *bio, int timeout, int nap_milliseconds);
 
 =head1 DESCRIPTION
 
@@ -23,27 +23,38 @@ BIO_socket_wait() waits on the socket B<fd> for reading if B<for_read> is not 0,
 else for writing, at most until B<max_time>.
 It succeeds immediately if B<max_time> == 0 (which means no timeout given).
 
-BIO_wait() waits at most until B<max_time> on the given B<bio>,
-which is typically socket-based,
-for reading if B<bio> is supposed to read, else for writing.
+BIO_wait() waits at most until B<max_time> on the given (typically socket-based)
+B<bio>, for reading if B<bio> is supposed to read, else for writing.
+It is used by BIO_do_connect_retry() and can be used together L<BIO_read(3)>.
 It succeeds immediately if B<max_time> == 0 (which means no timeout given).
-If sockets are not available it succeeds after waiting at most given
-B<milliseconds> in order to help avoiding a tight busy loop at the caller.
-
-BIO_connect_retry() connects via the given B<bio>, retrying BIO_do_connect()
-until success or a timeout or error condition is reached.
+If sockets are not available it supports polling by succeeding after sleeping
+at most the given B<nap_milliseconds> in order to avoid a tight busy loop.
+Via B<nap_milliseconds> the caller determines the polling granularity.
+
+BIO_do_connect_retry() connects via the given B<bio>.
+It retries BIO_do_connect() as far as needed to reach a definite outcome,
+i.e., connection succeeded, timeout has been reached, or an error occurred.
+For non-blocking and potentially even non-socket BIOs it polls
+every B<nap_milliseconds> and sleeps in between using BIO_wait().
+If B<nap_milliseconds> is < 0 then a default value of 100 ms is used.
 If the B<timeout> parameter is > 0 this indicates the maximum number of seconds
-to wait until the connection is established. A value of 0 enables waiting
-indefinitely, while a value < 0 immediately leads to a timeout condition.
+to wait until the connection is established or a definite error occurred.
+A value of 0 enables waiting indefinitely (i.e, no timeout),
+while a value < 0 means that BIO_do_connect() is tried only once.
+The function may, directly or indirectly, invoke ERR_clear_error().
 
 =head1 RETURN VALUES
 
-BIO_socket_wait(), BIO_wait(), and BIO_connect_retry()
+BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry()
 return -1 on error, 0 on timeout, and 1 on success.
 
+=head1 SEE ALSO
+
+L<BIO_do_connect(3)>, L<BIO_read(3)>
+
 =head1 HISTORY
 
-BIO_socket_wait(), BIO_wait(), and BIO_connect_retry()
+BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry()
 were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod
index 97927fb45e..e8237b46e7 100644
--- a/doc/man3/OSSL_CMP_CTX_new.pod
+++ b/doc/man3/OSSL_CMP_CTX_new.pod
@@ -337,7 +337,7 @@ function, which has the prototype
 The callback may modify the BIO B<bio> provided by OSSL_CMP_MSG_http_perform(),
 whereby it may make use of a custom defined argument B<ctx>
 stored in the OSSL_CMP_CTX by means of OSSL_CMP_CTX_set_http_cb_arg().
-During connection establishment, just after calling BIO_connect_retry(),
+During connection establishment, just after calling BIO_do_connect_retry(),
 the function is invoked with the B<connect> argument being 1 and the B<detail>
 argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled. On
 disconnect B<connect> is 0 and B<detail> is 1 in case no error occurred, else 0.
diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod
index e0adb2a1d1..4459f541f3 100644
--- a/doc/man3/OSSL_HTTP_transfer.pod
+++ b/doc/man3/OSSL_HTTP_transfer.pod
@@ -154,7 +154,7 @@ B<bio_update_fn> is a BIO connect/disconnect callback function with prototype
 The callback may modify the HTTP BIO provided in the B<bio> argument,
 whereby it may make use of a custom defined argument B<arg>,
 which may for instance refer to an I<SSL_CTX> structure.
-During connection establishment, just after calling BIO_connect_retry(),
+During connection establishment, just after calling BIO_do_connect_retry(),
 the function is invoked with the B<connect> argument being 1 and the B<detail>
 argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled.
 On disconnect B<connect> is 0 and B<detail> is 1 if no error occurred, else 0.