Document the state of the object you get from SSL_accept_connection()

The object may or may not have completed its handshake.

See also:
https://github.com/openssl/openssl/pull/27239#issuecomment-2772148408

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/27283)

diff --git a/doc/man3/SSL_new_listener.pod b/doc/man3/SSL_new_listener.pod
index b830bd11bd17453fc7e771de48d48a4b0f84f924..291c103381e7e440532345e6f48698c5893479a3 100644 (file)
--- a/doc/man3/SSL_new_listener.pod
+++ b/doc/man3/SSL_new_listener.pod
@@ -130,6 +130,14 @@ connection is created and returned on success. If no incoming connection is
 available and the listener SSL object is configured in nonblocking mode, NULL is
 returned.
 
+The new SSL object returned from SSL_accept_connection() may or may not have
+completed its handshake at the point it is returned. Optionally, you may use the
+function L<SSL_is_init_finished(3)> to determine this. You may call the
+functions L<SSL_accept(3)>, L<SSL_do_handshake(3)> or L<SSL_handle_events(3)> to
+progress the state of the SSL object towards handshake completion. Other "I/O"
+functions may also implicitly progress the state of the handshake such as
+L<SSL_poll(3)>, L<SSL_read(3)> and L<SSL_write(3)>.
+
 The B<SSL_ACCEPT_CONNECTION_NO_BLOCK> flag may be specified to
 SSL_accept_connection(). If specified, the call does not block even if the
 listener SSL object is configured in blocking mode.