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