xref: /openssl/doc/man3/SSL_pending.pod (revision e39e295e)
1=pod
2
3=head1 NAME
4
5SSL_pending, SSL_has_pending - check for readable bytes buffered in an
6SSL object
7
8=head1 SYNOPSIS
9
10 #include <openssl/ssl.h>
11
12 int SSL_pending(const SSL *ssl);
13 int SSL_has_pending(const SSL *s);
14
15=head1 DESCRIPTION
16
17Data is received in whole blocks known as records from the peer. A whole record
18is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
19read by the application via a call to L<SSL_read_ex(3)> or L<SSL_read(3)>.
20
21SSL_pending() returns the number of bytes which have been processed, buffered
22and are available inside B<ssl> for immediate read.
23
24If the B<SSL> object's I<read_ahead> flag is set (see
25L<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current
26record) may have been read containing more TLS/SSL records. This also applies to
27DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These
28additional bytes will be buffered by OpenSSL but will remain unprocessed until
29they are needed. As these bytes are still in an unprocessed state SSL_pending()
30will ignore them. Therefore, it is possible for no more bytes to be readable from
31the underlying BIO (because OpenSSL has already read them) and for SSL_pending()
32to return 0, even though readable application data bytes are available (because
33the data is in unprocessed buffered records).
34
35SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or
36unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to
37return 1, and then a subsequent call to SSL_read_ex() or SSL_read() to return no
38data because the unprocessed buffered data when processed yielded no application
39data (for example this can happen during renegotiation). It is also possible in
40this scenario for SSL_has_pending() to continue to return 1 even after an
41SSL_read_ex() or SSL_read() call because the buffered and unprocessed data is
42not yet processable (e.g. because OpenSSL has only received a partial record so
43far).
44
45=head1 RETURN VALUES
46
47SSL_pending() returns the number of buffered and processed application data
48bytes that are pending and are available for immediate read. SSL_has_pending()
49returns 1 if there is buffered record data in the SSL object and 0 otherwise.
50
51=head1 SEE ALSO
52
53L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,
54L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(7)>
55
56=head1 HISTORY
57
58The SSL_has_pending() function was added in OpenSSL 1.1.0.
59
60=head1 COPYRIGHT
61
62Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
63
64Licensed under the Apache License 2.0 (the "License").  You may not use
65this file except in compliance with the License.  You can obtain a copy
66in the file LICENSE in the source distribution or at
67L<https://www.openssl.org/source/license.html>.
68
69=cut
70