summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/BIO_read.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/BIO_read.3')
-rw-r--r--src/lib/libcrypto/man/BIO_read.3281
1 files changed, 0 insertions, 281 deletions
diff --git a/src/lib/libcrypto/man/BIO_read.3 b/src/lib/libcrypto/man/BIO_read.3
deleted file mode 100644
index 5fea9f728a..0000000000
--- a/src/lib/libcrypto/man/BIO_read.3
+++ /dev/null
@@ -1,281 +0,0 @@
1.\" $OpenBSD: BIO_read.3,v 1.11 2022/12/18 17:40:55 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) 2021, 2022 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, 2016 The OpenSSL Project. All rights reserved.
23.\"
24.\" Redistribution and use in source and binary forms, with or without
25.\" modification, are permitted provided that the following conditions
26.\" are met:
27.\"
28.\" 1. Redistributions of source code must retain the above copyright
29.\" notice, this list of conditions and the following disclaimer.
30.\"
31.\" 2. Redistributions in binary form must reproduce the above copyright
32.\" notice, this list of conditions and the following disclaimer in
33.\" the documentation and/or other materials provided with the
34.\" distribution.
35.\"
36.\" 3. All advertising materials mentioning features or use of this
37.\" software must display the following acknowledgment:
38.\" "This product includes software developed by the OpenSSL Project
39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
40.\"
41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
42.\" endorse or promote products derived from this software without
43.\" prior written permission. For written permission, please contact
44.\" openssl-core@openssl.org.
45.\"
46.\" 5. Products derived from this software may not be called "OpenSSL"
47.\" nor may "OpenSSL" appear in their names without prior written
48.\" permission of the OpenSSL Project.
49.\"
50.\" 6. Redistributions of any form whatsoever must retain the following
51.\" acknowledgment:
52.\" "This product includes software developed by the OpenSSL Project
53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
54.\"
55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66.\" OF THE POSSIBILITY OF SUCH DAMAGE.
67.\"
68.Dd $Mdocdate: December 18 2022 $
69.Dt BIO_READ 3
70.Os
71.Sh NAME
72.Nm BIO_read ,
73.Nm BIO_number_read ,
74.Nm BIO_gets ,
75.Nm BIO_write ,
76.Nm BIO_puts ,
77.Nm BIO_indent ,
78.Nm BIO_number_written
79.Nd BIO I/O functions
80.Sh SYNOPSIS
81.In openssl/bio.h
82.Ft int
83.Fo BIO_read
84.Fa "BIO *b"
85.Fa "void *buf"
86.Fa "int len"
87.Fc
88.Ft unsigned long
89.Fo BIO_number_read
90.Fa "BIO *b"
91.Fc
92.Ft int
93.Fo BIO_gets
94.Fa "BIO *b"
95.Fa "char *buf"
96.Fa "int size"
97.Fc
98.Ft int
99.Fo BIO_write
100.Fa "BIO *b"
101.Fa "const void *buf"
102.Fa "int len"
103.Fc
104.Ft int
105.Fo BIO_puts
106.Fa "BIO *b"
107.Fa "const char *string"
108.Fc
109.Ft int
110.Fo BIO_indent
111.Fa "BIO *b"
112.Fa "int indent"
113.Fa "int max"
114.Fc
115.Ft unsigned long
116.Fo BIO_number_written
117.Fa "BIO *b"
118.Fc
119.Sh DESCRIPTION
120.Fn BIO_read
121attempts to read
122.Fa len
123bytes from
124.Fa b
125and places the data in
126.Fa buf .
127.Pp
128.Fn BIO_number_read
129returns the grand total of bytes read from
130.Fa b
131using
132.Fn BIO_read
133so far.
134Bytes read with
135.Fn BIO_gets
136do
137.Sy not
138count.
139.Xr BIO_new 3
140and
141.Xr BIO_set 3
142initialize the counter to 0.
143When reading very large amounts of data,
144the counter will eventually wrap around from
145.Dv ULONG_MAX
146to 0.
147.Pp
148.Fn BIO_gets
149performs the BIOs "gets" operation and places the data in
150.Fa buf .
151Usually this operation will attempt to read a line of data
152from the BIO of maximum length
153.Fa size No \- 1 .
154There are exceptions to this however, for example
155.Fn BIO_gets
156on a digest BIO will calculate and return the digest
157and other BIOs may not support
158.Fn BIO_gets
159at all.
160The returned string is always NUL-terminated.
161.Pp
162.Fn BIO_write
163attempts to write
164.Fa len
165bytes from
166.Fa buf
167to
168.Fa b .
169.Pp
170.Fn BIO_puts
171attempts to write the NUL-terminated
172.Fa string
173to
174.Fa b .
175.Pp
176.Fn BIO_indent
177attempts to write
178.Fa indent
179space characters to
180.Fa b ,
181but not more than
182.Fa max
183characters.
184.Pp
185.Fn BIO_number_written
186returns the grand total of bytes written to
187.Fa b
188using
189.Fn BIO_write ,
190.Fn BIO_puts ,
191and
192.Fn BIO_indent
193so far.
194.Xr BIO_new 3
195and
196.Xr BIO_set 3
197initialize the counter to 0.
198When writing very large amounts of data,
199the counter will eventually wrap around from
200.Dv ULONG_MAX
201to 0.
202.Pp
203One technique sometimes used with blocking sockets
204is to use a system call (such as
205.Xr select 2 ,
206.Xr poll 2
207or equivalent) to determine when data is available and then call
208.Xr read 2
209to read the data.
210The equivalent with BIOs (that is call
211.Xr select 2
212on the underlying I/O structure and then call
213.Fn BIO_read
214to read the data) should
215.Em not
216be used because a single call to
217.Fn BIO_read
218can cause several reads (and writes in the case of SSL BIOs)
219on the underlying I/O structure and may block as a result.
220Instead
221.Xr select 2
222(or equivalent) should be combined with non-blocking I/O
223so successive reads will request a retry instead of blocking.
224.Pp
225See
226.Xr BIO_should_retry 3
227for details of how to determine the cause of a retry and other I/O issues.
228.Pp
229If the
230.Fn BIO_gets
231function is not supported by a BIO then it is possible to
232work around this by adding a buffering BIO
233.Xr BIO_f_buffer 3
234to the chain.
235.Sh RETURN VALUES
236.Fn BIO_indent
237returns 1 if successful, even if nothing was written,
238or 0 if writing fails.
239.Pp
240.Fn BIO_number_read
241and
242.Fn BIO_number_written
243return a number of bytes or 0 if
244.Fa b
245is a
246.Dv NULL
247pointer.
248.Pp
249The other functions return either the amount of data successfully
250read or written (if the return value is positive) or that no data
251was successfully read or written if the result is 0 or \-1.
252If the return value is \-2, then the operation is not implemented
253in the specific BIO type.
254The trailing NUL is not included in the length returned by
255.Fn BIO_gets .
256.Pp
257A 0 or \-1 return is not necessarily an indication of an error.
258In particular when the source/sink is non-blocking or of a certain type
259it may merely be an indication that no data is currently available and that
260the application should retry the operation later.
261.Sh SEE ALSO
262.Xr BIO_meth_new 3 ,
263.Xr BIO_new 3 ,
264.Xr BIO_should_retry 3
265.Sh HISTORY
266.Fn BIO_read ,
267.Fn BIO_gets ,
268.Fn BIO_write ,
269and
270.Fn BIO_puts
271first appeared in SSLeay 0.6.0.
272.Fn BIO_number_read
273and
274.Fn BIO_number_written
275first appeared in SSLeay 0.6.5.
276These functions have been available since
277.Ox 2.4 .
278.Pp
279.Fn BIO_indent
280first appeared in OpenSSL 0.9.7 and has been available since
281.Ox 3.4 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 16:55:53 +0000