secure/lib/libcrypto/man/BIO_set_callback.3

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