1 =pod 2 3 =head1 NAME 4 5 BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback, 6 BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback, 7 BIO_debug_callback_ex, BIO_callback_fn_ex, BIO_callback_fn 8 - BIO callback functions 9 10 =head1 SYNOPSIS 11 12 #include <openssl/bio.h> 13 14 typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp, 15 size_t len, int argi, 16 long argl, int ret, size_t *processed); 17 18 void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback); 19 BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b); 20 21 void BIO_set_callback_arg(BIO *b, char *arg); 22 char *BIO_get_callback_arg(const BIO *b); 23 24 long BIO_debug_callback_ex(BIO *bio, int oper, const char *argp, size_t len, 25 int argi, long argl, int ret, size_t *processed); 26 27 The following functions have been deprecated since OpenSSL 3.0, and can be 28 hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 29 see L<openssl_user_macros(7)>: 30 31 typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi, 32 long argl, long ret); 33 void BIO_set_callback(BIO *b, BIO_callback_fn cb); 34 BIO_callback_fn BIO_get_callback(const BIO *b); 35 long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi, 36 long argl, long ret); 37 38 typedef struct bio_mmsg_cb_args_st { 39 BIO_MSG *msg; 40 size_t stride, num_msg; 41 uint64_t flags; 42 size_t *msgs_processed; 43 } BIO_MMSG_CB_ARGS; 44 45 =head1 DESCRIPTION 46 47 BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO 48 callback. The callback is called during most high-level BIO operations. It can 49 be used for debugging purposes to trace operations on a BIO or to modify its 50 operation. 51 52 BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO 53 callback. New code should not use these functions, but they are retained for 54 backwards compatibility. Any callback set via BIO_set_callback_ex() will get 55 called in preference to any set by BIO_set_callback(). 56 57 BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be 58 used to set and retrieve an argument for use in the callback. 59 60 BIO_debug_callback_ex() is a standard debugging callback which prints 61 out information relating to each BIO operation. If the callback 62 argument is set it is interpreted as a BIO to send the information 63 to, otherwise stderr is used. The BIO_debug_callback() function is the 64 deprecated version of the same callback for use with the old callback 65 format BIO_set_callback() function. 66 67 BIO_callback_fn_ex is the type of the callback function and BIO_callback_fn 68 is the type of the old format callback function. The meaning of each argument 69 is described below: 70 71 =over 4 72 73 =item B<b> 74 75 The BIO the callback is attached to is passed in B<b>. 76 77 =item B<oper> 78 79 B<oper> is set to the operation being performed. For some operations 80 the callback is called twice, once before and once after the actual 81 operation, the latter case has B<oper> or'ed with BIO_CB_RETURN. 82 83 =item B<len> 84 85 The length of the data requested to be read or written. This is only useful if 86 B<oper> is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS. 87 88 =item B<argp> B<argi> B<argl> 89 90 The meaning of the arguments B<argp>, B<argi> and B<argl> depends on 91 the value of B<oper>, that is the operation being performed. 92 93 =item B<processed> 94 95 B<processed> is a pointer to a location which will be updated with the amount of 96 data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE, 97 BIO_CB_GETS and BIO_CB_PUTS. 98 99 =item B<ret> 100 101 B<ret> is the return value that would be returned to the 102 application if no callback were present. The actual value returned 103 is the return value of the callback itself. In the case of callbacks 104 called before the actual BIO operation 1 is placed in B<ret>, if 105 the return value is not positive it will be immediately returned to 106 the application and the BIO operation will not be performed. 107 108 =back 109 110 The callback should normally simply return B<ret> when it has 111 finished processing, unless it specifically wishes to modify the 112 value returned to the application. 113 114 =head1 CALLBACK OPERATIONS 115 116 In the notes below, B<callback> defers to the actual callback 117 function that is called. 118 119 =over 4 120 121 =item B<BIO_free(b)> 122 123 callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL) 124 125 or 126 127 callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) 128 129 is called before the free operation. 130 131 =item B<BIO_read_ex(b, data, dlen, readbytes)> 132 133 callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, NULL) 134 135 or 136 137 callback(b, BIO_CB_READ, data, dlen, 0L, 1L) 138 139 is called before the read and 140 141 callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, 142 &readbytes) 143 144 or 145 146 callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue) 147 148 after. 149 150 =item B<BIO_write(b, data, dlen, written)> 151 152 callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, NULL) 153 154 or 155 156 callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L) 157 158 is called before the write and 159 160 callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, 161 &written) 162 163 or 164 165 callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue) 166 167 after. 168 169 =item B<BIO_gets(b, buf, size)> 170 171 callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL) 172 173 or 174 175 callback(b, BIO_CB_GETS, buf, size, 0L, 1L) 176 177 is called before the operation and 178 179 callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue, 180 &readbytes) 181 182 or 183 184 callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue) 185 186 after. 187 188 =item B<BIO_puts(b, buf)> 189 190 callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL); 191 192 or 193 194 callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L) 195 196 is called before the operation and 197 198 callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, &written) 199 200 or 201 202 callback(b, BIO_CB_PUTS|BIO_CB_RETURN, buf, 0, 0L, retvalue) 203 204 after. 205 206 =item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)> 207 208 callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL) 209 210 or 211 212 callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L) 213 214 is called before the call and 215 216 callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL) 217 218 or 219 220 callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret) 221 222 after. 223 224 Note: B<cmd> == B<BIO_CTRL_SET_CALLBACK> is special, because B<parg> is not the 225 argument of type B<BIO_info_cb> itself. In this case B<parg> is a pointer to 226 the actual call parameter, see B<BIO_callback_ctrl>. 227 228 =item B<BIO_sendmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)> 229 230 callback_ex(b, BIO_CB_SENDMMSG, args, 0, 0, 0, 1, NULL) 231 232 or 233 234 callback(b, BIO_CB_SENDMMSG, args, 0, 0, 1) 235 236 is called before the call and 237 238 callback_ex(b, BIO_CB_SENDMMSG | BIO_CB_RETURN, args, ret, 0, 0, ret, NULL) 239 240 or 241 242 callback(b, BIO_CB_SENDMMSG | BIO_CB_RETURN, args, ret, 0, 0, ret) 243 244 after. 245 246 B<args> is a pointer to a B<BIO_MMSG_CB_ARGS> structure containing the arguments 247 passed to BIO_sendmmsg(). B<ret> is the return value of the BIO_sendmmsg() call. 248 The return value of BIO_sendmmsg() is altered to the value returned by the 249 B<BIO_CB_SENDMMSG | BIO_CB_RETURN> call. 250 251 =item B<BIO_recvmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)> 252 253 See the documentation for BIO_sendmmsg(). BIO_recvmmsg() works identically 254 except that B<BIO_CB_RECVMMSG> is used instead of B<BIO_CB_SENDMMSG>. 255 256 =back 257 258 =head1 RETURN VALUES 259 260 BIO_get_callback_ex() and BIO_get_callback() return the callback function 261 previously set by a call to BIO_set_callback_ex() and BIO_set_callback() 262 respectively. 263 264 BIO_get_callback_arg() returns a B<char> pointer to the value previously set 265 via a call to BIO_set_callback_arg(). 266 267 BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO 268 operations. 269 270 =head1 EXAMPLES 271 272 The BIO_debug_callback_ex() function is an example, its source is 273 in crypto/bio/bio_cb.c 274 275 =head1 HISTORY 276 277 The BIO_debug_callback_ex() function was added in OpenSSL 3.0. 278 279 BIO_set_callback(), BIO_get_callback(), and BIO_debug_callback() were 280 deprecated in OpenSSL 3.0. Use the non-deprecated _ex functions instead. 281 282 =head1 COPYRIGHT 283 284 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. 285 286 Licensed under the Apache License 2.0 (the "License"). You may not use 287 this file except in compliance with the License. You can obtain a copy 288 in the file LICENSE in the source distribution or at 289 L<https://www.openssl.org/source/license.html>. 290 291 =cut 292
Indexes created Sat Jun 27 00:24:51 UTC 2026