Debian Codegraph @

upstream/debian-unstable/man3/BIO_new.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BIO_NEW 3SSL"
58 .TH BIO_NEW 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BIO_new_ex, BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all
65 \&\- BIO allocation and freeing functions
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/bio.h>
70 \&
71 \& BIO *BIO_new_ex(OSSL_LIB_CTX *libctx, const BIO_METHOD *type);
72 \& BIO *BIO_new(const BIO_METHOD *type);
73 \& int BIO_up_ref(BIO *a);
74 \& int BIO_free(BIO *a);
75 \& void BIO_vfree(BIO *a);
76 \& void BIO_free_all(BIO *a);
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 The \fBBIO_new_ex()\fR function returns a new BIO using method \fBtype\fR associated with
81 the library context \fIlibctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)). The library context may be
82 NULL to indicate the default library context. \fItype\fR \fBMUST NOT\fR be NULL.
83 .PP
84 The \fBBIO_new()\fR is the same as \fBBIO_new_ex()\fR except the default library context is
85 always used.
86 .PP
87 \&\fBBIO_up_ref()\fR increments the reference count associated with the BIO object.
88 .PP
89 \&\fBBIO_free()\fR frees up a single BIO, \fBBIO_vfree()\fR also frees up a single BIO
90 but it does not return a value.
91 If \fBa\fR is NULL nothing is done.
92 Calling \fBBIO_free()\fR may also have some effect
93 on the underlying I/O structure, for example it may close the file being
94 referred to under certain circumstances. For more details see the individual
95 BIO_METHOD descriptions.
96 .PP
97 \&\fBBIO_free_all()\fR frees up an entire BIO chain, it does not halt if an error
98 occurs freeing up an individual BIO in the chain.
99 If \fBa\fR is NULL nothing is done.
100 .SH "RETURN VALUES"
101 .IX Header "RETURN VALUES"
102 \&\fBBIO_new_ex()\fR and \fBBIO_new()\fR return a newly created BIO or NULL if the call fails.
103 .PP
104 \&\fBBIO_up_ref()\fR and \fBBIO_free()\fR return 1 for success and 0 for failure.
105 .PP
106 \&\fBBIO_free_all()\fR and \fBBIO_vfree()\fR do not return values.
107 .SH NOTES
108 .IX Header "NOTES"
109 If \fBBIO_free()\fR is called on a BIO chain it will only free one BIO resulting
110 in a memory leak.
111 .PP
112 Calling \fBBIO_free_all()\fR on a single BIO has the same effect as calling \fBBIO_free()\fR
113 on it other than the discarded return value.
114 .SH HISTORY
115 .IX Header "HISTORY"
116 \&\fBBIO_set()\fR was removed in OpenSSL 1.1.0 as BIO type is now opaque.
117 .PP
118 \&\fBBIO_new_ex()\fR was added in OpenSSL 3.0.
119 .SH EXAMPLES
120 .IX Header "EXAMPLES"
121 Create a memory BIO:
122 .PP
123 .Vb 1
124 \& BIO *mem = BIO_new(BIO_s_mem());
125 .Ve
126 .SH COPYRIGHT
127 .IX Header "COPYRIGHT"
128 Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
129 .PP
130 Licensed under the Apache License 2.0 (the "License"). You may not use
131 this file except in compliance with the License. You can obtain a copy
132 in the file LICENSE in the source distribution or at
133 <https://www.openssl.org/source/license.html>.