| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "SSL_POLL 3SSL" |
| 58 |
.TH SSL_POLL 3SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
SSL_poll, |
| 65 |
SSL_POLL_EVENT_NONE, |
| 66 |
SSL_POLL_EVENT_F, |
| 67 |
SSL_POLL_EVENT_EL, |
| 68 |
SSL_POLL_EVENT_EC, |
| 69 |
SSL_POLL_EVENT_ECD, |
| 70 |
SSL_POLL_EVENT_ER, |
| 71 |
SSL_POLL_EVENT_EW, |
| 72 |
SSL_POLL_EVENT_R, |
| 73 |
SSL_POLL_EVENT_W, |
| 74 |
SSL_POLL_EVENT_IC, |
| 75 |
SSL_POLL_EVENT_ISB, |
| 76 |
SSL_POLL_EVENT_ISU, |
| 77 |
SSL_POLL_EVENT_OSB, |
| 78 |
SSL_POLL_EVENT_OSU, |
| 79 |
SSL_POLL_EVENT_RW, |
| 80 |
SSL_POLL_EVENT_RE, |
| 81 |
SSL_POLL_EVENT_WE, |
| 82 |
SSL_POLL_EVENT_RWE, |
| 83 |
SSL_POLL_EVENT_E, |
| 84 |
SSL_POLL_EVENT_IS, |
| 85 |
SSL_POLL_EVENT_ISE, |
| 86 |
SSL_POLL_EVENT_I, |
| 87 |
SSL_POLL_EVENT_OS, |
| 88 |
SSL_POLL_EVENT_OSE, |
| 89 |
SSL_POLL_FLAG_NO_HANDLE_EVENTS |
| 90 |
\&\- determine or await readiness conditions for one or more pollable objects |
| 91 |
.SH SYNOPSIS |
| 92 |
.IX Header "SYNOPSIS" |
| 93 |
.Vb 1 |
| 94 |
\& #include <openssl/ssl.h> |
| 95 |
\& |
| 96 |
\& #define SSL_POLL_EVENT_NONE 0 |
| 97 |
\& |
| 98 |
\& #define SSL_POLL_EVENT_F /* F (Failure) */ |
| 99 |
\& #define SSL_POLL_EVENT_EL /* EL (Exception on Listener) */ |
| 100 |
\& #define SSL_POLL_EVENT_EC /* EC (Exception on Conn) */ |
| 101 |
\& #define SSL_POLL_EVENT_ECD /* ECD (Exception on Conn Drained) */ |
| 102 |
\& #define SSL_POLL_EVENT_ER /* ER (Exception on Read) */ |
| 103 |
\& #define SSL_POLL_EVENT_EW /* EW (Exception on Write) */ |
| 104 |
\& #define SSL_POLL_EVENT_R /* R (Readable) */ |
| 105 |
\& #define SSL_POLL_EVENT_W /* W (Writable) */ |
| 106 |
\& #define SSL_POLL_EVENT_IC /* IC (Incoming Connection) */ |
| 107 |
\& #define SSL_POLL_EVENT_ISB /* ISB (Incoming Stream: Bidi) */ |
| 108 |
\& #define SSL_POLL_EVENT_ISU /* ISU (Incoming Stream: Uni) */ |
| 109 |
\& #define SSL_POLL_EVENT_OSB /* OSB (Outgoing Stream: Bidi) */ |
| 110 |
\& #define SSL_POLL_EVENT_OSU /* OSU (Outgoing Stream: Uni) */ |
| 111 |
\& |
| 112 |
\& #define SSL_POLL_EVENT_RW /* R | W */ |
| 113 |
\& #define SSL_POLL_EVENT_RE /* R | ER */ |
| 114 |
\& #define SSL_POLL_EVENT_WE /* W | EW */ |
| 115 |
\& #define SSL_POLL_EVENT_RWE /* RE | WE */ |
| 116 |
\& #define SSL_POLL_EVENT_E /* EL | EC | ER | EW */ |
| 117 |
\& #define SSL_POLL_EVENT_IS /* ISB | ISU */ |
| 118 |
\& #define SSL_POLL_EVENT_ISE /* IS | EC */ |
| 119 |
\& #define SSL_POLL_EVENT_I /* IS */ |
| 120 |
\& #define SSL_POLL_EVENT_OS /* OSB | OSU */ |
| 121 |
\& #define SSL_POLL_EVENT_OSE /* OS | EC */ |
| 122 |
\& |
| 123 |
\& typedef struct ssl_poll_item_st { |
| 124 |
\& BIO_POLL_DESCRIPTOR desc; |
| 125 |
\& uint64_t events, revents; |
| 126 |
\& } SSL_POLL_ITEM; |
| 127 |
\& |
| 128 |
\& #define SSL_POLL_FLAG_NO_HANDLE_EVENTS |
| 129 |
\& |
| 130 |
\& int SSL_poll(SSL_POLL_ITEM *items, |
| 131 |
\& size_t num_items, |
| 132 |
\& size_t stride, |
| 133 |
\& const struct timeval *timeout, |
| 134 |
\& uint64_t flags, |
| 135 |
\& size_t *result_count); |
| 136 |
.Ve |
| 137 |
.SH DESCRIPTION |
| 138 |
.IX Header "DESCRIPTION" |
| 139 |
\&\fBSSL_poll()\fR allows the readiness conditions of the resources represented by one |
| 140 |
or more BIO_POLL_DESCRIPTOR structures to be determined. In particular, it can |
| 141 |
be used to query for readiness conditions on QUIC connection SSL objects and |
| 142 |
QUIC stream SSL objects in a single call. It can also be used to block until at |
| 143 |
least one of the given resources is ready. |
| 144 |
.PP |
| 145 |
A call to \fBSSL_poll()\fR specifies an array of \fBSSL_POLL_ITEM\fR structures, each of |
| 146 |
which designates a resource which is being polled for readiness, and a set of |
| 147 |
event flags which indicate the specific readiness events which the caller is |
| 148 |
interested in in relation to the specified resource. |
| 149 |
.PP |
| 150 |
The fields of \fBSSL_POLL_ITEM\fR are as follows: |
| 151 |
.IP \fIdesc\fR 4 |
| 152 |
.IX Item "desc" |
| 153 |
The resource being polled for readiness, as represented by a |
| 154 |
\&\fBBIO_POLL_DESCRIPTOR\fR. Currently, this must be a poll descriptor of type |
| 155 |
\&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, representing an SSL object pointer, and the SSL |
| 156 |
object must be a QUIC connection SSL object or QUIC stream SSL object. |
| 157 |
.Sp |
| 158 |
If a \fBSSL_POLL_ITEM\fR has a poll descriptor type of |
| 159 |
\&\fBBIO_POLL_DESCRIPTOR_TYPE_NONE\fR, or the SSL object pointer is NULL, the |
| 160 |
\&\fBSSL_POLL_ITEM\fR array entry is ignored and \fIrevents\fR will be set to 0 on |
| 161 |
return. |
| 162 |
.IP \fIevents\fR 4 |
| 163 |
.IX Item "events" |
| 164 |
This is the set of zero or more events which the caller is interested in |
| 165 |
learning about in relation to the resource described by \fIdesc\fR. It is a |
| 166 |
collection of zero or more \fBSSL_POLL_EVENT\fR flags. See "EVENT TYPES" for a |
| 167 |
description of each of the event types. |
| 168 |
.IP \fIrevents\fR 4 |
| 169 |
.IX Item "revents" |
| 170 |
After \fBSSL_poll()\fR returns, this is the set of zero or more events which are |
| 171 |
actually applicable to the resource described by \fIdesc\fR. As for \fIevents\fR, |
| 172 |
it is a collection of zero or more \fBSSL_POLL_EVENT\fR flags. |
| 173 |
.Sp |
| 174 |
\&\fIrevents\fR need not be a subset of the events specified in \fIevents\fR, as some |
| 175 |
event types are defined as always being enabled (non-maskable). See "EVENT |
| 176 |
TYPES" for more information. |
| 177 |
.PP |
| 178 |
To use \fBSSL_poll()\fR, call it with an array of \fBSSL_POLL_ITEM\fR structures. The |
| 179 |
array need remain allocated only for the duration of the call. \fInum_items\fR must |
| 180 |
be set to the number of entries in the array, and \fIstride\fR must be set to |
| 181 |
\&\f(CWsizeof(SSL_POLL_ITEM)\fR. |
| 182 |
.PP |
| 183 |
The \fItimeout\fR argument specifies the timeout to use, and, implicitly, whether |
| 184 |
to use \fBSSL_poll()\fR in blocking or nonblocking mode: |
| 185 |
.IP \(bu 4 |
| 186 |
If \fItimeout\fR is NULL, the function blocks indefinitely until at least one |
| 187 |
resource is ready. |
| 188 |
.IP \(bu 4 |
| 189 |
If \fItimeout\fR is non-NULL, and it points to a \fBstruct timeval\fR which is set to |
| 190 |
zero, the function operates in nonblocking mode and returns immediately with |
| 191 |
readiness information. |
| 192 |
.IP \(bu 4 |
| 193 |
If \fItimeout\fR is non-NULL, and it points to a \fBstruct timeval\fR which is set to |
| 194 |
a value other than zero, the function blocks for the specified interval or until |
| 195 |
at least one of the specified resources is ready, whichever comes first. |
| 196 |
.PP |
| 197 |
The present implementation of \fBSSL_poll()\fR is a subset of the functionality which |
| 198 |
will eventually be available. For more information, see "LIMITATIONS". |
| 199 |
.PP |
| 200 |
The following flags are currently defined for the \fIflags\fR argument: |
| 201 |
.IP \fBSSL_POLL_FLAG_NO_HANDLE_EVENTS\fR 4 |
| 202 |
.IX Item "SSL_POLL_FLAG_NO_HANDLE_EVENTS" |
| 203 |
This flag indicates that internal state machine processing should not be |
| 204 |
performed in an attempt to generate new readiness events. Only existing |
| 205 |
readiness events will be reported. |
| 206 |
.Sp |
| 207 |
If this flag is used in nonblocking mode (with a timeout of zero), no internal |
| 208 |
state machine processing is performed. |
| 209 |
.Sp |
| 210 |
If this flag is used in blocking mode (for example, with \fItimeout\fR set to |
| 211 |
NULL), event processing does not occur unless the function blocks. |
| 212 |
.PP |
| 213 |
The \fIresult_count\fR argument is optional. If it is non-NULL, it is used to |
| 214 |
output the number of entries in the array which have nonzero \fIrevents\fR fields |
| 215 |
when the call to \fBSSL_poll()\fR returns; see "RETURN VALUES" for details. |
| 216 |
.SH "EVENT TYPES" |
| 217 |
.IX Header "EVENT TYPES" |
| 218 |
The \fBSSL_poll()\fR interface reports zero or more event types on a given resource, |
| 219 |
represented by a bit mask. |
| 220 |
.PP |
| 221 |
All of the event types are level triggered and represent a readiness or |
| 222 |
permanent exception condition; as such, after an event has been reported by |
| 223 |
\&\fBSSL_poll()\fR for a resource, it will continue to be reported in future \fBSSL_poll()\fR |
| 224 |
calls until the condition ceases to be in effect. A caller must mask the given |
| 225 |
event type bit in future \fBSSL_poll()\fR calls if it does not wish to receive |
| 226 |
repeated notifications and has not caused the underlying readiness condition |
| 227 |
(for example, consuming all available data using \fBSSL_read_ex\fR\|(3) after |
| 228 |
\&\fBSSL_POLL_EVENT_R\fR is reported) to be deasserted. |
| 229 |
.PP |
| 230 |
Some event types do not make sense on a given kind of resource. In this case, |
| 231 |
specifying that event type in \fIevents\fR is a no-op and will be ignored, and the |
| 232 |
given event will never be reported in \fIrevents\fR. |
| 233 |
.PP |
| 234 |
Failure of the polling mechanism itself is considered distinct from an exception |
| 235 |
condition on a resource which was successfully polled. See \fBSSL_POLL_EVENT_F\fR |
| 236 |
and "RETURN VALUES" for details. |
| 237 |
.PP |
| 238 |
In general, an application should always listen for the event types |
| 239 |
corresponding to exception conditions if it is listening to the corresponding |
| 240 |
non-exception event types (e.g. \fBSSL_POLL_EVENT_EC\fR and \fBSSL_POLL_EVENT_ER\fR |
| 241 |
for \fBSSL_POLL_EVENT_R\fR), as not doing so is unlikely to be a sound design. |
| 242 |
.PP |
| 243 |
Some event types are non-maskable and may be reported in \fIrevents\fR regardless |
| 244 |
of whether they were requested in \fIevents\fR. |
| 245 |
.PP |
| 246 |
The following event types are supported: |
| 247 |
.IP \fBSSL_POLL_EVENT_F\fR 4 |
| 248 |
.IX Item "SSL_POLL_EVENT_F" |
| 249 |
Polling failure. This event is raised when a resource could not be polled. It is |
| 250 |
distinct from an exception condition reported on a resource which was |
| 251 |
successfully polled and represents a failure of the polling process itself in |
| 252 |
relation to a resource. This may mean that \fBSSL_poll()\fR does not support the kind |
| 253 |
of resource specified. |
| 254 |
.Sp |
| 255 |
Where this event is raised on at least one item in \fIitems\fR, \fBSSL_poll()\fR will |
| 256 |
return 0 and the ERR stack will contain information pertaining to the first item |
| 257 |
in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR set. See "RETURN VALUES" for more |
| 258 |
information. |
| 259 |
.Sp |
| 260 |
This event type may be raised even if it was not requested in \fIevents\fR; |
| 261 |
specifying this event type in \fIevents\fR does nothing. |
| 262 |
.IP \fBSSL_POLL_EVENT_EL\fR 4 |
| 263 |
.IX Item "SSL_POLL_EVENT_EL" |
| 264 |
Error at listener level. This event is raised when a listener has failed, for |
| 265 |
example if a network BIO has encountered a permanent error. |
| 266 |
.Sp |
| 267 |
This event is never raised on objects which are not listeners, but its |
| 268 |
occurrence will cause \fBSSL_POLL_EVENT_EC\fR to be raised on all dependent |
| 269 |
connections. |
| 270 |
.IP \fBSSL_POLL_EVENT_EC\fR 4 |
| 271 |
.IX Item "SSL_POLL_EVENT_EC" |
| 272 |
Error at connection level. This event is raised when a connection has failed. |
| 273 |
In particular, it is raised when a connection begins terminating. |
| 274 |
.Sp |
| 275 |
This event is never raised on objects which are not connections. |
| 276 |
.IP \fBSSL_POLL_EVENT_ECD\fR 4 |
| 277 |
.IX Item "SSL_POLL_EVENT_ECD" |
| 278 |
Error at connection level (drained). This event is raised when a connection has |
| 279 |
finished terminating, and has reached the terminated state. This event will |
| 280 |
generally occur after an interval of time passes after the \fBSSL_POLL_EVENT_EC\fR |
| 281 |
event is raised on a connection. |
| 282 |
.Sp |
| 283 |
This event is never raised on objects which are not connections. |
| 284 |
.IP \fBSSL_POLL_EVENT_ER\fR 4 |
| 285 |
.IX Item "SSL_POLL_EVENT_ER" |
| 286 |
Error in read direction. For QUIC, this is raised only in the event that a |
| 287 |
stream has a read part and that read part has been reset by the peer (for |
| 288 |
example, using a \fBRESET_STREAM\fR frame). |
| 289 |
.IP \fBSSL_POLL_EVENT_EW\fR 4 |
| 290 |
.IX Item "SSL_POLL_EVENT_EW" |
| 291 |
Error in write direction. For QUIC, this is raised only in the event that a |
| 292 |
stream has a write part and that write part has been reset by the peer using a |
| 293 |
\&\fBSTOP_SENDING\fR frame. |
| 294 |
.IP \fBSSL_POLL_EVENT_R\fR 4 |
| 295 |
.IX Item "SSL_POLL_EVENT_R" |
| 296 |
Readable. This event is raised when a QUIC stream SSL object (or a QUIC |
| 297 |
connection SSL object with a default stream attached) has application data |
| 298 |
waiting to be read using \fBSSL_read_ex\fR\|(3), or a FIN event as represented by |
| 299 |
\&\fBSSL_ERROR_ZERO_RETURN\fR waiting to be read. |
| 300 |
.Sp |
| 301 |
It is not raised in the event of the receiving part of the QUIC stream being |
| 302 |
reset by the peer; see \fBSSL_POLL_EVENT_ER\fR. |
| 303 |
.IP \fBSSL_POLL_EVENT_W\fR 4 |
| 304 |
.IX Item "SSL_POLL_EVENT_W" |
| 305 |
Writable. This event is raised when a QUIC stream SSL object (or a QUIC |
| 306 |
connection SSL object with a default stream attached) could accept more |
| 307 |
application data using \fBSSL_write_ex\fR\|(3). |
| 308 |
.Sp |
| 309 |
This event is never raised by a receive-only stream. |
| 310 |
.Sp |
| 311 |
This event is never raised by a stream which has had its send part concluded |
| 312 |
normally (as with \fBSSL_stream_conclude\fR\|(3)) or locally reset (as with |
| 313 |
\&\fBSSL_stream_reset\fR\|(3)). |
| 314 |
.Sp |
| 315 |
This event does not guarantee that a subsequent call to \fBSSL_write_ex\fR\|(3) will |
| 316 |
succeed. |
| 317 |
.IP \fBSSL_POLL_EVENT_IC\fR 4 |
| 318 |
.IX Item "SSL_POLL_EVENT_IC" |
| 319 |
This event, which is only raised by a QUIC listener SSL object, is raised when |
| 320 |
one or more incoming QUIC connections are available to be accepted using |
| 321 |
\&\fBSSL_accept_connection\fR\|(3). |
| 322 |
.IP \fBSSL_POLL_EVENT_ISB\fR 4 |
| 323 |
.IX Item "SSL_POLL_EVENT_ISB" |
| 324 |
This event, which is only raised by a QUIC connection SSL object, is raised when |
| 325 |
one or more incoming bidirectional streams are available to be accepted using |
| 326 |
\&\fBSSL_accept_stream\fR\|(3). |
| 327 |
.IP \fBSSL_POLL_EVENT_ISU\fR 4 |
| 328 |
.IX Item "SSL_POLL_EVENT_ISU" |
| 329 |
This event, which is only raised by a QUIC connection SSL object, is raised when |
| 330 |
one or more incoming unidirectional streams are available to be accepted using |
| 331 |
\&\fBSSL_accept_stream\fR\|(3). |
| 332 |
.IP \fBSSL_POLL_EVENT_OSB\fR 4 |
| 333 |
.IX Item "SSL_POLL_EVENT_OSB" |
| 334 |
This event, which is only raised by a QUIC connection SSL object, is raised when |
| 335 |
QUIC stream creation flow control currently permits at least one additional |
| 336 |
bidirectional stream to be locally created. |
| 337 |
.IP \fBSSL_POLL_EVENT_OSU\fR 4 |
| 338 |
.IX Item "SSL_POLL_EVENT_OSU" |
| 339 |
This event, which is only raised by a QUIC connection SSL object, is raised when |
| 340 |
QUIC stream creation flow control currently permits at least one additional |
| 341 |
unidirectional stream to be locally created. |
| 342 |
.SH LIMITATIONS |
| 343 |
.IX Header "LIMITATIONS" |
| 344 |
\&\fBSSL_poll()\fR as presently implemented has the following limitation: |
| 345 |
.IP \(bu 4 |
| 346 |
Only \fBBIO_POLL_DESCRIPTOR\fR structures with type |
| 347 |
\&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, referencing QUIC listener, connection or |
| 348 |
stream SSL objects, are supported. |
| 349 |
.PP |
| 350 |
This limitation may be revised in a future release of OpenSSL. |
| 351 |
.SH "RETURN VALUES" |
| 352 |
.IX Header "RETURN VALUES" |
| 353 |
\&\fBSSL_poll()\fR returns 1 on success and 0 on failure. |
| 354 |
.PP |
| 355 |
Unless the \fIitems\fR pointer itself is invalid, \fBSSL_poll()\fR will always initialise |
| 356 |
the \fIrevents\fR fields of all items in the input array upon returning, even if it |
| 357 |
returns failure. |
| 358 |
.PP |
| 359 |
If \fIresult_count\fR is non-NULL, it is always written with the number of items in |
| 360 |
the array with nonzero \fIrevents\fR fields, even if the \fBSSL_poll()\fR call returns |
| 361 |
failure. |
| 362 |
.PP |
| 363 |
It is possible for \fIresult_count\fR to be written as 0 even if the \fBSSL_poll()\fR |
| 364 |
call returns success, namely if no events were output but the polling process |
| 365 |
was successful (e.g. in nonblocking usage) or timed out. |
| 366 |
.PP |
| 367 |
It is possible for \fIresult_count\fR to be written as a nonzero value if the |
| 368 |
\&\fBSSL_poll()\fR call returns failure, for example due to \fBSSL_POLL_EVENT_F\fR events, |
| 369 |
or because some events were detected and output before encountering a failure |
| 370 |
condition while processing a subsequent entry in the \fIitems\fR array. |
| 371 |
.PP |
| 372 |
If at least one \fBSSL_POLL_EVENT_F\fR event is output, \fBSSL_poll()\fR is guaranteed |
| 373 |
to return 0 and guaranteed to place at least one ERR on the error stack |
| 374 |
describing the first \fBSSL_POLL_EVENT_F\fR output. Detailed information on any |
| 375 |
additional \fBSSL_POLL_EVENT_F\fR events is not available. \fBSSL_poll()\fR may or may |
| 376 |
not return more than one \fBSSL_POLL_EVENT_F\fR event at once. |
| 377 |
.PP |
| 378 |
"Normal" events representing exceptional I/O conditions which do not |
| 379 |
constitute a failure of the \fBSSL_poll()\fR mechanism itself are not considered |
| 380 |
errors by \fBSSL_poll()\fR and are instead represented using their own event type; see |
| 381 |
"EVENT TYPES" for details. |
| 382 |
.PP |
| 383 |
The caller can establish the meaning of the \fBSSL_poll()\fR return and output values |
| 384 |
as follows: |
| 385 |
.IP \(bu 4 |
| 386 |
If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is zero, the operation timed out |
| 387 |
before any resource was ready. |
| 388 |
.IP \(bu 4 |
| 389 |
If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is nonzero, that many events were |
| 390 |
output. |
| 391 |
.IP \(bu 4 |
| 392 |
If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is zero, the caller has made a basic |
| 393 |
usage error; check the ERR stack for details. |
| 394 |
.IP \(bu 4 |
| 395 |
If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is nonzero, inspect the \fIitems\fR |
| 396 |
array for \fBSSL_POLL_ITEM\fR structures with the \fBSSL_POLL_EVENT_F\fR event type |
| 397 |
raised in \fIrevents\fR. The entries added to the ERR stack (of which there is |
| 398 |
guaranteed to be at least one) reflect the cause of the failure of the first |
| 399 |
item in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR raised. Note that there may be events |
| 400 |
other than \fISSL_POLL_EVENT_F\fR output for items which come before the first |
| 401 |
item with \fBSSL_POLL_EVENT_F\fR raised, and additional \fBSSL_POLL_EVENT_F\fR |
| 402 |
events may or may not have been output, both of which which will be reflected in |
| 403 |
\&\fIresult_count\fR. |
| 404 |
.SH "SEE ALSO" |
| 405 |
.IX Header "SEE ALSO" |
| 406 |
\&\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3), |
| 407 |
\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3) |
| 408 |
.SH HISTORY |
| 409 |
.IX Header "HISTORY" |
| 410 |
\&\fBSSL_poll()\fR was added in OpenSSL 3.3. |
| 411 |
.PP |
| 412 |
Before 3.5, \fBSSL_poll()\fR did not support blocking operation and |
| 413 |
would fail if called with a NULL \fItimeout\fR parameter or a \fItimeout\fR parameter |
| 414 |
pointing to a \fBstruct timeval\fR which was not zero. |
| 415 |
.PP |
| 416 |
Before 3.5, the \fBSSL_POLL_EVENT_EL\fR and \fBSSL_POLL_EVENT_IC\fR |
| 417 |
event types were not present. |
| 418 |
.SH COPYRIGHT |
| 419 |
.IX Header "COPYRIGHT" |
| 420 |
Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. |
| 421 |
.PP |
| 422 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 423 |
this file except in compliance with the License. You can obtain a copy |
| 424 |
in the file LICENSE in the source distribution or at |
| 425 |
<https://www.openssl.org/source/license.html>. |