]>
Commit | Line | Data |
---|---|---|
85074745 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
91da5e77 RS |
5 | SSL_CTX_set_read_ahead, SSL_CTX_get_read_ahead, |
6 | SSL_set_read_ahead, SSL_get_read_ahead, | |
7 | SSL_CTX_get_default_read_ahead | |
85074745 MC |
8 | - manage whether to read as many input bytes as possible |
9 | ||
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/ssl.h> | |
13 | ||
85074745 | 14 | void SSL_set_read_ahead(SSL *s, int yes); |
91da5e77 | 15 | int SSL_get_read_ahead(const SSL *s); |
85074745 | 16 | |
91da5e77 RS |
17 | SSL_CTX_set_read_ahead(SSL_CTX *ctx, int yes); |
18 | long SSL_CTX_get_read_ahead(SSL_CTX *ctx); | |
19 | long SSL_CTX_get_default_read_ahead(SSL_CTX *ctx); | |
85074745 MC |
20 | |
21 | =head1 DESCRIPTION | |
22 | ||
23 | SSL_CTX_set_read_ahead() and SSL_set_read_ahead() set whether we should read as | |
24 | many input bytes as possible (for non-blocking reads) or not. For example if | |
25 | B<x> bytes are currently required by OpenSSL, but B<y> bytes are available from | |
26 | the underlying BIO (where B<y> > B<x>), then OpenSSL will read all B<y> bytes | |
27 | into its buffer (providing that the buffer is large enough) if reading ahead is | |
57fd5170 KR |
28 | on, or B<x> bytes otherwise. |
29 | Setting the parameter B<yes> to 0 turns reading ahead is off, other values turn | |
30 | it on. | |
91da5e77 | 31 | SSL_CTX_set_default_read_ahead() is identical to SSL_CTX_set_read_ahead(). |
85074745 MC |
32 | |
33 | SSL_CTX_get_read_ahead() and SSL_get_read_ahead() indicate whether reading | |
34 | ahead has been set or not. | |
57fd5170 | 35 | SSL_CTX_get_default_read_ahead() is identical to SSL_CTX_get_read_ahead(). |
85074745 MC |
36 | |
37 | =head1 NOTES | |
38 | ||
39 | These functions have no impact when used with DTLS. The return values for | |
d7ded13a MC |
40 | SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS. Setting |
41 | B<read_ahead> can impact the behaviour of the SSL_pending() function | |
c1e35057 | 42 | (see L<SSL_pending(3)>). |
85074745 | 43 | |
57fd5170 KR |
44 | Since SSL_read() can return B<SSL_ERROR_WANT_READ> for non-application data |
45 | records, and SSL_has_pending() can't tell the difference between processed and | |
46 | unprocessed data, it's recommended that if read ahead is turned on that | |
47 | B<SSL_MODE_AUTO_RETRY> is not turned off using SSL_CTX_clear_mode(). | |
48 | That will prevent getting B<SSL_ERROR_WANT_READ> when there is still a complete | |
3dcbb6c4 | 49 | record available that hasn't been processed. |
57fd5170 KR |
50 | |
51 | If the application wants to continue to use the underlying transport (e.g. TCP | |
52 | connection) after the SSL connection is finished using SSL_shutdown() reading | |
53 | ahead should be turned off. | |
54 | Otherwise the SSL structure might read data that it shouldn't. | |
55 | ||
85074745 MC |
56 | =head1 RETURN VALUES |
57 | ||
c952780c | 58 | SSL_get_read_ahead() and SSL_CTX_get_read_ahead() return 0 if reading ahead is off, |
85074745 MC |
59 | and non zero otherwise. |
60 | ||
61 | =head1 SEE ALSO | |
62 | ||
b97fdb57 | 63 | L<ssl(7)>, L<SSL_pending(3)> |
85074745 | 64 | |
e2f92610 RS |
65 | =head1 COPYRIGHT |
66 | ||
1212818e | 67 | Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 68 | |
4746f25a | 69 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |