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