- NAME
- SYNOPSIS
- DESCRIPTION
- RETURN VALUES
- SEE ALSO
- HISTORY
- COPYRIGHT

# NAME

SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_net_read_desired, SSL_net_write_desired - obtain information which can be used to determine when network I/O can be performed

# SYNOPSIS

     #include <openssl/ssl.h>

     int SSL_get_rpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
     int SSL_get_wpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
     int SSL_net_read_desired(SSL *s);
     int SSL_net_write_desired(SSL *s);

# DESCRIPTION

The functions `SSL_get_rpoll_descriptor()` and `SSL_get_wpoll_descriptor()` can be used to determine when an SSL object which represents a QUIC connection can perform useful network I/O, so that an application using a QUIC connection SSL object in nonblocking mode can determine when it should call `SSL_handle_events()`.

On success, these functions output poll descriptors. For more information on poll descriptors, see BIO_get_rpoll_descriptor(3).

The functions `SSL_net_read_desired()` and `SSL_net_write_desired()` return 1 or 0 depending on whether the SSL object is currently interested in receiving data from the network and/or writing data to the network respectively. If an SSL object is not interested in reading data from the network at the current time, `SSL_net_read_desired()` will return 0; likewise, if an SSL object is not interested in writing data to the network at the current time, `SSL_net_write_desired()` will return 0.

The intention is that an application using QUIC in nonblocking mode can use these calls, in conjunction with SSL_get_event_timeout(3) to wait for network I/O conditions which allow the SSL object to perform useful work. When such a condition arises, SSL_handle_events(3) should be called.

In particular, the expected usage is as follows:

- `SSL_handle_events()` should be called whenever the timeout returned by `SSL_get_event_timeout(3)` (if any) expires

- If the last call to `SSL_net_read_desired()` returned 1, `SSL_handle_events()` should be called whenever the poll descriptor output by `SSL_get_rpoll_descriptor()` becomes readable.

- If the last call to `SSL_net_write_desired()` returned 1, `SSL_handle_events()` should be called whenever the poll descriptor output by `SSL_get_wpoll_descriptor()` becomes writable.

The return values of the `SSL_net_read_desired()` and `SSL_net_write_desired()` functions may change in response to any call to the SSL object other than `SSL_net_read_desired()`, `SSL_net_write_desired()`, `SSL_get_rpoll_descriptor()`, `SSL_get_wpoll_descriptor()` and `SSL_get_event_timeout()`.

On non-QUIC SSL objects, calls to `SSL_get_rpoll_descriptor()` and `SSL_get_wpoll_descriptor()` function the same as calls to `BIO_get_rpoll_descriptor()` and `BIO_get_wpoll_descriptor()` on the respective read and write BIOs configured on the SSL object.

On non-QUIC SSL objects, calls to `SSL_net_read_desired()` and `SSL_net_write_desired()` function identically to calls to `SSL_want_read()` and `SSL_want_write()` respectively.

# RETURN VALUES

These functions return 1 on success and 0 on failure.

# SEE ALSO

SSL_handle_events(3), SSL_get_event_timeout(3), ssl(7)

# HISTORY

The `SSL_get_rpoll_descriptor()`, `SSL_get_wpoll_descriptor()`, `SSL_net_read_desired()` and `SSL_net_write_desired()` functions were added in OpenSSL 3.2.

# COPYRIGHT

Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.

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.