Debian Codegraph @

upstream/debian-unstable/man3/BIO_meth_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_METH_NEW 3SSL"
58 .TH BIO_METH_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_get_new_index,
65 BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex,
66 BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write,
67 BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts,
68 BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl,
69 BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create,
70 BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
71 BIO_meth_set_callback_ctrl, BIO_meth_set_sendmmsg, BIO_meth_get_sendmmsg,
72 BIO_meth_set_recvmmsg, BIO_meth_get_recvmmsg \- Routines to build up BIO methods
73 .SH SYNOPSIS
74 .IX Header "SYNOPSIS"
75 .Vb 1
76 \& #include <openssl/bio.h>
77 \&
78 \& int BIO_get_new_index(void);
79 \&
80 \& BIO_METHOD *BIO_meth_new(int type, const char *name);
81 \&
82 \& void BIO_meth_free(BIO_METHOD *biom);
83 \&
84 \& int BIO_meth_set_write_ex(BIO_METHOD *biom,
85 \& int (*bwrite)(BIO *, const char *, size_t, size_t *));
86 \& int BIO_meth_set_write(BIO_METHOD *biom,
87 \& int (*write)(BIO *, const char *, int));
88 \&
89 \& int BIO_meth_set_read_ex(BIO_METHOD *biom,
90 \& int (*bread)(BIO *, char *, size_t, size_t *));
91 \& int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int));
92 \&
93 \& int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *));
94 \& int BIO_meth_set_gets(BIO_METHOD *biom,
95 \& int (*gets)(BIO *, char *, int));
96 \&
97 \& int BIO_meth_set_ctrl(BIO_METHOD *biom,
98 \& long (*ctrl)(BIO *, int, long, void *));
99 \&
100 \& int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *));
101 \& int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *));
102 \&
103 \& int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
104 \& long (*callback_ctrl)(BIO *, int, BIO_info_cb *));
105 \&
106 \& int BIO_meth_set_sendmmsg(BIO_METHOD *biom,
107 \& ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,
108 \& size_t, uint64_t));
109 \& int BIO_meth_set_recvmmsg(BIO_METHOD *biom,
110 \& ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,
111 \& size_t, uint64_t));
112 .Ve
113 .PP
114 The following functions have been deprecated since OpenSSL 3.5:
115 .PP
116 .Vb 3
117 \& int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t,
118 \& size_t *);
119 \& int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int);
120 \&
121 \& int (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *);
122 \& int (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int);
123 \&
124 \& int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *);
125 \& int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int);
126 \&
127 \& long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *);
128 \&
129 \& int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *);
130 \& int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *);
131 \&
132 \& long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *);
133 \&
134 \& ossl_ssize_t (*BIO_meth_get_sendmmsg(const BIO_METHOD *biom))(BIO *,
135 \& BIO_MSG *,
136 \& size_t,
137 \& size_t,
138 \& uint64_t);
139 \& ossl_ssize_t (*BIO_meth_get_recvmmsg(const BIO_METHOD *biom))(BIO *,
140 \& BIO_MSG *,
141 \& size_t,
142 \& size_t,
143 \& uint64_t);
144 .Ve
145 .SH DESCRIPTION
146 .IX Header "DESCRIPTION"
147 The \fBBIO_METHOD\fR type is a structure used for the implementation of new BIO
148 types. It provides a set of functions used by OpenSSL for the implementation
149 of the various BIO capabilities. See the \fBbio\fR\|(7) page for more information.
150 .PP
151 \&\fBBIO_meth_new()\fR creates a new \fBBIO_METHOD\fR structure that contains a type
152 identifier \fItype\fR and a string that represents its \fBname\fR.
153 \&\fBtype\fR can be set to either \fBBIO_TYPE_NONE\fR or via \fBBIO_get_new_index()\fR if
154 a unique type is required for searching (See \fBBIO_find_type\fR\|(3))
155 .PP
156 Note that \fBBIO_get_new_index()\fR can only be used 127 times before it returns an
157 error.
158 .PP
159 The set of
160 standard OpenSSL provided BIO types is provided in \fI<openssl/bio.h>\fR.
161 Some examples include \fBBIO_TYPE_BUFFER\fR and \fBBIO_TYPE_CIPHER\fR. Filter BIOs
162 should have a type which have the "filter" bit set (\fBBIO_TYPE_FILTER\fR).
163 Source/sink BIOs should have the "source/sink" bit set (\fBBIO_TYPE_SOURCE_SINK\fR).
164 File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should
165 additionally have the "descriptor" bit set (\fBBIO_TYPE_DESCRIPTOR\fR). See the
166 \&\fBBIO_find_type\fR\|(3) page for more information.
167 .PP
168 \&\fBBIO_meth_free()\fR destroys a \fBBIO_METHOD\fR structure and frees up any memory
169 associated with it. If the argument is NULL, nothing is done.
170 .PP
171 \&\fBBIO_meth_get_write_ex()\fR and \fBBIO_meth_set_write_ex()\fR get and set the function
172 used for writing arbitrary length data to the BIO respectively. This function
173 will be called in response to the application calling \fBBIO_write_ex()\fR or
174 \&\fBBIO_write()\fR. The parameters for the function have the same meaning as for
175 \&\fBBIO_write_ex()\fR. Older code may call \fBBIO_meth_get_write()\fR and
176 \&\fBBIO_meth_set_write()\fR instead. Applications should not call both
177 \&\fBBIO_meth_set_write_ex()\fR and \fBBIO_meth_set_write()\fR or call \fBBIO_meth_get_write()\fR
178 when the function was set with \fBBIO_meth_set_write_ex()\fR.
179 .PP
180 \&\fBBIO_meth_get_read_ex()\fR and \fBBIO_meth_set_read_ex()\fR get and set the function used
181 for reading arbitrary length data from the BIO respectively. This function will
182 be called in response to the application calling \fBBIO_read_ex()\fR or \fBBIO_read()\fR.
183 The parameters for the function have the same meaning as for \fBBIO_read_ex()\fR.
184 Older code may call \fBBIO_meth_get_read()\fR and \fBBIO_meth_set_read()\fR instead.
185 Applications should not call both \fBBIO_meth_set_read_ex()\fR and \fBBIO_meth_set_read()\fR
186 or call \fBBIO_meth_get_read()\fR when the function was set with
187 \&\fBBIO_meth_set_read_ex()\fR.
188 .PP
189 \&\fBBIO_meth_get_puts()\fR and \fBBIO_meth_set_puts()\fR get and set the function used for
190 writing a NULL terminated string to the BIO respectively. This function will be
191 called in response to the application calling \fBBIO_puts()\fR. The parameters for
192 the function have the same meaning as for \fBBIO_puts()\fR.
193 .PP
194 \&\fBBIO_meth_get_gets()\fR and \fBBIO_meth_set_gets()\fR get and set the function typically
195 used for reading a line of data from the BIO respectively (see the \fBBIO_gets\fR\|(3)
196 page for more information). This function will be called in response to the
197 application calling \fBBIO_gets()\fR. The parameters for the function have the same
198 meaning as for \fBBIO_gets()\fR.
199 .PP
200 \&\fBBIO_meth_get_ctrl()\fR and \fBBIO_meth_set_ctrl()\fR get and set the function used for
201 processing ctrl messages in the BIO respectively. See the \fBBIO_ctrl\fR\|(3) page for
202 more information. This function will be called in response to the application
203 calling \fBBIO_ctrl()\fR. The parameters for the function have the same meaning as for
204 \&\fBBIO_ctrl()\fR.
205 .PP
206 \&\fBBIO_meth_get_create()\fR and \fBBIO_meth_set_create()\fR get and set the function used
207 for creating a new instance of the BIO respectively. This function will be
208 called in response to the application calling \fBBIO_new()\fR and passing
209 in a pointer to the current BIO_METHOD. The \fBBIO_new()\fR function will allocate the
210 memory for the new BIO, and a pointer to this newly allocated structure will
211 be passed as a parameter to the function. If a create function is set,
212 \&\fBBIO_new()\fR will not mark the BIO as initialised on allocation.
213 \&\fBBIO_set_init\fR\|(3) must then be called either by the create function, or later,
214 by a BIO ctrl function, once BIO initialisation is complete.
215 .PP
216 \&\fBBIO_meth_get_destroy()\fR and \fBBIO_meth_set_destroy()\fR get and set the function used
217 for destroying an instance of a BIO respectively. This function will be
218 called in response to the application calling \fBBIO_free()\fR. A pointer to the BIO
219 to be destroyed is passed as a parameter. The destroy function should be used
220 for BIO specific clean up. The memory for the BIO itself should not be freed by
221 this function.
222 .PP
223 \&\fBBIO_meth_get_callback_ctrl()\fR and \fBBIO_meth_set_callback_ctrl()\fR get and set the
224 function used for processing callback ctrl messages in the BIO respectively. See
225 the \fBBIO_callback_ctrl\fR\|(3) page for more information. This function will be called
226 in response to the application calling \fBBIO_callback_ctrl()\fR. The parameters for
227 the function have the same meaning as for \fBBIO_callback_ctrl()\fR.
228 .PP
229 \&\fBBIO_meth_get_sendmmsg()\fR, \fBBIO_meth_set_sendmmsg()\fR, \fBBIO_meth_get_recvmmsg()\fR and
230 \&\fBBIO_meth_set_recvmmsg()\fR get and set the functions used for handling
231 \&\fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR calls respectively. See \fBBIO_sendmmsg\fR\|(3) for
232 more information.
233 .SH "RETURN VALUES"
234 .IX Header "RETURN VALUES"
235 \&\fBBIO_get_new_index()\fR returns the new BIO type value or \-1 if an error occurred.
236 .PP
237 BIO_meth_new(int type, const char *name) returns a valid \fBBIO_METHOD\fR or NULL
238 if an error occurred.
239 .PP
240 The \fBBIO_meth_set\fR functions return 1 on success or 0 on error.
241 .PP
242 The \fBBIO_meth_get\fR functions return the corresponding function pointers.
243 .SH BUGS
244 .IX Header "BUGS"
245 It is not safe to use \f(CW\*(C`BIO_meth_get_\*(C'\fR functions to reuse the \fBBIO\fR
246 implementation of \fBBIO\fRs implemented by OpenSSL itself with
247 application-implemented \fBBIO\fRs. Instead either the applications ought to
248 implement these functions themselves or they should implement a filter BIO.
249 .PP
250 For more details please see <https://github.com/openssl/openssl/issues/26047>.
251 .SH "SEE ALSO"
252 .IX Header "SEE ALSO"
253 \&\fBbio\fR\|(7), \fBBIO_find_type\fR\|(3), \fBBIO_ctrl\fR\|(3), \fBBIO_read_ex\fR\|(3), \fBBIO_new\fR\|(3)
254 .SH HISTORY
255 .IX Header "HISTORY"
256 The functions \fBBIO_meth_get_sendmmsg()\fR, \fBBIO_meth_set_sendmmsg()\fR,
257 \&\fBBIO_meth_get_recvmmsg()\fR and \fBBIO_meth_set_recvmmsg()\fR were added in OpenSSL 3.2.
258 .PP
259 All the other functions described here were added in OpenSSL 1.1.0.
260 .PP
261 The functions \fBBIO_meth_get_read_ex()\fR, \fBBIO_meth_get_write_ex()\fR,
262 \&\fBBIO_meth_get_write()\fR, \fBBIO_meth_get_read()\fR, \fBBIO_meth_get_puts()\fR,
263 \&\fBBIO_meth_get_gets()\fR, \fBBIO_meth_get_ctrl()\fR, \fBBIO_meth_get_create()\fR,
264 \&\fBBIO_meth_get_destroy()\fR, \fBBIO_meth_get_callback_ctrl()\fR,
265 \&\fBBIO_meth_get_sendmmsg()\fR and \fBBIO_meth_get_recvmmsg()\fR are deprecated since
266 OpenSSL 3.5.
267 .SH COPYRIGHT
268 .IX Header "COPYRIGHT"
269 Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved.
270 .PP
271 Licensed under the Apache License 2.0 (the "License"). You may not use
272 this file except in compliance with the License. You can obtain a copy
273 in the file LICENSE in the source distribution or at
274 <https://www.openssl.org/source/license.html>.