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 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 RETURN VALUES 341 342SSL_poll() returns 1 on success and 0 on failure. 343 344Unless the I<items> pointer itself is invalid, SSL_poll() will always initialise 345the I<revents> fields of all items in the input array upon returning, even if it 346returns failure. 347 348If I<result_count> is non-NULL, it is always written with the number of items in 349the array with nonzero I<revents> fields, even if the SSL_poll() call returns 350failure. 351 352It is possible for I<result_count> to be written as 0 even if the SSL_poll() 353call returns success, namely if no events were output but the polling process 354was successful (e.g. in nonblocking usage) or timed out. 355 356It is possible for I<result_count> to be written as a nonzero value if the 357SSL_poll() call returns failure, for example due to B<SSL_POLL_EVENT_F> events, 358or because some events were detected and output before encountering a failure 359condition while processing a subsequent entry in the I<items> array. 360 361If at least one B<SSL_POLL_EVENT_F> event is output, SSL_poll() is guaranteed 362to return 0 and guaranteed to place at least one ERR on the error stack 363describing the first B<SSL_POLL_EVENT_F> output. Detailed information on any 364additional B<SSL_POLL_EVENT_F> events is not available. SSL_poll() may or may 365not return more than one B<SSL_POLL_EVENT_F> event at once. 366 367"Normal" events representing exceptional I/O conditions which do not 368constitute a failure of the SSL_poll() mechanism itself are not considered 369errors by SSL_poll() and are instead represented using their own event type; see 370L</EVENT TYPES> for details. 371 372The caller can establish the meaning of the SSL_poll() return and output values 373as follows: 374 375=over 4 376 377=item 378 379If SSL_poll() returns 1 and I<result_count> is zero, the operation timed out 380before any resource was ready. 381 382=item 383 384If SSL_poll() returns 1 and I<result_count> is nonzero, that many events were 385output. 386 387=item 388 389If SSL_poll() returns 0 and I<result_count> is zero, the caller has made a basic 390usage error; check the ERR stack for details. 391 392=item 393 394If SSL_poll() returns 0 and I<result_count> is nonzero, inspect the I<items> 395array for B<SSL_POLL_ITEM> structures with the B<SSL_POLL_EVENT_F> event type 396raised in I<revents>. The entries added to the ERR stack (of which there is 397guaranteed to be at least one) reflect the cause of the failure of the first 398item in I<items> with B<SSL_POLL_EVENT_F> raised. Note that there may be events 399other than I<SSL_POLL_EVENT_F> output for items which come before the first 400item with B<SSL_POLL_EVENT_F> raised, and additional B<SSL_POLL_EVENT_F> 401events may or may not have been output, both of which which will be reflected in 402I<result_count>. 403 404=back 405 406=head1 SEE ALSO 407 408L<BIO_get_rpoll_descriptor(3)>, L<BIO_get_wpoll_descriptor(3)>, 409L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)> 410 411=head1 HISTORY 412 413SSL_poll() was added in OpenSSL 3.3. 414 415Before 3.5, SSL_poll() did not support blocking operation and 416would fail if called with a NULL I<timeout> parameter or a I<timeout> parameter 417pointing to a B<struct timeval> which was not zero. 418 419Before 3.5, the B<SSL_POLL_EVENT_EL> and B<SSL_POLL_EVENT_IC> 420event types were not present. 421 422=head1 COPYRIGHT 423 424Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved. 425 426Licensed under the Apache License 2.0 (the "License"). You may not use 427this file except in compliance with the License. You can obtain a copy 428in the file LICENSE in the source distribution or at 429L<https://www.openssl.org/source/license.html>. 430 431=cut 432