1.\" $OpenBSD: BIO_f_buffer.3,v 1.17 2023/04/29 12:22:08 schwarze Exp $ 2.\" full merge up to OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2000, 2010, 2015, 2016 The OpenSSL Project. 23.\" All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: April 29 2023 $ 70.Dt BIO_F_BUFFER 3 71.Os 72.Sh NAME 73.Nm BIO_f_buffer , 74.Nm BIO_get_buffer_num_lines , 75.Nm BIO_set_read_buffer_size , 76.Nm BIO_set_write_buffer_size , 77.Nm BIO_set_buffer_size , 78.Nm BIO_set_buffer_read_data 79.\" .Nm BIO_buffer_get_num_lines and 80.\" .Nm BIO_CTRL_GET are intentionally undocumented. 81.\" Contrary to what bio.h says, they do not *not* get some "IO type", 82.\" whatever that is supposed to be, but are NOOPs, and nothing uses them. 83.Nd buffering BIO 84.Sh SYNOPSIS 85.In openssl/bio.h 86.Ft const BIO_METHOD * 87.Fo BIO_f_buffer 88.Fa void 89.Fc 90.Ft long 91.Fo BIO_get_buffer_num_lines 92.Fa "BIO *b" 93.Fc 94.Ft long 95.Fo BIO_set_read_buffer_size 96.Fa "BIO *b" 97.Fa "long size" 98.Fc 99.Ft long 100.Fo BIO_set_write_buffer_size 101.Fa "BIO *b" 102.Fa "long size" 103.Fc 104.Ft long 105.Fo BIO_set_buffer_size 106.Fa "BIO *b" 107.Fa "long size" 108.Fc 109.Ft long 110.Fo BIO_set_buffer_read_data 111.Fa "BIO *b" 112.Fa "void *buf" 113.Fa "long num" 114.Fc 115.Sh DESCRIPTION 116.Fn BIO_f_buffer 117returns the buffering BIO method. 118.Pp 119Data written to a buffering BIO is buffered and periodically written 120to the next BIO in the chain. 121Data read from a buffering BIO comes from an internal buffer 122which is filled from the next BIO in the chain. 123Both 124.Xr BIO_gets 3 125and 126.Xr BIO_puts 3 127are supported. 128.Pp 129Calling 130.Xr BIO_reset 3 131on a buffering BIO clears any buffered data. 132.Pp 133.Fn BIO_get_buffer_num_lines 134returns the number of lines currently buffered. 135.Pp 136.Fn BIO_set_read_buffer_size , 137.Fn BIO_set_write_buffer_size , 138and 139.Fn BIO_set_buffer_size 140set the read, write or both read and write buffer sizes to 141.Fa size . 142The initial buffer size is 143.Dv DEFAULT_BUFFER_SIZE , 144currently 4096. 145Any attempt to reduce the buffer size below 146.Dv DEFAULT_BUFFER_SIZE 147is ignored. 148Any buffered data is cleared when the buffer is resized. 149.Pp 150.Fn BIO_set_buffer_read_data 151clears the read buffer and fills it with 152.Fa num 153bytes of 154.Fa buf . 155If 156.Fa num 157is larger than the current buffer size, the buffer is expanded. 158.Pp 159Buffering BIOs implement 160.Xr BIO_gets 3 161by using 162.Xr BIO_read 3 163operations on the next BIO in the chain. 164By prepending a buffering BIO to a chain 165it is therefore possible to provide the functionality of 166.Xr BIO_gets 3 167if the following BIOs do not support it (for example SSL BIOs). 168.Pp 169Data is only written to the next BIO in the chain 170when the write buffer fills or when 171.Xr BIO_flush 3 172is called. 173It is therefore important to call 174.Xr BIO_flush 3 175whenever any pending data should be written 176such as when removing a buffering BIO using 177.Xr BIO_pop 3 . 178.Xr BIO_flush 3 179may need to be retried if the ultimate source/sink BIO is non-blocking. 180.Pp 181When a chain containing a buffering BIO is copied with 182.Xr BIO_dup_chain 3 , 183.Fn BIO_set_read_buffer_size 184and 185.Fn BIO_set_write_buffer_size 186are called internally to automatically copy both buffer sizes from the 187original BIO object to the new one. 188.Pp 189.Xr BIO_ctrl 3 190.Fa cmd 191arguments correspond to macros as follows: 192.Bl -column BIO_C_GET_BUFF_NUM_LINES BIO_get_buffer_num_lines() -offset 3n 193.It Fa cmd No constant Ta corresponding macro 194.It Dv BIO_C_GET_BUFF_NUM_LINES Ta Fn BIO_get_buffer_num_lines 195.It Dv BIO_C_SET_BUFF_READ_DATA Ta Fn BIO_set_buffer_read_data 196.It Dv BIO_C_SET_BUFF_SIZE Ta Fn BIO_set_buffer_size 197.It Dv BIO_CTRL_FLUSH Ta Xr BIO_flush 3 198.It Dv BIO_CTRL_PENDING Ta Xr BIO_pending 3 199.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 200.It Dv BIO_CTRL_WPENDING Ta Xr BIO_wpending 3 201.El 202.Pp 203The 204.Fa cmd 205constant 206.Dv BIO_C_SET_BUFF_SIZE 207is special. 208It is also used for 209.Xr BIO_int_ctrl 3 210with the following 211.Fa iarg 212arguments: 213.Bl -column BIO_C_SET_BUFF_SIZE iarg BIO_set_write_buffer_size() -offset 3n 214.It Fa cmd No constant Ta Fa iarg Ta corresponding macro 215.It Dv BIO_C_SET_BUFF_SIZE Ta 0 Ta Fn BIO_set_read_buffer_size 216.It Ta 1 Ta Fn BIO_set_write_buffer_size 217.El 218.Sh RETURN VALUES 219.Fn BIO_f_buffer 220returns the buffering BIO method. 221.Pp 222When called on a buffering BIO object, 223.Xr BIO_method_type 3 224returns the constant 225.Dv BIO_TYPE_BUFFER 226and 227.Xr BIO_method_name 3 228returns a pointer to the static string 229.Qq buffer . 230.Pp 231.Fn BIO_get_buffer_num_lines 232returns the number of lines buffered (may be 0). 233.Pp 234.Fn BIO_set_read_buffer_size , 235.Fn BIO_set_write_buffer_size , 236and 237.Fn BIO_set_buffer_size 238return 1 if the buffer was successfully resized or 0 for failure. 239.Pp 240.Fn BIO_set_buffer_read_data 241returns 1 if the data was set correctly or 0 if there was an error. 242.Sh SEE ALSO 243.Xr BIO_ctrl 3 , 244.Xr BIO_flush 3 , 245.Xr BIO_new 3 , 246.Xr BIO_pop 3 , 247.Xr BIO_reset 3 248.Sh HISTORY 249.Fn BIO_f_buffer 250first appeared in SSLeay 0.6.0. 251.Fn BIO_get_buffer_num_lines 252and 253.Fn BIO_set_buffer_size 254first appeared in SSLeay 0.6.5. 255.Fn BIO_set_read_buffer_size 256and 257.Fn BIO_set_write_buffer_size 258first appeared in SSLeay 0.8.0. 259.Fn BIO_set_buffer_read_data 260first appeared in SSLeay 0.9.0. 261All these functions have been available since 262.Ox 2.4 . 263