secure/lib/libcrypto/man/BIO_set_callback.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "BIO_SET_CALLBACK 3"
 132 .TH BIO_SET_CALLBACK 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback, BIO_callback_fn_ex, BIO_callback_fn \&\- BIO callback functions
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/bio.h>
 143 \&
 144 \& typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
 145 \&                                    size_t len, int argi,
 146 \&                                    long argl, int ret, size_t *processed);
 147 \& typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
 148 \&                                 long argl, long ret);
 149 \&
 150 \& void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
 151 \& BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
 152 \&
 153 \& void BIO_set_callback(BIO *b, BIO_callback_fn cb);
 154 \& BIO_callback_fn BIO_get_callback(BIO *b);
 155 \& void BIO_set_callback_arg(BIO *b, char *arg);
 156 \& char *BIO_get_callback_arg(const BIO *b);
 157 \&
 158 \& long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
 159 \&                         long argl, long ret);
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 \&\fIBIO_set_callback_ex()\fR and \fIBIO_get_callback_ex()\fR set and retrieve the \s-1BIO\s0
 164 callback. The callback is called during most high level \s-1BIO\s0 operations. It can
 165 be used for debugging purposes to trace operations on a \s-1BIO\s0 or to modify its
 166 operation.
 167 .PP
 168 \&\fIBIO_set_callback()\fR and \fIBIO_get_callback()\fR set and retrieve the old format \s-1BIO\s0
 169 callback. New code should not use these functions, but they are retained for
 170 backwards compatibility. Any callback set via \fIBIO_set_callback_ex()\fR will get
 171 called in preference to any set by \fIBIO_set_callback()\fR.
 172 .PP
 173 \&\fIBIO_set_callback_arg()\fR and \fIBIO_get_callback_arg()\fR are macros which can be
 174 used to set and retrieve an argument for use in the callback.
 175 .PP
 176 \&\fIBIO_debug_callback()\fR is a standard debugging callback which prints
 177 out information relating to each \s-1BIO\s0 operation. If the callback
 178 argument is set it is interpreted as a \s-1BIO\s0 to send the information
 179 to, otherwise stderr is used.
 180 .PP
 181 \&\fIBIO_callback_fn_ex()\fR is the type of the callback function and \fIBIO_callback_fn()\fR
 182 is the type of the old format callback function. The meaning of each argument
 183 is described below:
 184 .IP "\fBb\fR" 4
 185 .IX Item "b"
 186 The \s-1BIO\s0 the callback is attached to is passed in \fBb\fR.
 187 .IP "\fBoper\fR" 4
 188 .IX Item "oper"
 189 \&\fBoper\fR is set to the operation being performed. For some operations
 190 the callback is called twice, once before and once after the actual
 191 operation, the latter case has \fBoper\fR or'ed with \s-1BIO_CB_RETURN.\s0
 192 .IP "\fBlen\fR" 4
 193 .IX Item "len"
 194 The length of the data requested to be read or written. This is only useful if
 195 \&\fBoper\fR is \s-1BIO_CB_READ, BIO_CB_WRITE\s0 or \s-1BIO_CB_GETS.\s0
 196 .IP "\fBargp\fR \fBargi\fR \fBargl\fR" 4
 197 .IX Item "argp argi argl"
 198 The meaning of the arguments \fBargp\fR, \fBargi\fR and \fBargl\fR depends on
 199 the value of \fBoper\fR, that is the operation being performed.
 200 .IP "\fBprocessed\fR" 4
 201 .IX Item "processed"
 202 \&\fBprocessed\fR is a pointer to a location which will be updated with the amount of
 203 data that was actually read or written. Only used for \s-1BIO_CB_READ, BIO_CB_WRITE,
 204 BIO_CB_GETS\s0 and \s-1BIO_CB_PUTS.\s0
 205 .IP "\fBret\fR" 4
 206 .IX Item "ret"
 207 \&\fBret\fR is the return value that would be returned to the
 208 application if no callback were present. The actual value returned
 209 is the return value of the callback itself. In the case of callbacks
 210 called before the actual \s-1BIO\s0 operation 1 is placed in \fBret\fR, if
 211 the return value is not positive it will be immediately returned to
 212 the application and the \s-1BIO\s0 operation will not be performed.
 213 .PP
 214 The callback should normally simply return \fBret\fR when it has
 215 finished processing, unless it specifically wishes to modify the
 216 value returned to the application.
 217 .SH "CALLBACK OPERATIONS"
 218 .IX Header "CALLBACK OPERATIONS"
 219 In the notes below, \fBcallback\fR defers to the actual callback
 220 function that is called.
 221 .IP "\fBBIO_free(b)\fR" 4
 222 .IX Item "BIO_free(b)"
 223 .Vb 1
 224 \& callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
 225 .Ve
 226 .Sp
 227 or
 228 .Sp
 229 .Vb 1
 230 \& callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
 231 .Ve
 232 .Sp
 233 is called before the free operation.
 234 .IP "\fBBIO_read_ex(b, data, dlen, readbytes)\fR" 4
 235 .IX Item "BIO_read_ex(b, data, dlen, readbytes)"
 236 .Vb 1
 237 \& callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, NULL)
 238 .Ve
 239 .Sp
 240 or
 241 .Sp
 242 .Vb 1
 243 \& callback(b, BIO_CB_READ, data, dlen, 0L, 1L)
 244 .Ve
 245 .Sp
 246 is called before the read and
 247 .Sp
 248 .Vb 2
 249 \& callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
 250 \&             &readbytes)
 251 .Ve
 252 .Sp
 253 or
 254 .Sp
 255 .Vb 1
 256 \& callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue)
 257 .Ve
 258 .Sp
 259 after.
 260 .IP "\fBBIO_write(b, data, dlen, written)\fR" 4
 261 .IX Item "BIO_write(b, data, dlen, written)"
 262 .Vb 1
 263 \& callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, NULL)
 264 .Ve
 265 .Sp
 266 or
 267 .Sp
 268 .Vb 1
 269 \& callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L)
 270 .Ve
 271 .Sp
 272 is called before the write and
 273 .Sp
 274 .Vb 2
 275 \& callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
 276 \&             &written)
 277 .Ve
 278 .Sp
 279 or
 280 .Sp
 281 .Vb 1
 282 \& callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue)
 283 .Ve
 284 .Sp
 285 after.
 286 .IP "\fBBIO_gets(b, buf, size)\fR" 4
 287 .IX Item "BIO_gets(b, buf, size)"
 288 .Vb 1
 289 \& callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL)
 290 .Ve
 291 .Sp
 292 or
 293 .Sp
 294 .Vb 1
 295 \& callback(b, BIO_CB_GETS, buf, size, 0L, 1L)
 296 .Ve
 297 .Sp
 298 is called before the operation and
 299 .Sp
 300 .Vb 2
 301 \& callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue,
 302 \&             &readbytes)
 303 .Ve
 304 .Sp
 305 or
 306 .Sp
 307 .Vb 1
 308 \& callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue)
 309 .Ve
 310 .Sp
 311 after.
 312 .IP "\fBBIO_puts(b, buf)\fR" 4
 313 .IX Item "BIO_puts(b, buf)"
 314 .Vb 1
 315 \& callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL);
 316 .Ve
 317 .Sp
 318 or
 319 .Sp
 320 .Vb 1
 321 \& callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L)
 322 .Ve
 323 .Sp
 324 is called before the operation and
 325 .Sp
 326 .Vb 1
 327 \& callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, &written)
 328 .Ve
 329 .Sp
 330 or
 331 .Sp
 332 .Vb 1
 333 \& callback(b, BIO_CB_PUTS|BIO_CB_RETURN, buf, 0, 0L, retvalue)
 334 .Ve
 335 .Sp
 336 after.
 337 .IP "\fBBIO_ctrl(\s-1BIO\s0 *b, int cmd, long larg, void *parg)\fR" 4
 338 .IX Item "BIO_ctrl(BIO *b, int cmd, long larg, void *parg)"
 339 .Vb 1
 340 \& callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
 341 .Ve
 342 .Sp
 343 or
 344 .Sp
 345 .Vb 1
 346 \& callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
 347 .Ve
 348 .Sp
 349 is called before the call and
 350 .Sp
 351 .Vb 1
 352 \& callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
 353 .Ve
 354 .Sp
 355 or
 356 .Sp
 357 .Vb 1
 358 \& callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
 359 .Ve
 360 .Sp
 361 after.
 362 .Sp
 363 Note: \fBcmd\fR == \fB\s-1BIO_CTRL_SET_CALLBACK\s0\fR is special, because \fBparg\fR is not the
 364 argument of type \fBBIO_info_cb\fR itself.  In this case \fBparg\fR is a pointer to
 365 the actual call parameter, see \fBBIO_callback_ctrl\fR.
 366 .SH "EXAMPLE"
 367 .IX Header "EXAMPLE"
 368 The \fIBIO_debug_callback()\fR function is a good example, its source is
 369 in crypto/bio/bio_cb.c
 370 .SH "RETURN VALUES"
 371 .IX Header "RETURN VALUES"
 372 \&\fIBIO_get_callback_ex()\fR and \fIBIO_get_callback()\fR return the callback function
 373 previously set by a call to \fIBIO_set_callback_ex()\fR and \fIBIO_set_callback()\fR
 374 respectively.
 375 .PP
 376 \&\fIBIO_get_callback_arg()\fR returns a \fBchar\fR pointer to the value previously set
 377 via a call to \fIBIO_set_callback_arg()\fR.
 378 .PP
 379 \&\fIBIO_debug_callback()\fR returns 1 or \fBret\fR if it's called after specific \s-1BIO\s0
 380 operations.
 381 .SH "COPYRIGHT"
 382 .IX Header "COPYRIGHT"
 383 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
 384 .PP
 385 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 386 this file except in compliance with the License.  You can obtain a copy
 387 in the file \s-1LICENSE\s0 in the source distribution or at
 388 <https://www.openssl.org/source/license.html>.