SSL_pending.pod 2.6 KB
Newer Older
1 2 3 4
=pod

=head1 NAME

5 6
SSL_pending, SSL_has_pending - check for readable bytes buffered in an
SSL object
7 8 9 10 11

=head1 SYNOPSIS

 #include <openssl/ssl.h>

12
 int SSL_pending(const SSL *ssl);
13
 int SSL_has_pending(const SSL *s);
14 15 16

=head1 DESCRIPTION

17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
Data is received in whole blocks known as records from the peer. A whole record
is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
read by the application via a call to L<SSL_read(3)>.

SSL_pending() returns the number of bytes which have been processed, buffered
and are available inside B<ssl> for immediate read.

If the B<SSL> object's I<read_ahead> flag is set (see
L<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current
record) may have been read containing more TLS/SSL records. This also applies to
DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These
additional bytes will be buffered by OpenSSL but will remain unprocessed until
they are needed. As these bytes are still in an unprocessed state SSL_pending()
will ignore them. Therefore it is possible for no more bytes to be readable from
the underlying BIO (because OpenSSL has already read them) and for SSL_pending()
to return 0, even though readable application data bytes are available (because
the data is in unprocessed buffered records).

SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or
unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to
return 1, and then a subsequent call to SSL_read() to return no data because the
unprocessed buffered data when processed yielded no application data (for
M
Matt Caswell 已提交
39
example this can happen during renegotiation). It is also possible in this
40 41 42
scenario for SSL_has_pending() to continue to return 1 even after an SSL_read()
call because the buffered and unprocessed data is not yet processable (e.g.
because OpenSSL has only received a partial record so far).
43 44 45

=head1 RETURN VALUES

46 47 48
SSL_pending() returns the number of buffered and processed application data
bytes that are pending and are available for immediate read. SSL_has_pending()
returns 1 if there is buffered record data in the SSL object and 0 otherwise.
49

50
=head1 SEE ALSO
B
Bodo Möller 已提交
51

52 53
L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,
L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(3)>
B
Bodo Möller 已提交
54

55
=head1 HISTORY
B
Bodo Möller 已提交
56

57
The SSL_has_pending() function was added in OpenSSL 1.1.0.
58 59

=cut
R
Rich Salz 已提交
60 61 62 63 64 65 66 67 68 69 70

=head1 COPYRIGHT

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (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
L<https://www.openssl.org/source/license.html>.

=cut