doc/man3/BIO_set_callback.pod

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