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 167The 168.Vt BIO_METHOD 169structure stores function pointers implementing a 170.Vt BIO 171type. 172See 173.Xr BIO_new 3 174for more information about 175.Vt BIO 176objects. 177.Pp 178.Fn BIO_meth_new 179creates a new 180.Vt BIO_METHOD 181structure. 182It requires a unique integer 183.Fa type ; 184use 185.Fn BIO_get_new_index 186to get the value for 187.Fa type . 188Currently, the user can only create up to 127 different BIO types, and 189.Fa type 190is limited to the range 129\(en255. 191The 192.Fa name 193pointer is stored in the structure and will not be freed by 194.Fn BIO_meth_free . 195.Pp 196The standard BIO types are listed in 197.In openssl/bio.h . 198Some examples include 199.Dv BIO_TYPE_BUFFER 200and 201.Dv BIO_TYPE_CIPHER . 202The 203.Fa type 204of filter BIOs should have the 205.Dv BIO_TYPE_FILTER 206bit set. 207Source/sink BIOs should have the 208.Dv BIO_TYPE_SOURCE_SINK 209bit set. 210File descriptor based BIOs (e.g. socket, fd, connect, accept etc.\&) 211should additionally have the 212.Dv BIO_TYPE_DESCRIPTOR 213bit set. 214See 215.Xr BIO_find_type 3 216for more information. 217.Pp 218.Fn BIO_meth_free 219is 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 , 225and 226.Fn BIO_meth_set_read 227get and set the functions 228.Fa write 229and 230.Fa read 231used for writing and reading arbitrary length data to and from the 232.Vt BIO . 233These functions are called from 234.Xr BIO_write 3 235and 236.Xr BIO_read 3 , 237respectively. 238The parameters and return values of 239.Fa write 240and 241.Fa read 242have the same meaning as for 243.Xr BIO_write 3 244and 245.Xr BIO_read 3 . 246.Pp 247.Fn BIO_meth_get_puts 248and 249.Fn BIO_meth_set_puts 250get and set the function 251.Fa puts 252used for writing a NUL-terminated string to the 253.Vt BIO . 254This function is called from 255.Xr BIO_puts 3 . 256The parameters and the return value of 257.Fa puts 258have the same meaning as for 259.Xr BIO_puts 3 . 260.Pp 261.Fn BIO_meth_get_gets 262and 263.Fn BIO_meth_set_gets 264get and set the function 265.Fa gets 266used for reading a line of data from the 267.Vt BIO . 268This function is called from 269.Xr BIO_gets 3 . 270The parameters and the return value of 271.Fa gets 272have the same meaning as for 273.Xr BIO_gets 3 . 274.Pp 275.Fn BIO_meth_get_ctrl 276and 277.Fn BIO_meth_set_ctrl 278get and set the function 279.Fa ctrl 280used for processing control messages in the 281.Vt BIO . 282This function is called from 283.Xr BIO_ctrl 3 . 284The parameters and return value of 285.Fa ctrl 286have the same meaning as for 287.Xr BIO_ctrl 3 . 288.Pp 289.Fn BIO_meth_get_create 290and 291.Fn BIO_meth_set_create 292get and set a function 293.Fa create 294used while initializing a new instance of the 295.Vt BIO . 296This function is called from 297.Xr BIO_new 3 . 298The 299.Xr BIO_new 3 300function allocates the memory for the new 301.Vt BIO , 302and a pointer to this newly allocated structure is passed 303as the parameter to 304.Fa create . 305.Pp 306.Fn BIO_meth_get_destroy 307and 308.Fn BIO_meth_set_destroy 309get and set a function 310.Fa destroy 311used while destroying an instance of a 312.Vt BIO . 313This function is called from 314.Xr BIO_free 3 . 315A pointer to the 316.Vt BIO 317to be destroyed is passed as the parameter. 318The 319.Fa destroy 320function is intended to perform clean-up specific to the 321.Vt BIO 322.Fa type . 323The memory for the 324.Vt BIO 325itself must not be freed by this function. 326.Pp 327.Fn BIO_meth_get_callback_ctrl 328and 329.Fn BIO_meth_set_callback_ctrl 330get and set the function 331.Fa callback_ctrl 332used for processing callback control messages in the 333.Vt BIO . 334This function is called from 335.Xr BIO_callback_ctrl 3 . 336The parameters and return value of 337.Fa callback_ctrl 338have the same meaning as for 339.Xr BIO_callback_ctrl 3 . 340.Sh RETURN VALUES 341.Fn BIO_get_new_index 342returns the new BIO type value or \-1 if an error occurs. 343.Pp 344.Fn BIO_meth_new 345returns the new 346.Vt BIO_METHOD 347structure or 348.Dv NULL 349if an error occurs. 350.Pp 351The 352.Fn BIO_meth_set_* 353functions return 1 on success or 0 on error. 354Currently, they cannot fail. 355.Pp 356The 357.Fn BIO_meth_get_* 358functions 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 365These functions first appeared in OpenSSL 1.1.0 366and have been available since 367.Ox 6.3 . 368