]>
Commit | Line | Data |
---|---|---|
3b2cbbcb DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c RS |
5 | BIO_get_buffer_num_lines, |
6 | BIO_set_read_buffer_size, | |
7 | BIO_set_write_buffer_size, | |
8 | BIO_set_buffer_size, | |
9 | BIO_set_buffer_read_data, | |
91da5e77 RS |
10 | BIO_f_buffer |
11 | - buffering BIO | |
3b2cbbcb DSH |
12 | |
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/bio.h> | |
16 | ||
91da5e77 | 17 | const BIO_METHOD *BIO_f_buffer(void); |
3b2cbbcb | 18 | |
91da5e77 RS |
19 | long BIO_get_buffer_num_lines(BIO *b); |
20 | long BIO_set_read_buffer_size(BIO *b, long size); | |
21 | long BIO_set_write_buffer_size(BIO *b, long size); | |
22 | long BIO_set_buffer_size(BIO *b, long size); | |
23 | long BIO_set_buffer_read_data(BIO *b, void *buf, long num); | |
3b2cbbcb DSH |
24 | |
25 | =head1 DESCRIPTION | |
26 | ||
27 | BIO_f_buffer() returns the buffering BIO method. | |
28 | ||
29 | Data written to a buffering BIO is buffered and periodically written | |
30 | to the next BIO in the chain. Data read from a buffering BIO comes from | |
31 | an internal buffer which is filled from the next BIO in the chain. | |
32 | Both BIO_gets() and BIO_puts() are supported. | |
33 | ||
34 | Calling BIO_reset() on a buffering BIO clears any buffered data. | |
35 | ||
36 | BIO_get_buffer_num_lines() returns the number of lines currently buffered. | |
37 | ||
38 | BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() | |
39 | set the read, write or both read and write buffer sizes to B<size>. The initial | |
827f3d5f | 40 | buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the |
3b2cbbcb DSH |
41 | buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared |
42 | when the buffer is resized. | |
43 | ||
44 | BIO_set_buffer_read_data() clears the read buffer and fills it with B<num> | |
45 | bytes of B<buf>. If B<num> is larger than the current buffer size the buffer | |
46 | is expanded. | |
47 | ||
48 | =head1 NOTES | |
49 | ||
91da5e77 RS |
50 | These functions, other than BIO_f_buffer(), are implemented as macros. |
51 | ||
b055fceb | 52 | Buffering BIOs implement BIO_gets() by using BIO_read_ex() operations on the |
3b2cbbcb DSH |
53 | next BIO in the chain. By prepending a buffering BIO to a chain it is therefore |
54 | possible to provide BIO_gets() functionality if the following BIOs do not | |
55 | support it (for example SSL BIOs). | |
56 | ||
57 | Data is only written to the next BIO in the chain when the write buffer fills | |
58 | or when BIO_flush() is called. It is therefore important to call BIO_flush() | |
59 | whenever any pending data should be written such as when removing a buffering | |
60 | BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate | |
61 | source/sink BIO is non blocking. | |
62 | ||
63 | =head1 RETURN VALUES | |
64 | ||
65 | BIO_f_buffer() returns the buffering BIO method. | |
66 | ||
67 | BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0). | |
68 | ||
69 | BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() | |
70 | return 1 if the buffer was successfully resized or 0 for failure. | |
71 | ||
72 | BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if | |
73 | there was an error. | |
74 | ||
75 | =head1 SEE ALSO | |
76 | ||
b97fdb57 | 77 | L<bio(7)>, |
9b86974e RS |
78 | L<BIO_reset(3)>, |
79 | L<BIO_flush(3)>, | |
80 | L<BIO_pop(3)>, | |
81 | L<BIO_ctrl(3)>. | |
99ec4fdb | 82 | |
e2f92610 RS |
83 | =head1 COPYRIGHT |
84 | ||
85 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
86 | ||
4746f25a | 87 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
88 | this file except in compliance with the License. You can obtain a copy |
89 | in the file LICENSE in the source distribution or at | |
90 | L<https://www.openssl.org/source/license.html>. | |
91 | ||
92 | =cut |