1 =pod 2 3 =head1 NAME 4 5 BIO_get_new_index, 6 BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex, 7 BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write, 8 BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, 9 BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, 10 BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create, 11 BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl, 12 BIO_meth_set_callback_ctrl, BIO_meth_set_sendmmsg, BIO_meth_get_sendmmsg, 13 BIO_meth_set_recvmmsg, BIO_meth_get_recvmmsg - Routines to build up BIO methods 14 15 =head1 SYNOPSIS 16 17 #include <openssl/bio.h> 18 19 int BIO_get_new_index(void); 20 21 BIO_METHOD *BIO_meth_new(int type, const char *name); 22 23 void BIO_meth_free(BIO_METHOD *biom); 24 25 int BIO_meth_set_write_ex(BIO_METHOD *biom, 26 int (*bwrite)(BIO *, const char *, size_t, size_t *)); 27 int BIO_meth_set_write(BIO_METHOD *biom, 28 int (*write)(BIO *, const char *, int)); 29 30 int BIO_meth_set_read_ex(BIO_METHOD *biom, 31 int (*bread)(BIO *, char *, size_t, size_t *)); 32 int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int)); 33 34 int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *)); 35 int BIO_meth_set_gets(BIO_METHOD *biom, 36 int (*gets)(BIO *, char *, int)); 37 38 int BIO_meth_set_ctrl(BIO_METHOD *biom, 39 long (*ctrl)(BIO *, int, long, void *)); 40 41 int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *)); 42 int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *)); 43 44 int BIO_meth_set_callback_ctrl(BIO_METHOD *biom, 45 long (*callback_ctrl)(BIO *, int, BIO_info_cb *)); 46 47 int BIO_meth_set_sendmmsg(BIO_METHOD *biom, 48 ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t, 49 size_t, uint64_t)); 50 int BIO_meth_set_recvmmsg(BIO_METHOD *biom, 51 ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t, 52 size_t, uint64_t)); 53 54 The following functions have been deprecated since OpenSSL 3.5: 55 56 int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t, 57 size_t *); 58 int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int); 59 60 int (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *); 61 int (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int); 62 63 int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *); 64 int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int); 65 66 long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *); 67 68 int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *); 69 int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *); 70 71 long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *); 72 73 ossl_ssize_t (*BIO_meth_get_sendmmsg(const BIO_METHOD *biom))(BIO *, 74 BIO_MSG *, 75 size_t, 76 size_t, 77 uint64_t); 78 ossl_ssize_t (*BIO_meth_get_recvmmsg(const BIO_METHOD *biom))(BIO *, 79 BIO_MSG *, 80 size_t, 81 size_t, 82 uint64_t); 83 84 =head1 DESCRIPTION 85 86 The B<BIO_METHOD> type is a structure used for the implementation of new BIO 87 types. It provides a set of functions used by OpenSSL for the implementation 88 of the various BIO capabilities. See the L<bio(7)> page for more information. 89 90 BIO_meth_new() creates a new B<BIO_METHOD> structure that contains a type 91 identifier I<type> and a string that represents its B<name>. 92 B<type> can be set to either B<BIO_TYPE_NONE> or via BIO_get_new_index() if 93 a unique type is required for searching (See L<BIO_find_type(3)>) 94 95 Note that BIO_get_new_index() can only be used 127 times before it returns an 96 error. 97 98 The set of 99 standard OpenSSL provided BIO types is provided in F<< <openssl/bio.h> >>. 100 Some examples include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs 101 should have a type which have the "filter" bit set (B<BIO_TYPE_FILTER>). 102 Source/sink BIOs should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). 103 File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should 104 additionally have the "descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the 105 L<BIO_find_type(3)> page for more information. 106 107 BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory 108 associated with it. If the argument is NULL, nothing is done. 109 110 BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function 111 used for writing arbitrary length data to the BIO respectively. This function 112 will be called in response to the application calling BIO_write_ex() or 113 BIO_write(). The parameters for the function have the same meaning as for 114 BIO_write_ex(). Older code may call BIO_meth_get_write() and 115 BIO_meth_set_write() instead. Applications should not call both 116 BIO_meth_set_write_ex() and BIO_meth_set_write() or call BIO_meth_get_write() 117 when the function was set with BIO_meth_set_write_ex(). 118 119 BIO_meth_get_read_ex() and BIO_meth_set_read_ex() get and set the function used 120 for reading arbitrary length data from the BIO respectively. This function will 121 be called in response to the application calling BIO_read_ex() or BIO_read(). 122 The parameters for the function have the same meaning as for BIO_read_ex(). 123 Older code may call BIO_meth_get_read() and BIO_meth_set_read() instead. 124 Applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read() 125 or call BIO_meth_get_read() when the function was set with 126 BIO_meth_set_read_ex(). 127 128 BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for 129 writing a NULL terminated string to the BIO respectively. This function will be 130 called in response to the application calling BIO_puts(). The parameters for 131 the function have the same meaning as for BIO_puts(). 132 133 BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically 134 used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)> 135 page for more information). This function will be called in response to the 136 application calling BIO_gets(). The parameters for the function have the same 137 meaning as for BIO_gets(). 138 139 BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for 140 processing ctrl messages in the BIO respectively. See the L<BIO_ctrl(3)> page for 141 more information. This function will be called in response to the application 142 calling BIO_ctrl(). The parameters for the function have the same meaning as for 143 BIO_ctrl(). 144 145 BIO_meth_get_create() and BIO_meth_set_create() get and set the function used 146 for creating a new instance of the BIO respectively. This function will be 147 called in response to the application calling BIO_new() and passing 148 in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the 149 memory for the new BIO, and a pointer to this newly allocated structure will 150 be passed as a parameter to the function. If a create function is set, 151 BIO_new() will not mark the BIO as initialised on allocation. 152 L<BIO_set_init(3)> must then be called either by the create function, or later, 153 by a BIO ctrl function, once BIO initialisation is complete. 154 155 BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used 156 for destroying an instance of a BIO respectively. This function will be 157 called in response to the application calling BIO_free(). A pointer to the BIO 158 to be destroyed is passed as a parameter. The destroy function should be used 159 for BIO specific clean up. The memory for the BIO itself should not be freed by 160 this function. 161 162 BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the 163 function used for processing callback ctrl messages in the BIO respectively. See 164 the L<BIO_callback_ctrl(3)> page for more information. This function will be called 165 in response to the application calling BIO_callback_ctrl(). The parameters for 166 the function have the same meaning as for BIO_callback_ctrl(). 167 168 BIO_meth_get_sendmmsg(), BIO_meth_set_sendmmsg(), BIO_meth_get_recvmmsg() and 169 BIO_meth_set_recvmmsg() get and set the functions used for handling 170 BIO_sendmmsg() and BIO_recvmmsg() calls respectively. See L<BIO_sendmmsg(3)> for 171 more information. 172 173 =head1 RETURN VALUES 174 175 BIO_get_new_index() returns the new BIO type value or -1 if an error occurred. 176 177 BIO_meth_new(int type, const char *name) returns a valid B<BIO_METHOD> or NULL 178 if an error occurred. 179 180 The B<BIO_meth_set> functions return 1 on success or 0 on error. 181 182 The B<BIO_meth_get> functions return the corresponding function pointers. 183 184 =head1 BUGS 185 186 It is not safe to use C<BIO_meth_get_> functions to reuse the B<BIO> 187 implementation of B<BIO>s implemented by OpenSSL itself with 188 application-implemented B<BIO>s. Instead either the applications ought to 189 implement these functions themselves or they should implement a filter BIO. 190 191 For more details please see L<https://github.com/openssl/openssl/issues/26047>. 192 193 =head1 SEE ALSO 194 195 L<bio(7)>, L<BIO_find_type(3)>, L<BIO_ctrl(3)>, L<BIO_read_ex(3)>, L<BIO_new(3)> 196 197 =head1 HISTORY 198 199 The functions BIO_meth_get_sendmmsg(), BIO_meth_set_sendmmsg(), 200 BIO_meth_get_recvmmsg() and BIO_meth_set_recvmmsg() were added in OpenSSL 3.2. 201 202 All the other functions described here were added in OpenSSL 1.1.0. 203 204 The functions BIO_meth_get_read_ex(), BIO_meth_get_write_ex(), 205 BIO_meth_get_write(), BIO_meth_get_read(), BIO_meth_get_puts(), 206 BIO_meth_get_gets(), BIO_meth_get_ctrl(), BIO_meth_get_create(), 207 BIO_meth_get_destroy(), BIO_meth_get_callback_ctrl(), 208 BIO_meth_get_sendmmsg() and BIO_meth_get_recvmmsg() are deprecated since 209 OpenSSL 3.5. 210 211 =head1 COPYRIGHT 212 213 Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved. 214 215 Licensed under the Apache License 2.0 (the "License"). You may not use 216 this file except in compliance with the License. You can obtain a copy 217 in the file LICENSE in the source distribution or at 218 L<https://www.openssl.org/source/license.html>. 219 220 =cut 221
Indexes created Sun Jun 28 00:24:58 UTC 2026