Android_verify/lib/openssl/share/man/man3/SSL_poll.3ossl

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SSL_POLL 3ossl"
.TH SSL_POLL 3ossl 2025-01-17 3.4.0 OpenSSL
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH 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
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBSSL_poll()\fR 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.
.PP
A call to \fBSSL_poll()\fR specifies an array of \fBSSL_POLL_ITEM\fR 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.
.PP
The fields of \fBSSL_POLL_ITEM\fR are as follows:
.IP \fIdesc\fR 4
.IX Item "desc"
The resource being polled for readiness, as represented by a
\&\fBBIO_POLL_DESCRIPTOR\fR. Currently, this must be a poll descriptor of type
\&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, representing a SSL object pointer, and the SSL
object must be a QUIC connection SSL object or QUIC stream SSL object.
.Sp
If a \fBSSL_POLL_ITEM\fR has a poll descriptor type of
\&\fBBIO_POLL_DESCRIPTOR_TYPE_NONE\fR, or the SSL object pointer is NULL, the
\&\fBSSL_POLL_ITEM\fR array entry is ignored and \fIrevents\fR will be set to 0 on
return.
.IP \fIevents\fR 4
.IX Item "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 \fIdesc\fR. It is a
collection of zero or more \fBSSL_POLL_EVENT\fR flags. See "EVENT TYPES" for a
description of each of the event types.
.IP \fIrevents\fR 4
.IX Item "revents"
After \fBSSL_poll()\fR returns, this is the set of zero or more events which are
actually applicable to the resource described by \fIdesc\fR. As for \fIevents\fR,
it is a collection of zero or more \fBSSL_POLL_EVENT\fR flags.
.Sp
\&\fIrevents\fR need not be a subset of the events specified in \fIevents\fR, as some
event types are defined as always being enabled (non-maskable). See "EVENT
TYPES" for more information.
.PP
To use \fBSSL_poll()\fR, call it with an array of \fBSSL_POLL_ITEM\fR structures. The
array need remain allocated only for the duration of the call. \fInum_items\fR must
be set to the number of entries in the array, and \fIstride\fR must be set to
\&\f(CWsizeof(SSL_POLL_ITEM)\fR.
.PP
The present implementation of \fBSSL_poll()\fR is a subset of the functionality which
will eventually be available. Only a nonblocking mode of operation is available
at this time, where \fBSSL_poll()\fR always returns immediately. As such, \fItimeout\fR
must point to a valid \fBstruct timeval\fR and that structure must be set to zero.
In future, other inputs to the \fItimeout\fR argument will result in a blocking
mode of operation, which is not currently supported. For more information, see
"LIMITATIONS".
.PP
The following flags are currently defined for the \fIflags\fR argument:
.IP \fBSSL_POLL_FLAG_NO_HANDLE_EVENTS\fR 4
.IX Item "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.
.PP
The \fIresult_count\fR argument is optional. If it is non-NULL, it is used to
output the number of entries in the array which have nonzero \fIrevents\fR fields
when the call to \fBSSL_poll()\fR returns; see "RETURN VALUES" for details.
.SH "EVENT TYPES"
.IX Header "EVENT TYPES"
The \fBSSL_poll()\fR interface reports zero or more event types on a given resource,
represented by a bit mask.
.PP
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
\&\fBSSL_poll()\fR for a resource, it will continue to be reported in future \fBSSL_poll()\fR
calls until the condition ceases to be in effect. A caller must mask the given
event type bit in future \fBSSL_poll()\fR 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 \fBSSL_read_ex\fR\|(3) after
\&\fBSSL_POLL_EVENT_R\fR is reported) to be deasserted.
.PP
Some event types do not make sense on a given kind of resource. In this case,
specifying that event type in \fIevents\fR is a no-op and will be ignored, and the
given event will never be reported in \fIrevents\fR.
.PP
Failure of the polling mechanism itself is considered distinct from an exception
condition on a resource which was successfully polled. See \fBSSL_POLL_EVENT_F\fR
and "RETURN VALUES" for details.
.PP
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. \fBSSL_POLL_EVENT_EC\fR and \fBSSL_POLL_EVENT_ER\fR
for \fBSSL_POLL_EVENT_R\fR), as not doing so is unlikely to be a sound design.
.PP
Some event types are non-maskable and may be reported in \fIrevents\fR regardless
of whether they were requested in \fIevents\fR.
.PP
The following event types are supported:
.IP \fBSSL_POLL_EVENT_F\fR 4
.IX Item "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 \fBSSL_poll()\fR does not support the kind
of resource specified.
.Sp
Where this event is raised on at least one item in \fIitems\fR, \fBSSL_poll()\fR will
return 0 and the ERR stack will contain information pertaining to the first item
in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR set. See "RETURN VALUES" for more
information.
.Sp
This event type may be raised even if it was not requested in \fIevents\fR;
specifying this event type in \fIevents\fR does nothing.
.IP \fBSSL_POLL_EVENT_EC\fR 4
.IX Item "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.
.Sp
This event is never raised on objects which are not connections.
.IP \fBSSL_POLL_EVENT_DCD\fR 4
.IX Item "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 \fBSSL_POLL_EVENT_EC\fR
event is raised on a connection.
.Sp
This event is never raised on objects which are not connections.
.IP \fBSSL_POLL_EVENT_ER\fR 4
.IX Item "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 \fBRESET_STREAM\fR frame).
.IP \fBSSL_POLL_EVENT_EW\fR 4
.IX Item "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
\&\fBSTOP_SENDING\fR frame.
.IP \fBSSL_POLL_EVENT_R\fR 4
.IX Item "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 \fBSSL_read_ex\fR\|(3), or a FIN event as represented by
\&\fBSSL_ERROR_ZERO_RETURN\fR waiting to be read.
.Sp
It is not raised in the event of the receiving part of the QUIC stream being
reset by the peer; see \fBSSL_POLL_EVENT_ER\fR.
.IP \fBSSL_POLL_EVENT_W\fR 4
.IX Item "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 \fBSSL_write_ex\fR\|(3).
.Sp
This event is never raised by a receive-only stream.
.Sp
This event is never raised by a stream which has had its send part concluded
normally (as with \fBSSL_stream_conclude\fR\|(3)) or locally reset (as with
\&\fBSSL_stream_reset\fR\|(3)).
.Sp
This event does not guarantee that a subsequent call to \fBSSL_write_ex\fR\|(3) will
succeed.
.IP \fBSSL_POLL_EVENT_ISB\fR 4
.IX Item "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
\&\fBSSL_accept_stream\fR\|(3).
.IP \fBSSL_POLL_EVENT_ISU\fR 4
.IX Item "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
\&\fBSSL_accept_stream\fR\|(3).
.IP \fBSSL_POLL_EVENT_OSB\fR 4
.IX Item "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.
.IP \fBSSL_POLL_EVENT_OSU\fR 4
.IX Item "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.
.SH LIMITATIONS
.IX Header "LIMITATIONS"
\&\fBSSL_poll()\fR as presently implemented has the following limitations:
.IP \(bu 4
The implementation of \fBSSL_poll()\fR only supports nonblocking operation and
therefore requires the \fItimeout\fR argument be used to specify a zero timeout.
Calls to \fBSSL_poll()\fR which specify another value, or which pass \fItimeout\fR 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.
.Sp
Future releases will remove this limitation and support blocking \fBSSL_poll()\fR.
.IP \(bu 4
Only \fBBIO_POLL_DESCRIPTOR\fR structures with type
\&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, referencing QUIC connection SSL objects or QUIC
stream SSL objects, are supported.
.PP
These limitations will be revised in a future release of OpenSSL.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBSSL_poll()\fR returns 1 on success and 0 on failure.
.PP
Unless the \fIitems\fR pointer itself is invalid, \fBSSL_poll()\fR will always initialise
the \fIrevents\fR fields of all items in the input array upon returning, even if it
returns failure.
.PP
If \fIresult_count\fR is non-NULL, it is always written with the number of items in
the array with nonzero \fIrevents\fR fields, even if the \fBSSL_poll()\fR call returns
failure.
.PP
It is possible for \fIresult_count\fR to be written as 0 even if the \fBSSL_poll()\fR
call returns success, namely if no events were output but the polling process
was successful (e.g. in nonblocking usage) or timed out.
.PP
It is possible for \fIresult_count\fR to be written as a nonzero value if the
\&\fBSSL_poll()\fR call returns failure, for example due to \fBSSL_POLL_EVENT_F\fR events,
or because some events were detected and output before encountering a failure
condition while processing a subsequent entry in the \fIitems\fR array.
.PP
If at least one \fBSSL_POLL_EVENT_F\fR event is output, \fBSSL_poll()\fR is guaranteed
to return 0 and guaranteed to place at least one ERR on the error stack
describing the first \fBSSL_POLL_EVENT_F\fR output. Detailed information on any
additional \fBSSL_POLL_EVENT_F\fR events is not available. \fBSSL_poll()\fR may or may
not return more than one \fBSSL_POLL_EVENT_F\fR event at once.
.PP
"Normal" events representing exceptional I/O conditions which do not
constitute a failure of the \fBSSL_poll()\fR mechanism itself are not considered
errors by \fBSSL_poll()\fR and are instead represented using their own event type; see
"EVENT TYPES" for details.
.PP
The caller can establish the meaning of the \fBSSL_poll()\fR return and output values
as follows:
.IP \(bu 4
If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is zero, the operation timed out
before any resource was ready.
.IP \(bu 4
If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is nonzero, that many events were
output.
.IP \(bu 4
If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is zero, the caller has made a basic
usage error; check the ERR stack for details.
.IP \(bu 4
If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is nonzero, inspect the \fIitems\fR
array for \fBSSL_POLL_ITEM\fR structures with the \fBSSL_POLL_EVENT_F\fR event type
raised in \fIrevents\fR. 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 \fIitems\fR with \fBSSL_POLL_EVENT_F\fR raised. Note that there may be events
other than \fISSL_POLL_EVENT_F\fR output for items which come before the first
item with \fBSSL_POLL_EVENT_F\fR raised, and additional \fBSSL_POLL_EVENT_F\fR
events may or may not have been output, both of which which will be reflected in
\&\fIresult_count\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3),
\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3)
.SH HISTORY
.IX Header "HISTORY"
\&\fBSSL_poll()\fR was added in OpenSSL 3.3.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
.PP
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>.