summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/BIO_get_data.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/BIO_get_data.3')
-rw-r--r--src/lib/libcrypto/man/BIO_get_data.3406
1 files changed, 0 insertions, 406 deletions
diff --git a/src/lib/libcrypto/man/BIO_get_data.3 b/src/lib/libcrypto/man/BIO_get_data.3
deleted file mode 100644
index 63750ac37b..0000000000
--- a/src/lib/libcrypto/man/BIO_get_data.3
+++ /dev/null
@@ -1,406 +0,0 @@
1.\" $OpenBSD: BIO_get_data.3,v 1.8 2023/11/16 20:27:43 schwarze Exp $
2.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
3.\"
4.\" This file is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2018, 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 Matt Caswell <matt@openssl.org>.
22.\" Copyright (c) 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: November 16 2023 $
69.Dt BIO_GET_DATA 3
70.Os
71.Sh NAME
72.Nm BIO_set_data ,
73.Nm BIO_get_data ,
74.Nm BIO_set_flags ,
75.Nm BIO_clear_flags ,
76.Nm BIO_test_flags ,
77.Nm BIO_get_flags ,
78.Nm BIO_set_retry_read ,
79.Nm BIO_set_retry_write ,
80.Nm BIO_set_retry_special ,
81.Nm BIO_clear_retry_flags ,
82.Nm BIO_get_retry_flags ,
83.Nm BIO_copy_next_retry ,
84.Nm BIO_set_init ,
85.Nm BIO_get_init ,
86.Nm BIO_set_shutdown ,
87.Nm BIO_get_shutdown
88.Nd manage BIO state information
89.Sh SYNOPSIS
90.In openssl/bio.h
91.Ft void
92.Fo BIO_set_data
93.Fa "BIO *a"
94.Fa "void *ptr"
95.Fc
96.Ft void *
97.Fo BIO_get_data
98.Fa "BIO *a"
99.Fc
100.Ft void
101.Fo BIO_set_flags
102.Fa "BIO *a"
103.Fa "int flags"
104.Fc
105.Ft void
106.Fo BIO_clear_flags
107.Fa "BIO *a"
108.Fa "int flags"
109.Fc
110.Ft int
111.Fo BIO_test_flags
112.Fa "const BIO *a"
113.Fa "int flags"
114.Fc
115.Ft int
116.Fo BIO_get_flags
117.Fa "const BIO *a"
118.Fc
119.Ft void
120.Fo BIO_set_retry_read
121.Fa "BIO *a"
122.Fc
123.Ft void
124.Fo BIO_set_retry_write
125.Fa "BIO *a"
126.Fc
127.Ft void
128.Fo BIO_set_retry_special
129.Fa "BIO *a"
130.Fc
131.Ft void
132.Fo BIO_clear_retry_flags
133.Fa "BIO *a"
134.Fc
135.Ft int
136.Fo BIO_get_retry_flags
137.Fa "BIO *a"
138.Fc
139.Ft void
140.Fo BIO_copy_next_retry
141.Fa "BIO *a"
142.Fc
143.Ft void
144.Fo BIO_set_init
145.Fa "BIO *a"
146.Fa "int init"
147.Fc
148.Ft int
149.Fo BIO_get_init
150.Fa "BIO *a"
151.Fc
152.Ft void
153.Fo BIO_set_shutdown
154.Fa "BIO *a"
155.Fa "int shutdown"
156.Fc
157.Ft int
158.Fo BIO_get_shutdown
159.Fa "BIO *a"
160.Fc
161.Sh DESCRIPTION
162These functions are mainly useful when implementing a custom BIO.
163.Pp
164The
165.Fn BIO_set_data
166function associates the custom data pointed to by
167.Fa ptr
168with the
169.Fa "BIO a" .
170This data can subsequently be retrieved via a call to
171.Fn BIO_get_data .
172This can be used by custom BIOs for storing implementation specific
173information.
174.Pp
175.Fn BIO_set_flags
176sets all the bits contained in the
177.Fa flags
178argument in the flags stored in
179.Fa a .
180The value of a flag neither changes when it is already set in
181.Fa a
182nor when it is unset in the
183.Fa flags
184argument.
185.Pp
186.Fn BIO_clear_flags
187clears all the bits contained in the
188.Fa flags
189argument from the flags stored in
190.Fa a .
191The value of a flag neither changes when it is already unset in
192.Fa a
193nor when it is unset in the
194.Fa flags
195argument.
196.Pp
197.Fn BIO_test_flags
198checks whether any of the bits contained in the
199.Fa flags
200argument are set in the flags stored in
201.Fa a .
202Application programs usually call macros like those documented in
203.Xr BIO_should_retry 3
204rather than calling
205.Fn BIO_test_flags
206directly.
207Flag bits correspond to accessor macros as follows:
208.Pp
209.Bl -tag -width BIO_FLAGS_SHOULD_RETRY -compact
210.It Dv BIO_FLAGS_READ
211.Xr BIO_should_read 3
212.It Dv BIO_FLAGS_WRITE
213.Xr BIO_should_write 3
214.It Dv BIO_FLAGS_IO_SPECIAL
215.Xr BIO_should_io_special 3
216.It Dv BIO_FLAGS_RWS
217.Xr BIO_retry_type 3
218.It Dv BIO_FLAGS_SHOULD_RETRY
219.Xr BIO_should_retry 3
220.It Dv BIO_FLAGS_BASE64_NO_NL
221see
222.Xr BIO_f_base64 3
223.It Dv BIO_FLAGS_MEM_RDONLY
224see
225.Xr BIO_s_mem 3
226.El
227.Pp
228In particular,
229.Dv BIO_FLAGS_RWS
230is the bitwise OR of
231.Dv BIO_FLAGS_READ ,
232.Dv BIO_FLAGS_WRITE ,
233and
234.Dv BIO_FLAGS_IO_SPECIAL .
235.Pp
236.Fn BIO_set_retry_read ,
237.Fn BIO_set_retry_write ,
238and
239.Fn BIO_set_retry_special
240set the
241.Dv BIO_FLAGS_READ ,
242.Dv BIO_FLAGS_WRITE ,
243and
244.Dv BIO_FLAGS_IO_SPECIAL
245flag bit in
246.Fa a ,
247respectively.
248They all set the
249.Dv BIO_FLAGS_SHOULD_RETRY
250flag bit, too.
251.Pp
252.Fn BIO_clear_retry_flags
253clears the flag bits
254.Dv BIO_FLAGS_READ ,
255.Dv BIO_FLAGS_WRITE ,
256.Dv BIO_FLAGS_IO_SPECIAL ,
257and
258.Dv BIO_FLAGS_SHOULD_RETRY
259in
260.Fa a .
261.Pp
262.Fn BIO_copy_next_retry
263copies retry-related state data from the BIO that follows
264.Fa a
265in its chain to
266.Fa a ,
267that is, the data accessible with
268.Fn BIO_get_retry_flags
269and
270.Xr BIO_get_retry_reason 3 .
271Flags which are already set in
272.Fa a
273are not cleared.
274Before calling
275.Fn BIO_copy_next_retry ,
276making sure that
277.Fa a
278is not the last BIO in its chain is the responsibility of the caller,
279for example by checking that
280.Xr BIO_next 3
281does not return
282.Dv NULL .
283.Pp
284The
285.Fn BIO_set_init
286function sets the
287.Fa init
288flag in
289.Fa a
290to the specified value.
291A non-zero value indicates that initialisation is complete,
292whilst zero indicates that it is not.
293Often initialisation will complete
294during initial construction of the BIO.
295For some BIOs however, initialisation may not be complete until
296additional steps have been taken, for example through calling custom
297ctrls.
298.Pp
299The
300.Fn BIO_set_shutdown
301and
302.Fn BIO_get_shutdown
303functions are low-level interfaces to forcefully set and get the
304.Fa shutdown
305flag of
306.Fa a ,
307circumventing type-dependent sanity checks,
308exclusively intended for implementing a new BIO type.
309The
310.Fa shutdown
311argument must be either
312.Dv BIO_CLOSE
313or
314.Dv BIO_NOCLOSE .
315When merely using a
316.Vt BIO
317object, call
318.Xr BIO_set_close 3
319and
320.Xr BIO_get_close 3
321instead.
322.Pp
323.Fn BIO_get_flags ,
324.Fn BIO_set_retry_read ,
325.Fn BIO_set_retry_write ,
326.Fn BIO_set_retry_special ,
327.Fn BIO_clear_retry_flags ,
328and
329.Fn BIO_get_retry_flags
330are implemented as macros.
331.Sh RETURN VALUES
332.Fn BIO_get_data
333returns a pointer to the implementation specific custom data associated
334with
335.Fa a ,
336or
337.Dv NULL
338if none is set.
339.Pp
340.Fn BIO_test_flags
341returns the bitwise AND of the
342.Fa flags
343argument and the flags stored in
344.Fa a .
345Consequently, it returns a non-zero value
346if and only if at least one of the requested
347.Fa flags
348is set.
349.Pp
350.Fn BIO_get_flags
351returns all the flags currently stored in
352.Fa a .
353.Pp
354.Fn BIO_get_retry_flags
355returns the bitwise AND of
356.Pq Dv BIO_FLAGS_RWS | BIO_FLAGS_SHOULD_RETRY
357and the flags stored in
358.Fa a .
359.Pp
360.Fn BIO_get_init
361returns the value of the init flag of
362.Fa a .
363.Pp
364.Fn BIO_get_shutdown
365returns the value previously set with
366.Fn BIO_set_shutdown
367or with
368.Xr BIO_set_close 3 .
369.Sh SEE ALSO
370.Xr BIO_meth_new 3 ,
371.Xr BIO_new 3 ,
372.Xr BIO_set_close 3 ,
373.Xr BIO_should_retry 3
374.Sh HISTORY
375.Fn BIO_set_flags ,
376.Fn BIO_clear_flags ,
377.Fn BIO_set_retry_read ,
378.Fn BIO_set_retry_write ,
379.Fn BIO_set_retry_special ,
380.Fn BIO_clear_retry_flags ,
381and
382.Fn BIO_get_retry_flags
383first appeared in SSLeay 0.8.0,
384.Fn BIO_copy_next_retry
385in SSLeay 0.8.1, and
386.Fn BIO_get_flags
387in SSLeay 0.9.0.
388These functions have been available since
389.Ox 2.4 .
390.Pp
391.Fn BIO_test_flags
392first appeared in OpenSSL 0.9.8e and has been available since
393.Ox 4.5 .
394.Pp
395.Fn BIO_set_data ,
396.Fn BIO_get_data ,
397.Fn BIO_set_init ,
398.Fn BIO_set_shutdown ,
399and
400.Fn BIO_get_shutdown
401first appeared in OpenSSL 1.1.0 and have been available since
402.Ox 6.3 .
403.Pp
404.Fn BIO_get_init
405first appeared in OpenSSL 1.1.0 and has been available since
406.Ox 7.1 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 16:36:13 +0000