| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | SSL_set_blocking_mode, SSL_get_blocking_mode - configure blocking mode for a
|
|---|
| 6 | QUIC SSL object
|
|---|
| 7 |
|
|---|
| 8 | =head1 SYNOPSIS
|
|---|
| 9 |
|
|---|
| 10 | #include <openssl/ssl.h>
|
|---|
| 11 |
|
|---|
| 12 | int SSL_set_blocking_mode(SSL *s, int blocking);
|
|---|
| 13 | int SSL_get_blocking_mode(SSL *s);
|
|---|
| 14 |
|
|---|
| 15 | =head1 DESCRIPTION
|
|---|
| 16 |
|
|---|
| 17 | SSL_set_blocking_mode() can be used to enable or disable blocking mode on a QUIC
|
|---|
| 18 | connection SSL object. By default, blocking is enabled, unless the SSL object is
|
|---|
| 19 | configured to use an underlying read or write BIO which cannot provide a poll
|
|---|
| 20 | descriptor (see L<BIO_get_rpoll_descriptor(3)>), as blocking mode cannot be
|
|---|
| 21 | supported in this case.
|
|---|
| 22 |
|
|---|
| 23 | To enable blocking mode, call SSL_set_blocking_mode() with I<blocking> set to 1;
|
|---|
| 24 | to disable it, call SSL_set_blocking_mode() with I<blocking> set to 0.
|
|---|
| 25 |
|
|---|
| 26 | To retrieve the current blocking mode, call SSL_get_blocking_mode().
|
|---|
| 27 |
|
|---|
| 28 | Blocking mode means that calls such as SSL_read() and SSL_write() will block
|
|---|
| 29 | until the requested operation can be performed. In nonblocking mode, these
|
|---|
| 30 | calls will fail if the requested operation cannot be performed immediately; see
|
|---|
| 31 | L<SSL_get_error(3)>.
|
|---|
| 32 |
|
|---|
| 33 | These functions are only applicable to QUIC connection SSL objects. Other kinds
|
|---|
| 34 | of SSL object, such as those for TLS, automatically function in blocking or
|
|---|
| 35 | nonblocking mode based on whether the underlying network read and write BIOs
|
|---|
| 36 | provided to the SSL object are themselves configured in nonblocking mode.
|
|---|
| 37 |
|
|---|
| 38 | Where a QUIC connection SSL object is used in nonblocking mode, an application
|
|---|
| 39 | is responsible for ensuring that the SSL object is ticked regularly; see
|
|---|
| 40 | L<SSL_handle_events(3)>.
|
|---|
| 41 |
|
|---|
| 42 | Blocking mode is disabled automatically if the application provides a QUIC
|
|---|
| 43 | connection SSL object with a network BIO which cannot support blocking mode. To
|
|---|
| 44 | re-enable blocking mode in this case, an application must set a network BIO
|
|---|
| 45 | which can support blocking mode and explicitly call SSL_set_blocking_mode().
|
|---|
| 46 |
|
|---|
| 47 | =head1 RETURN VALUES
|
|---|
| 48 |
|
|---|
| 49 | SSL_set_blocking_mode() returns 1 on success and 0 on failure. The function
|
|---|
| 50 | fails if called on a SSL object which does not represent a QUIC connection,
|
|---|
| 51 | or if blocking mode cannot be used for the given connection.
|
|---|
| 52 |
|
|---|
| 53 | SSL_get_blocking_mode() returns 1 if blocking is currently enabled. It returns
|
|---|
| 54 | -1 if called on an unsupported SSL object.
|
|---|
| 55 |
|
|---|
| 56 | =head1 SEE ALSO
|
|---|
| 57 |
|
|---|
| 58 | L<SSL_handle_events(3)>, L<ssl(7)>
|
|---|
| 59 |
|
|---|
| 60 | =head1 HISTORY
|
|---|
| 61 |
|
|---|
| 62 | The SSL_set_blocking_mode() and SSL_get_blocking_mode() functions were added in
|
|---|
| 63 | OpenSSL 3.2.
|
|---|
| 64 |
|
|---|
| 65 | =head1 COPYRIGHT
|
|---|
| 66 |
|
|---|
| 67 | Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 68 |
|
|---|
| 69 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 70 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 71 | in the file LICENSE in the source distribution or at
|
|---|
| 72 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 73 |
|
|---|
| 74 | =cut
|
|---|
