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