Fix typo in SSL_pending docs
[openssl.git] / doc / ssl / SSL_pending.pod
1 =pod
2
3 =head1 NAME
4
5 SSL_pending, SSL_has_pending - check for readable bytes buffered in an
6 SSL 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
17 Data is received in whole blocks known as records from the peer. A whole record
18 is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
19 read by the application via a call to L<SSL_read(3)>.
20
21 SSL_pending() returns the number of bytes which have been processed, buffered
22 and are available inside B<ssl> for immediate read.
23
24 If the B<SSL> object's I<read_ahead> flag is set (see
25 L<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current
26 record) may have been read containing more TLS/SSL records. This also applies to
27 DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These
28 additional bytes will be buffered by OpenSSL but will remain unprocessed until
29 they are needed. As these bytes are still in an unprocessed state SSL_pending()
30 will ignore them. Therefore it is possible for no more bytes to be readable from
31 the underlying BIO (because OpenSSL has already read them) and for SSL_pending()
32 to return 0, even though readable application data bytes are available (because
33 the data is in unprocessed buffered records).
34
35 SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or
36 unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to
37 return 1, and then a subsequent call to SSL_read() to return no data because the
38 unprocessed buffered data when processed yielded no application data (for
39 example this can happen during renegotiation). It is also possible in this
40 scenario for SSL_has_pending() to continue to return 1 even after an SSL_read()
41 call because the buffered and unprocessed data is not yet processable (e.g.
42 because OpenSSL has only received a partial record so far).
43
44 =head1 RETURN VALUES
45
46 SSL_pending() returns the number of buffered and processed application data
47 bytes that are pending and are available for immediate read. SSL_has_pending()
48 returns 1 if there is buffered record data in the SSL object and 0 otherwise.
49
50 =head1 SEE ALSO
51
52 L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,
53 L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(3)>
54
55 =head1 HISTORY
56
57 The SSL_has_pending() function was added in OpenSSL 1.1.0.
58
59 =cut