summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/BIO_f_buffer.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libcrypto/man/BIO_f_buffer.3262
1 files changed, 0 insertions, 262 deletions
diff --git a/src/lib/libcrypto/man/BIO_f_buffer.3 b/src/lib/libcrypto/man/BIO_f_buffer.3
deleted file mode 100644
index a3012c5c5d..0000000000
--- a/src/lib/libcrypto/man/BIO_f_buffer.3
+++ /dev/null
@@ -1,262 +0,0 @@
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 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 22:12:53 +0000