From: Hugo Landau Date: Mon, 13 May 2024 19:20:23 +0000 (+0100) Subject: QUIC: Update SSL_poll documentation X-Git-Tag: openssl-3.5.0-alpha1~339 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b20f55702100f65ee271d9e4c321de8b579a34a0;p=thirdparty%2Fopenssl.git QUIC: Update SSL_poll documentation Reviewed-by: Matt Caswell Reviewed-by: Saša Nedvědický Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/25416) --- diff --git a/doc/man3/SSL_poll.pod b/doc/man3/SSL_poll.pod index 8622e775691..3b376742151 100644 --- a/doc/man3/SSL_poll.pod +++ b/doc/man3/SSL_poll.pod @@ -76,7 +76,8 @@ SSL_POLL_FLAG_NO_HANDLE_EVENTS SSL_poll() allows the readiness conditions of the resources represented by one or more BIO_POLL_DESCRIPTOR structures to be determined. In particular, it can be used to query for readiness conditions on QUIC connection SSL objects and -QUIC stream SSL objects in a single call. +QUIC stream SSL objects in a single call. It can also be used to block until at +least one of the given resources is ready. A call to SSL_poll() specifies an array of B structures, each of which designates a resource which is being polled for readiness, and a set of @@ -123,13 +124,32 @@ array need remain allocated only for the duration of the call. I must be set to the number of entries in the array, and I must be set to C. +The I argument specifies the timeout to use, and, implicitly, whether +to use SSL_poll() in blocking or nonblocking mode: + +=over 4 + +=item * + +If I is NULL, the function blocks indefinitely until at least one +resource is ready. + +=item * + +If I is non-NULL, and it points to a B which is set to +zero, the function operates in nonblocking mode and returns immediately with +readiness information. + +=item * + +If I is non-NULL, and it points to a B which is set to +a value other than zero, the function blocks for the specified interval or until +at least one of the specified resources is ready, whichever comes first. + +=back + The present implementation of SSL_poll() is a subset of the functionality which -will eventually be available. Only a nonblocking mode of operation is available -at this time, where SSL_poll() always returns immediately. As such, I -must point to a valid B and that structure must be set to zero. -In future, other inputs to the I argument will result in a blocking -mode of operation, which is not currently supported. For more information, see -L. +will eventually be available. For more information, see L. The following flags are currently defined for the I argument: @@ -141,6 +161,12 @@ This flag indicates that internal state machine processing should not be performed in an attempt to generate new readiness events. Only existing readiness events will be reported. +If this flag is used in nonblocking mode (with a timeout of zero), no internal +state machine processing is performed. + +If this flag is used in blocking mode (for example, with I set to +NULL), event processing does not occur unless the function blocks. + =back The I argument is optional. If it is non-NULL, it is used to @@ -197,6 +223,15 @@ information. This event type may be raised even if it was not requested in I; specifying this event type in I does nothing. +=item B + +Error at listener level. This event is raised when a listener has failed, for +example if a network BIO has encountered a permanent error. + +This event is never raised on objects which are not listeners, but its +occurrence will cause B to be raised on all dependent +connections. + =item B Error at connection level. This event is raised when a connection has failed. @@ -204,7 +239,7 @@ In particular, it is raised when a connection begins terminating. This event is never raised on objects which are not connections. -=item B +=item B Error at connection level (drained). This event is raised when a connection has finished terminating, and has reached the terminated state. This event will @@ -250,6 +285,12 @@ L). This event does not guarantee that a subsequent call to L will succeed. +=item B + +This event, which is only raised by a QUIC listener SSL object, is raised when +one or more incoming QUIC connections are available to be accepted using +L. + =item B This event, which is only raised by a QUIC connection SSL object, is raised when @@ -278,29 +319,19 @@ unidirectional stream to be locally created. =head1 LIMITATIONS -SSL_poll() as presently implemented has the following limitations: +SSL_poll() as presently implemented has the following limitation: =over 4 =item -The implementation of SSL_poll() only supports nonblocking operation and -therefore requires the I argument be used to specify a zero timeout. -Calls to SSL_poll() which specify another value, or which pass I as -NULL, will fail. This does not allow waiting, but does allow multiple QUIC SSL -objects to be queried for their readiness state in a single call. - -Future releases will remove this limitation and support blocking SSL_poll(). - -=item - Only B structures with type B, referencing QUIC connection SSL objects or QUIC stream SSL objects, are supported. =back -These limitations will be revised in a future release of OpenSSL. +This limitation may be revised in a future release of OpenSSL. =head1 RETURN VALUES @@ -377,6 +408,13 @@ L, L SSL_poll() was added in OpenSSL 3.3. +Before @VERSION_QUIC_SERVER@, SSL_poll() did not support blocking operation and +would fail if called with a NULL I parameter or a I parameter +pointing to a B which was not zero. + +Before @VERSION_QUIC_SERVER@, the B and B +event types were not present. + =head1 COPYRIGHT Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/SSL_set_blocking_mode.pod b/doc/man3/SSL_set_blocking_mode.pod index aca7ce7405e..1967afdbda4 100644 --- a/doc/man3/SSL_set_blocking_mode.pod +++ b/doc/man3/SSL_set_blocking_mode.pod @@ -55,7 +55,8 @@ SSL_get_blocking_mode() returns 1 if blocking is currently enabled. It returns =head1 SEE ALSO -L, L +L, L, L, +L, L =head1 HISTORY