add BIO_socket_wait(), BIO_wait(), and BIO_connect_retry() improving timeout support

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/10667)

1 files changed, 53 insertions, 0 deletions

diff --git a/doc/man3/BIO_socket_wait.pod b/doc/man3/BIO_socket_wait.pod
new file mode 100644
index 0000000000..845389215b
--- /dev/null
+++ b/doc/man3/BIO_socket_wait.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+BIO_socket_wait,
+BIO_wait,
+BIO_connect_retry
+- BIO socket utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ int BIO_socket_wait(int fd, int for_read, time_t max_time);
+ int BIO_wait(BIO *bio, time_t max_time);
+ int BIO_connect_retry(BIO *bio, long timeout);
+
+=head1 DESCRIPTION
+
+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 on the socket underlying the given B<bio>, for reading if
+B<bio> is supposed to read, else for writing, at most until B<max_time>.
+It succeeds immediately if B<max_time> == 0 (which means no timeout given).
+
+BIO_connect_retry() connects via the given B<bio>, retrying BIO_do_connect()
+until success or a timeout or error condition is reached.
+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.
+
+=head1 RETURN VALUES
+
+BIO_socket_wait(), BIO_wait(), and BIO_connect_retry()
+return -1 on error, 0 on timeout, and 1 on success.
+
+=head1 HISTORY
+
+BIO_socket_wait(), BIO_wait(), and BIO_connect_retry()
+were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut