SSL_POLL(3ossl) OpenSSL SSL_POLL(3ossl)
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
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);
DESCRIPTION
SSL_poll(3) 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(3) specifies an array of 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 SSL_POLL_ITEM are as follows:
desc
The resource being polled for readiness, as represented by a
BIO_POLL_DESCRIPTOR. Currently, this must be a poll descriptor of
type BIO_POLL_DESCRIPTOR_TYPE_SSL, representing a SSL object
pointer, and the SSL object must be a QUIC connection SSL object or
QUIC stream SSL object.
If a SSL_POLL_ITEM has a poll descriptor type of
BIO_POLL_DESCRIPTOR_TYPE_NONE, or the SSL object pointer is NULL,
the SSL_POLL_ITEM array entry is ignored and revents will be set to
0 on return.
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 desc. It is a collection of zero or more SSL_POLL_EVENT flags.
See "EVENT TYPES" for a description of each of the event types.
revents
After SSL_poll(3) returns, this is the set of zero or more events
which are actually applicable to the resource described by desc. As
for events, it is a collection of zero or more SSL_POLL_EVENT
flags.
revents need not be a subset of the events specified in events, as
some event types are defined as always being enabled (non-
maskable). See "EVENT TYPES" for more information.
To use SSL_poll(3), call it with an array of SSL_POLL_ITEM structures.
The array need remain allocated only for the duration of the call.
num_items must be set to the number of entries in the array, and stride
must be set to "sizeof(SSL_POLL_ITEM)".
The present implementation of SSL_poll(3) 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(3) always
returns immediately. As such, timeout must point to a valid struct
timeval and that structure must be set to zero. In future, other
inputs to the timeout argument will result in a blocking mode of
operation, which is not currently supported. For more information, see
"LIMITATIONS".
The following flags are currently defined for the flags argument:
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.
The 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 revents
fields when the call to SSL_poll(3) returns; see "RETURN VALUES" for
details.
EVENT TYPES
The SSL_poll(3) 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(3) for a resource, it will continue to be reported
in future SSL_poll(3) calls until the condition ceases to be in effect.
A caller must mask the given event type bit in future SSL_poll(3) 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 SSL_read_ex(3) after 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 events is a no-op and will be
ignored, and the given event will never be reported in revents.
Failure of the polling mechanism itself is considered distinct from an
exception condition on a resource which was successfully polled. See
SSL_POLL_EVENT_F and "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. SSL_POLL_EVENT_EC and
SSL_POLL_EVENT_ER for 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 revents
regardless of whether they were requested in events.
The following event types are supported:
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(3) does not support the kind of resource specified.
Where this event is raised on at least one item in items,
SSL_poll(3) will return 0 and the ERR stack will contain information
pertaining to the first item in items with SSL_POLL_EVENT_F set.
See "RETURN VALUES" for more information.
This event type may be raised even if it was not requested in
events; specifying this event type in events does nothing.
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.
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 SSL_POLL_EVENT_EC event is raised on a connection.
This event is never raised on objects which are not connections.
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 RESET_STREAM frame).
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 STOP_SENDING frame.
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 SSL_read_ex(3), or a FIN
event as represented by 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 SSL_POLL_EVENT_ER.
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 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 SSL_stream_conclude(3)) or locally
reset (as with SSL_stream_reset(3)).
This event does not guarantee that a subsequent call to
SSL_write_ex(3) will succeed.
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 SSL_accept_stream(3).
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 SSL_accept_stream(3).
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.
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.
LIMITATIONS
SSL_poll(3) as presently implemented has the following limitations:
SSL_poll(3) only supports nonblocking
operation and therefore requires the timeout argument be used to
specify a zero timeout. Calls to SSL_poll(3) which specify another
value, or which pass 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(3).
o Only BIO_POLL_DESCRIPTOR structures with type
BIO_POLL_DESCRIPTOR_TYPE_SSL, referencing QUIC connection SSL
objects or QUIC stream SSL objects, are supported.
These limitations will be revised in a future release of OpenSSL.
RETURN VALUES
SSL_poll(3) returns 1 on success and 0 on failure.
Unless the items pointer itself is invalid, SSL_poll(3) will always
initialise the revents fields of all items in the input array upon
returning, even if it returns failure.
If result_count is non-NULL, it is always written with the number of
items in the array with nonzero revents fields, even if the SSL_poll(3)
call returns failure.
It is possible for result_count to be written as 0 even if the
SSL_poll(3) 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 result_count to be written as a nonzero value if the
SSL_poll(3) call returns failure, for example due to 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 items array.
If at least one SSL_poll(3) is
guaranteed to return 0 and guaranteed to place at least one ERR on the
error stack describing the first SSL_POLL_EVENT_F output. Detailed
information on any additional SSL_POLL_EVENT_F events is not available.
SSL_poll(3) may or may not return more than one SSL_POLL_EVENT_F event
at once.
"Normal" events representing exceptional I/O conditions which do not
constitute a failure of the SSL_poll(3) mechanism itself are not
considered errors by SSL_poll(3) and are instead represented using their
own event type; see "EVENT TYPES" for details.
The caller can establish the meaning of the SSL_poll(3) return and
output values as follows:
SSL_poll(3) returns 1 and result_count is zero, the operation
timed out before any resource was ready.
SSL_poll(3) returns 1 and result_count is nonzero, that many
events were output.
SSL_poll(3) returns 0 and result_count is zero, the caller has
made a basic usage error; check the ERR stack for details.
SSL_poll(3) returns 0 and result_count is nonzero, inspect the
items array for SSL_POLL_ITEM structures with the SSL_POLL_EVENT_F
event type raised in 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 items with SSL_POLL_EVENT_F
raised. Note that there may be events other than SSL_POLL_EVENT_F
output for items which come before the first item with
SSL_POLL_EVENT_F raised, and additional SSL_POLL_EVENT_F events may
or may not have been output, both of which which will be reflected
in result_count.
SEE ALSO
BIO_get_rpoll_descriptor(3), BIO_get_wpoll_descriptor(3),
SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3)
HISTORY
SSL_poll(3) was added in OpenSSL 3.3.
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
<https://www.openssl.org/source/license.html>.
3.4.0 2024-10-29 SSL_POLL(3ossl)
openssl 3.4.0 - Generated Sun Nov 17 15:50:12 CST 2024