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 callback functions
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/bio.h>
  12
  13  typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
  14                                     size_t len, int argi,
  15                                     long argl, int ret, size_t *processed);
  16  typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
  17                                  long argl, long ret);
  18
  19  void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
  20  BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
  21
  22  void BIO_set_callback(BIO *b, BIO_callack_fn cb);
  23  BIO_callack_fn BIO_get_callback(BIO *b);
  24  void BIO_set_callback_arg(BIO *b, char *arg);
  25  char *BIO_get_callback_arg(const BIO *b);
  26
  27  long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
  28                          long argl, long ret);
  29
  30 =head1 DESCRIPTION
  31
  32 BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO
  33 callback. The callback is called during most high level BIO operations. It can
  34 be used for debugging purposes to trace operations on a BIO or to modify its
  35 operation.
  36
  37 BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO
  38 callback. New code should not use these functions, but they are retained for
  39 backwards compatbility. Any callback set via BIO_set_callback_ex() will get
  40 called in preference to any set by BIO_set_callback().
  41
  42 BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
  43 used to set and retrieve an argument for use in the callback.
  44
  45 BIO_debug_callback() is a standard debugging callback which prints
  46 out information relating to each BIO operation. If the callback
  47 argument is set it is interpreted as a BIO to send the information
  48 to, otherwise stderr is used.
  49
  50 BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn()
  51 is the type of the old format callback function. The meaning of each argument
  52 is described below:
  53
  54 =over
  55
  56 =item B<b>
  57
  58 The BIO the callback is attached to is passed in B<b>.
  59
  60 =item B<oper>
  61
  62 B<oper> is set to the operation being performed. For some operations
  63 the callback is called twice, once before and once after the actual
  64 operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
  65
  66 =item B<len>
  67
  68 The length of the data requested to be read or written. This is only useful if
  69 B<oper> is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS.
  70
  71 =item B<argp> B<argi> B<argl>
  72
  73 The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
  74 the value of B<oper>, that is the operation being performed.
  75
  76 =item B<processed>
  77
  78 B<processed> is a pointer to a location which will be updated with the amount of
  79 data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE,
  80 BIO_CB_GETS and BIO_CB_PUTS.
  81
  82 =item B<ret>
  83
  84 B<ret> is the return value that would be returned to the
  85 application if no callback were present. The actual value returned
  86 is the return value of the callback itself. In the case of callbacks
  87 called before the actual BIO operation 1 is placed in B<ret>, if
  88 the return value is not positive it will be immediately returned to
  89 the application and the BIO operation will not be performed.
  90
  91 =back
  92
  93 The callback should normally simply return B<ret> when it has
  94 finished processing, unless it specifically wishes to modify the
  95 value returned to the application.
  96
  97 =head1 CALLBACK OPERATIONS
  98
  99 In the notes below, B<callback> defers to the actual callback
 100 function that is called.
 101
 102 =over 4
 103
 104 =item B<BIO_free(b)>
 105
 106  callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
 107
 108 or
 109
 110  callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
 111
 112 is called before the free operation.
 113
 114 =item B<BIO_read_ex(b, out, outl, read)>
 115
 116  callback_ex(b, BIO_CB_READ, out, outl, 0, 0L, 1L, read)
 117
 118 or
 119
 120  callback(b, BIO_CB_READ, out, outl, 0L, 1L)
 121
 122 is called before the read and
 123
 124  callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, out, outl, 0, 0L, retvalue, read)
 125
 126 or
 127
 128  callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
 129
 130 after.
 131
 132 =item B<BIO_write(b, in, inl, written)>
 133
 134  callback_ex(b, BIO_CB_WRITE, in, inl, 0, 0L, 1L, written)
 135
 136 or
 137
 138  callback(b, BIO_CB_WRITE, in, inl, 0L, 1L)
 139
 140 is called before the write and
 141
 142  callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, in, inl, 0, 0L, retvalue, written)
 143
 144 or
 145
 146  callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
 147
 148 after.
 149
 150 =item B<BIO_gets(b, out, outl)>
 151
 152  callback_ex(b, BIO_CB_GETS, out, outl, 0, 0L, 1, NULL, NULL)
 153
 154 or
 155
 156  callback(b, BIO_CB_GETS, out, outl, 0L, 1L)
 157
 158 is called before the operation and
 159
 160  callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, out, outl, 0, 0L, retvalue, read)
 161
 162 or
 163
 164  callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
 165
 166 after.
 167
 168 =item B<BIO_puts(b, in)>
 169
 170  callback_ex(b, BIO_CB_PUTS, in, 0, 0, 0L, 1L, NULL);
 171
 172 or
 173
 174  callback(b, BIO_CB_PUTS, in, 0, 0L, 1L)
 175
 176 is called before the operation and
 177
 178  callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, in, 0, 0, 0L, retvalue, written)
 179
 180 or
 181
 182  callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
 183
 184 after.
 185
 186 =item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
 187
 188  callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
 189
 190 or
 191
 192  callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
 193
 194 is called before the call and
 195
 196  callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
 197
 198 or
 199
 200  callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
 201
 202 after.
 203
 204 =back
 205
 206 =head1 EXAMPLE
 207
 208 The BIO_debug_callback() function is a good example, its source is
 209 in crypto/bio/bio_cb.c
 210
 211 =head1 COPYRIGHT
 212
 213 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
 214
 215 Licensed under the OpenSSL license (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