| blob | 2159560596aec9bfb44fdac855336d1a23a1126c |
1 .\" $OpenBSD: BIO_meth_new.3,v 1.5 2018/07/09 09:52:18 tb Exp $
2 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3 .\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
4 .\"
5 .\" This file is a derived work.
6 .\" The changes are covered by the following Copyright and license:
7 .\"
8 .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
9 .\"
10 .\" Permission to use, copy, modify, and distribute this software for any
11 .\" purpose with or without fee is hereby granted, provided that the above
12 .\" copyright notice and this permission notice appear in all copies.
13 .\"
14 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
15 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
16 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
17 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
18 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
19 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
20 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21 .\"
22 .\" The original file was written by Matt Caswell <matt@openssl.org>
23 .\" Copyright (c) 2016 The OpenSSL Project. 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: July 9 2018 $
70 .Dt BIO_METH_NEW 3
71 .Os
72 .Sh NAME
73 .Nm BIO_get_new_index ,
74 .Nm BIO_meth_new ,
75 .Nm BIO_meth_free ,
76 .Nm BIO_meth_get_write ,
77 .Nm BIO_meth_set_write ,
78 .Nm BIO_meth_get_read ,
79 .Nm BIO_meth_set_read ,
80 .Nm BIO_meth_get_puts ,
81 .Nm BIO_meth_set_puts ,
82 .Nm BIO_meth_get_gets ,
83 .Nm BIO_meth_set_gets ,
84 .Nm BIO_meth_get_ctrl ,
85 .Nm BIO_meth_set_ctrl ,
86 .Nm BIO_meth_get_create ,
87 .Nm BIO_meth_set_create ,
88 .Nm BIO_meth_get_destroy ,
89 .Nm BIO_meth_set_destroy ,
90 .Nm BIO_meth_get_callback_ctrl ,
91 .Nm BIO_meth_set_callback_ctrl
92 .Nd manipulate BIO_METHOD structures
93 .Sh SYNOPSIS
94 .In openssl/bio.h
95 .Ft int
96 .Fn BIO_get_new_index void
97 .Ft BIO_METHOD *
98 .Fo BIO_meth_new
99 .Fa "int type"
100 .Fa "const char *name"
101 .Fc
102 .Ft void
103 .Fo BIO_meth_free
104 .Fa "BIO_METHOD *biom"
105 .Fc
106 .Ft int
107 .Fn "(*BIO_meth_get_write(const BIO_METHOD *biom))" "BIO *" "const char *" int
108 .Ft int
109 .Fo BIO_meth_set_write
110 .Fa "BIO_METHOD *biom"
111 .Fa "int (*write)(BIO *, const char *, int)"
112 .Fc
113 .Ft int
114 .Fn "(*BIO_meth_get_read(const BIO_METHOD *biom))" "BIO *" "char *" int
115 .Ft int
116 .Fo BIO_meth_set_read
117 .Fa "BIO_METHOD *biom"
118 .Fa "int (*read)(BIO *, char *, int)"
119 .Fc
120 .Ft int
121 .Fn "(*BIO_meth_get_puts(const BIO_METHOD *biom))" "BIO *" "const char *"
122 .Ft int
123 .Fo BIO_meth_set_puts
124 .Fa "BIO_METHOD *biom"
125 .Fa "int (*puts)(BIO *, const char *)"
126 .Fc
127 .Ft int
128 .Fn "(*BIO_meth_get_gets(const BIO_METHOD *biom))" "BIO *" "char *" int
129 .Ft int
130 .Fo BIO_meth_set_gets
131 .Fa "BIO_METHOD *biom"
132 .Fa "int (*gets)(BIO *, char *, int)"
133 .Fc
134 .Ft long
135 .Fn "(*BIO_meth_get_ctrl(const BIO_METHOD *biom))" "BIO *" int long "void *"
136 .Ft int
137 .Fo BIO_meth_set_ctrl
138 .Fa "BIO_METHOD *biom"
139 .Fa "long (*ctrl)(BIO *, int, long, void *)"
140 .Fc
141 .Ft int
142 .Fn "(*BIO_meth_get_create(const BIO_METHOD *biom))" "BIO *"
143 .Ft int
144 .Fo BIO_meth_set_create
145 .Fa "BIO_METHOD *biom"
146 .Fa "int (*create)(BIO *)"
147 .Fc
148 .Ft int
149 .Fn "(*BIO_meth_get_destroy(const BIO_METHOD *biom))" "BIO *"
150 .Ft int
151 .Fo BIO_meth_set_destroy
152 .Fa "BIO_METHOD *biom"
153 .Fa "int (*destroy)(BIO *)"
154 .Fc
155 .Ft long
156 .Fo "(*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))"
157 .Fa "BIO *"
158 .Fa int
159 .Fa "BIO_info_cb *"
160 .Fc
161 .Ft int
162 .Fo BIO_meth_set_callback_ctrl
163 .Fa "BIO_METHOD *biom"
164 .Fa "long (*callback_ctrl)(BIO *, int, BIO_info_cb *)"
165 .Fc
166 .Sh DESCRIPTION
167 The
168 .Vt BIO_METHOD
169 structure stores function pointers implementing a
170 .Vt BIO
171 type.
172 See
173 .Xr BIO_new 3
174 for more information about
175 .Vt BIO
176 objects.
177 .Pp
178 .Fn BIO_meth_new
179 creates a new
180 .Vt BIO_METHOD
181 structure.
182 It requires a unique integer
183 .Fa type ;
184 use
185 .Fn BIO_get_new_index
186 to get the value for
187 .Fa type .
188 Currently, the user can only create up to 127 different BIO types, and
189 .Fa type
190 is limited to the range 129\(en255.
191 The
192 .Fa name
193 pointer is stored in the structure and will not be freed by
194 .Fn BIO_meth_free .
195 .Pp
196 The standard BIO types are listed in
197 .In openssl/bio.h .
198 Some examples include
199 .Dv BIO_TYPE_BUFFER
200 and
201 .Dv BIO_TYPE_CIPHER .
202 The
203 .Fa type
204 of filter BIOs should have the
205 .Dv BIO_TYPE_FILTER
206 bit set.
207 Source/sink BIOs should have the
208 .Dv BIO_TYPE_SOURCE_SINK
209 bit set.
210 File descriptor based BIOs (e.g. socket, fd, connect, accept etc.\&)
211 should additionally have the
212 .Dv BIO_TYPE_DESCRIPTOR
213 bit set.
214 See
215 .Xr BIO_find_type 3
216 for more information.
217 .Pp
218 .Fn BIO_meth_free
219 is an alias for
220 .Xr free 3 .
221 .Pp
222 .Fn BIO_meth_get_write ,
223 .Fn BIO_meth_set_write ,
224 .Fn BIO_meth_get_read ,
225 and
226 .Fn BIO_meth_set_read
227 get and set the functions
228 .Fa write
229 and
230 .Fa read
231 used for writing and reading arbitrary length data to and from the
232 .Vt BIO .
233 These functions are called from
234 .Xr BIO_write 3
235 and
236 .Xr BIO_read 3 ,
237 respectively.
238 The parameters and return values of
239 .Fa write
240 and
241 .Fa read
242 have the same meaning as for
243 .Xr BIO_write 3
244 and
245 .Xr BIO_read 3 .
246 .Pp
247 .Fn BIO_meth_get_puts
248 and
249 .Fn BIO_meth_set_puts
250 get and set the function
251 .Fa puts
252 used for writing a NUL-terminated string to the
253 .Vt BIO .
254 This function is called from
255 .Xr BIO_puts 3 .
256 The parameters and the return value of
257 .Fa puts
258 have the same meaning as for
259 .Xr BIO_puts 3 .
260 .Pp
261 .Fn BIO_meth_get_gets
262 and
263 .Fn BIO_meth_set_gets
264 get and set the function
265 .Fa gets
266 used for reading a line of data from the
267 .Vt BIO .
268 This function is called from
269 .Xr BIO_gets 3 .
270 The parameters and the return value of
271 .Fa gets
272 have the same meaning as for
273 .Xr BIO_gets 3 .
274 .Pp
275 .Fn BIO_meth_get_ctrl
276 and
277 .Fn BIO_meth_set_ctrl
278 get and set the function
279 .Fa ctrl
280 used for processing control messages in the
281 .Vt BIO .
282 This function is called from
283 .Xr BIO_ctrl 3 .
284 The parameters and return value of
285 .Fa ctrl
286 have the same meaning as for
287 .Xr BIO_ctrl 3 .
288 .Pp
289 .Fn BIO_meth_get_create
290 and
291 .Fn BIO_meth_set_create
292 get and set a function
293 .Fa create
294 used while initializing a new instance of the
295 .Vt BIO .
296 This function is called from
297 .Xr BIO_new 3 .
298 The
299 .Xr BIO_new 3
300 function allocates the memory for the new
301 .Vt BIO ,
302 and a pointer to this newly allocated structure is passed
303 as the parameter to
304 .Fa create .
305 .Pp
306 .Fn BIO_meth_get_destroy
307 and
308 .Fn BIO_meth_set_destroy
309 get and set a function
310 .Fa destroy
311 used while destroying an instance of a
312 .Vt BIO .
313 This function is called from
314 .Xr BIO_free 3 .
315 A pointer to the
316 .Vt BIO
317 to be destroyed is passed as the parameter.
318 The
319 .Fa destroy
320 function is intended to perform clean-up specific to the
321 .Vt BIO
322 .Fa type .
323 The memory for the
324 .Vt BIO
325 itself must not be freed by this function.
326 .Pp
327 .Fn BIO_meth_get_callback_ctrl
328 and
329 .Fn BIO_meth_set_callback_ctrl
330 get and set the function
331 .Fa callback_ctrl
332 used for processing callback control messages in the
333 .Vt BIO .
334 This function is called from
335 .Xr BIO_callback_ctrl 3 .
336 The parameters and return value of
337 .Fa callback_ctrl
338 have the same meaning as for
339 .Xr BIO_callback_ctrl 3 .
340 .Sh RETURN VALUES
341 .Fn BIO_get_new_index
342 returns the new BIO type value or \-1 if an error occurs.
343 .Pp
344 .Fn BIO_meth_new
345 returns the new
346 .Vt BIO_METHOD
347 structure or
348 .Dv NULL
349 if an error occurs.
350 .Pp
351 The
352 .Fn BIO_meth_set_*
353 functions return 1 on success or 0 on error.
354 Currently, they cannot fail.
355 .Pp
356 The
357 .Fn BIO_meth_get_*
358 functions return function pointers.
359 .Sh SEE ALSO
360 .Xr BIO_ctrl 3 ,
361 .Xr BIO_find_type 3 ,
362 .Xr BIO_new 3 ,
363 .Xr BIO_read 3
364 .Sh HISTORY
365 These functions first appeared in OpenSSL 1.1.0
366 and have been available since
367 .Ox 6.3 .