--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_poll,
+SSL_POLL_EVENT_NONE,
+SSL_POLL_EVENT_F,
+SSL_POLL_EVENT_EC,
+SSL_POLL_EVENT_ECD,
+SSL_POLL_EVENT_ER,
+SSL_POLL_EVENT_EW,
+SSL_POLL_EVENT_R,
+SSL_POLL_EVENT_W,
+SSL_POLL_EVENT_ISB,
+SSL_POLL_EVENT_ISU,
+SSL_POLL_EVENT_OSB,
+SSL_POLL_EVENT_OSU,
+SSL_POLL_EVENT_RW,
+SSL_POLL_EVENT_RE,
+SSL_POLL_EVENT_WE,
+SSL_POLL_EVENT_RWE,
+SSL_POLL_EVENT_E,
+SSL_POLL_EVENT_IS,
+SSL_POLL_EVENT_ISE,
+SSL_POLL_EVENT_I,
+SSL_POLL_EVENT_OS,
+SSL_POLL_EVENT_OSE,
+SSL_POLL_FLAG_NO_HANDLE_EVENTS
+- determine or await readiness conditions for one or more pollable objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ #define SSL_POLL_EVENT_NONE 0
+
+ #define SSL_POLL_EVENT_F /* F (Failure) */
+ #define SSL_POLL_EVENT_EC /* EC (Exception on Conn) */
+ #define SSL_POLL_EVENT_ECD /* ECD (Exception on Conn Drained) */
+ #define SSL_POLL_EVENT_ER /* ER (Exception on Read) */
+ #define SSL_POLL_EVENT_EW /* EW (Exception on Write) */
+ #define SSL_POLL_EVENT_R /* R (Readable) */
+ #define SSL_POLL_EVENT_W /* W (Writable) */
+ #define SSL_POLL_EVENT_ISB /* ISB (Incoming Stream: Bidi) */
+ #define SSL_POLL_EVENT_ISU /* ISU (Incoming Stream: Uni) */
+ #define SSL_POLL_EVENT_OSB /* OSB (Outgoing Stream: Bidi) */
+ #define SSL_POLL_EVENT_OSU /* OSU (Outgoing Stream: Uni) */
+
+ #define SSL_POLL_EVENT_RW /* R | W */
+ #define SSL_POLL_EVENT_RE /* R | ER */
+ #define SSL_POLL_EVENT_WE /* W | EW */
+ #define SSL_POLL_EVENT_RWE /* RE | WE */
+ #define SSL_POLL_EVENT_E /* EC | ER | EW */
+ #define SSL_POLL_EVENT_IS /* ISB | ISU */
+ #define SSL_POLL_EVENT_ISE /* IS | EC */
+ #define SSL_POLL_EVENT_I /* IS */
+ #define SSL_POLL_EVENT_OS /* OSB | OSU */
+ #define SSL_POLL_EVENT_OSE /* OS | EC */
+
+ typedef struct ssl_poll_item_st {
+ BIO_POLL_DESCRIPTOR desc;
+ uint64_t events, revents;
+ } SSL_POLL_ITEM;
+
+ #define SSL_POLL_FLAG_NO_HANDLE_EVENTS
+
+ int SSL_poll(SSL_POLL_ITEM *items,
+ size_t num_items,
+ size_t stride,
+ const struct timeval *timeout,
+ uint64_t flags,
+ size_t *result_count);
+
+=head1 DESCRIPTION
+
+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.
+
+A call to SSL_poll() specifies an array of B<SSL_POLL_ITEM> structures, each of
+which designates a resource which is being polled for readiness, and a set of
+event flags which indicate the specific readiness events which the caller is
+interested in in relation to the specified resource.
+
+The fields of B<SSL_POLL_ITEM> are as follows:
+
+=over 4
+
+=item I<desc>
+
+The resource being polled for readiness, as represented by a
+B<BIO_POLL_DESCRIPTOR>. Currently, this must be a poll descriptor of type
+B<BIO_POLL_DESCRIPTOR_TYPE_SSL>, representing a SSL object pointer, and the SSL
+object must be to a QUIC connection SSL object or QUIC stream SSL object.
+
+If a B<SSL_POLL_ITEM> has a poll descriptor type of
+B<BIO_POLL_DESCRIPTOR_TYPE_NONE>, or the SSL object pointer is NULL, the
+B<SSL_POLL_ITEM> array entry is ignored and I<revents> will be set to 0 on
+return.
+
+=item I<events>
+
+This is the set of zero or more events which the caller is interested in
+learning about in relation to the resource described by I<desc>. It is a
+collection of zero or more B<SSL_POLL_EVENT> flags. See L</EVENT TYPES> for a
+description of each of the event types.
+
+=item I<revents>
+
+After SSL_poll() returns, this is the set of zero or more events which are
+actually applicable to the resource described by I<desc>. As for I<events>,
+it is a collection of zero or more B<SSL_POLL_EVENT> flags.
+
+I<revents> need not be a subset of the events specified in I<events>, as some
+event types are defined as always being enabled (non-maskable). See L</EVENT
+TYPES> for more information.
+
+=back
+
+To use SSL_poll(), call it with an array of B<SSL_POLL_ITEM> structures. The
+array need remain allocated only for the duration of the call. I<num_items> must
+be set to the number of entries in the array, and I<stride> must be set to
+C<sizeof(SSL_POLL_ITEM)>.
+
+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<timeout>
+must point to a valid B<struct timeval> and that structure must be set to zero.
+In future, other inputs to the I<timeout> argument will result in a blocking
+mode of operation, which is not currently supported. For more information, see
+L</LIMITATIONS>.
+
+The following flags are currently defined for the I<flags> argument:
+
+=over 4
+
+=item B<SSL_POLL_FLAG_NO_HANDLE_EVENTS>
+
+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.
+
+=back
+
+The I<result_count> argument is optional. If it is non-NULL, it is used to
+output the number of entries in the array which have nonzero I<revents> fields
+when the call to SSL_poll() returns; see L</RETURN VALUES> for details.
+
+=head1 EVENT TYPES
+
+The SSL_poll() interface reports zero or more event types on a given resource,
+represented by a bit mask.
+
+All of the event types are level triggered and represent a readiness or
+permanent exception condition; as such, after an event has been reported by
+SSL_poll() for a resource, it will continue to be reported in future SSL_poll()
+calls until the condition ceases to be in effect. A caller must mask the given
+event type bit in future SSL_poll() calls if it does not wish to receive
+repeated notifications and has not caused the underlying readiness condition
+(for example, consuming all available data using L<SSL_read_ex(3)> after
+B<SSL_POLL_EVENT_R> is reported) to be deasserted.
+
+Some event types do not make sense on a given kind of resource. In this case,
+specifying that event type in I<events> is a no-op and will be ignored, and the
+given event will never be reported in I<revents>.
+
+Failure of the polling mechanism itself is considered distinct from an exception
+condition on a resource which was successfully polled. See B<SSL_POLL_EVENT_F>
+and L</RETURN VALUES> for details.
+
+In general, an application should always listen for the event types
+corresponding to exception conditions if it is listening to the corresponding
+non-exception event types (e.g. B<SSL_POLL_EVENT_EC> and B<SSL_POLL_EVENT_ER>
+for B<SSL_POLL_EVENT_R>), as not doing so is unlikely to be a sound design.
+
+Some event types are non-maskable and may be reported in I<revents> regardless
+of whether they were requested in I<events>.
+
+The following event types are supported:
+
+=over 4
+
+=item B<SSL_POLL_EVENT_F>
+
+Polling failure. This event is raised when a resource could not be polled. It is
+distinct from an exception condition reported on a resource which was
+successfully polled and represents a failure of the polling process itself in
+relation to a resource. This may mean that SSL_poll() does not support the kind
+of resource specified.
+
+Where this event is raised on at least one item in I<items>, SSL_poll() will
+return 0 and the ERR stack will contain information pertaining to the first item
+in I<items> with B<SSL_POLL_EVENT_F> set. See L</RETURN VALUES> for more
+information.
+
+This event type may be raised even if it was not requested in I<events>;
+specifying this event type in I<events> does nothing.
+
+=item B<SSL_POLL_EVENT_EC>
+
+Error at connection level. This event is raised when a connection has failed.
+In particular, it is raised when a connection begins terminating.
+
+This event is never raised on objects which are not connections.
+
+=item B<SSL_POLL_EVENT_DCD>
+
+Error at connection level (drained). This event is raised when a connection has
+finished terminating, and has reached the terminated state. This event will
+generally occur after an interval of time passes after the B<SSL_POLL_EVENT_EC>
+event is raised on a connection.
+
+This event is never raised on objects which are not connections.
+
+=item B<SSL_POLL_EVENT_ER>
+
+Error in read direction. For QUIC, this is raised only in the event that a
+stream has a read part and that read part has been reset by the peer (for
+example, using a B<RESET_STREAM> frame).
+
+=item B<SSL_POLL_EVENT_EW>
+
+Error in write direction. For QUIC, this is raised only in the event that a
+stream has a write part and that write part has been reset by the peer using a
+B<STOP_SENDING> frame.
+
+=item B<SSL_POLL_EVENT_R>
+
+Readable. This event is raised when a QUIC stream SSL object (or a QUIC
+connection SSL object with a default stream attached) has application data
+waiting to be read using L<SSL_read_ex(3)>, or a FIN event as represented by
+B<SSL_ERROR_ZERO_RETURN> waiting to be read.
+
+It is not raised in the event of the receiving part of the QUIC stream being
+reset by the peer; see B<SSL_POLL_EVENT_ER>.
+
+=item B<SSL_POLL_EVENT_W>
+
+Writable. This event is raised when a QUIC stream SSL object (or a QUIC
+connection SSL object with a default stream attached) could accept more
+application data using L<SSL_write_ex(3)>.
+
+This event is never raised by a receive-only stream.
+
+This event is never raised by a stream which has had its send part concluded
+normally (as with L<SSL_stream_conclude(3)>) or locally reset (as with
+L<SSL_stream_reset(3)>).
+
+This event does not guarantee that a subsequent call to L<SSL_write_ex(3)> will
+succeed.
+
+=item B<SSL_POLL_EVENT_ISB>
+
+This event, which is only raised by a QUIC connection SSL object, is raised when
+one or more incoming bidirectional streams are available to be accepted using
+L<SSL_accept_stream(3)>.
+
+=item B<SSL_POLL_EVENT_ISU>
+
+This event, which is only raised by a QUIC connection SSL object, is raised when
+one or more incoming unidirectional streams are available to be accepted using
+L<SSL_accept_stream(3)>.
+
+=item B<SSL_POLL_EVENT_OSB>
+
+This event, which is only raised by a QUIC connection SSL object, is raised when
+QUIC stream creation flow control currently permits at least one additional
+bidirectional stream to be locally created.
+
+=item B<SSL_POLL_EVENT_OSU>
+
+This event, which is only raised by a QUIC connection SSL object, is raised when
+QUIC stream creation flow control currently permits at least one additional
+unidirectional stream to be locally created.
+
+=back
+
+=head1 LIMITATIONS
+
+SSL_poll() as presently implemented has the following limitations:
+
+=over 4
+
+=item
+
+The implementation of SSL_poll() only supports nonblocking operation and
+therefore requires the I<timeout> argument be used to specify a zero timeout.
+Calls to SSL_poll() which specify another value, or which pass I<timeout> 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<BIO_POLL_DESCRIPTOR> structures with type
+B<BIO_POLL_DESCRIPTOR_TYPE_SSL>, referencing QUIC connection SSL objects or QUIC
+stream SSL objects, are supported.
+
+=back
+
+These limitations will be revised in a future release of OpenSSL.
+
+=head1 RETURN VALUES
+
+SSL_poll() returns 1 on success and 0 on failure.
+
+Unless the I<items> pointer itself is invalid, SSL_poll() will always initialise
+the I<revents> fields of all items in the input array upon returning, even if it
+returns failure.
+
+If I<result_count> is non-NULL, it is always written with the number of items in
+the array with nonzero I<revents> fields, even if the SSL_poll() call returns
+failure.
+
+It is possible for I<result_count> to be written as 0 even if the SSL_poll()
+call returns success, namely if no events were output but the polling process
+was successful (e.g. in nonblocking usage) or timed out.
+
+It is possible for I<result_count> to be written as a nonzero value if the
+SSL_poll() call returns failure, for example due to B<SSL_POLL_EVENT_F> events,
+or because some events were detected and output before encountering a failure
+condition while processing a subsequent entry in the I<items> array.
+
+If at least one B<SSL_POLL_EVENT_F> event is output, SSL_poll() is guaranteed
+to return 0 and guaranteed to place at least one ERR on the error stack
+describing the first B<SSL_POLL_EVENT_F> output. Detailed information on any
+additional B<SSL_POLL_EVENT_F> events is not available. SSL_poll() may or may
+not return more than one B<SSL_POLL_EVENT_F> event at once.
+
+"Normal" events representing exceptional I/O conditions which do not
+constitute a failure of the SSL_poll() mechanism itself are not considered
+errors by SSL_poll() and are instead represented using their own event type; see
+L</EVENT TYPES> for details.
+
+The caller can esablish the meaning of the SSL_poll() return and output values
+as follows:
+
+=over 4
+
+=item
+
+If SSL_poll() returns 1 and I<result_count> is zero, the operation timed out
+before any resource was ready.
+
+=item
+
+If SSL_poll() returns 1 and I<result_count> is nonzero, that many events were
+output.
+
+=item
+
+If SSL_poll() returns 0 and I<result_count> is zero, the caller has made a basic
+usage error; check the ERR stack for details.
+
+=item
+
+If SSL_poll() returns 0 and I<result_count> is nonzero, inspect the I<items>
+array for B<SSL_POLL_ITEM> structures with the B<SSL_POLL_EVENT_F> event type
+raised in I<revents>. The entries added to the ERR stack (of which there is
+guaranteed to be at least one) reflect the cause of the failure of the first
+item in I<items> with B<SSL_POLL_EVENT_F> raised. Note that there may be events
+other than I<SSL_POLL_EVENT_F> output for items which come before the first
+item with B<SSL_POLL_EVENT_F> raised, and additional B<SSL_POLL_EVENT_F>
+events may or may not have been output, both of which which will be reflected in
+I<result_count>.
+
+=back
+
+=head1 SEE ALSO
+
+L<BIO_get_rpoll_descriptor(3)>, L<BIO_get_wpoll_descriptor(3)>,
+L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)>
+
+=head1 HISTORY
+
+SSL_poll() was added in OpenSSL 3.3.
+
+=head1 COPYRIGHT
+
+Copyright 2024 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
projects / thirdparty / openssl.git / commitdiff
