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