secure/lib/libcrypto/man/BIO_set_callback.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH BIO_set_callback 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
 192 BIO_debug_callback \- BIO callback functions
 193 .SH "SYNOPSIS"
 194 .PP
 195 .Vb 1
 196 \& #include <openssl/bio.h>
 197 .Ve
 198 .Vb 4
 199 \& #define BIO_set_callback(b,cb)         ((b)->callback=(cb))
 200 \& #define BIO_get_callback(b)            ((b)->callback)
 201 \& #define BIO_set_callback_arg(b,arg)    ((b)->cb_arg=(char *)(arg))
 202 \& #define BIO_get_callback_arg(b)                ((b)->cb_arg)
 203 .Ve
 204 .Vb 2
 205 \& long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
 206 \&        long argl,long ret);
 207 .Ve
 208 .Vb 2
 209 \& typedef long callback(BIO *b, int oper, const char *argp,
 210 \&                        int argi, long argl, long retvalue);
 211 .Ve
 212 .SH "DESCRIPTION"
 213 \fIBIO_set_callback()\fR and \fIBIO_get_callback()\fR set and retrieve the BIO callback,
 214 they are both macros. The callback is called during most high level BIO
 215 operations. It can be used for debugging purposes to trace operations on
 216 a BIO or to modify its operation.
 217 .PP
 218 \fIBIO_set_callback_arg()\fR and \fIBIO_get_callback_arg()\fR are macros which can be
 219 used to set and retrieve an argument for use in the callback.
 220 .PP
 221 \fIBIO_debug_callback()\fR is a standard debugging callback which prints
 222 out information relating to each BIO operation. If the callback
 223 argument is set if is interpreted as a BIO to send the information
 224 to, otherwise stderr is used.
 225 .PP
 226 \fIcallback()\fR is the callback function itself. The meaning of each
 227 argument is described below.
 228 .PP
 229 The BIO the callback is attached to is passed in \fBb\fR.
 230 .PP
 231 \fBoper\fR is set to the operation being performed. For some operations
 232 the callback is called twice, once before and once after the actual
 233 operation, the latter case has \fBoper\fR or'ed with BIO_CB_RETURN.
 234 .PP
 235 The meaning of the arguments \fBargp\fR, \fBargi\fR and \fBargl\fR depends on
 236 the value of \fBoper\fR, that is the operation being performed.
 237 .PP
 238 \fBretvalue\fR is the return value that would be returned to the
 239 application if no callback were present. The actual value returned
 240 is the return value of the callback itself. In the case of callbacks
 241 called before the actual BIO operation 1 is placed in retvalue, if
 242 the return value is not positive it will be immediately returned to
 243 the application and the BIO operation will not be performed.
 244 .PP
 245 The callback should normally simply return \fBretvalue\fR when it has
 246 finished processing, unless if specifically wishes to modify the
 247 value returned to the application.
 248 .SH "CALLBACK OPERATIONS"
 249 .Ip "\fBBIO_free(b)\fR" 4
 250 \fIcallback\fR\|(b, \s-1BIO_CB_FREE\s0, \s-1NULL\s0, 0L, 0L, 1L) is called before the
 251 free operation.
 252 .Ip "\fBBIO_read(b, out, outl)\fR" 4
 253 \fIcallback\fR\|(b, \s-1BIO_CB_READ\s0, out, outl, 0L, 1L) is called before
 254 the read and \fIcallback\fR\|(b, \s-1BIO_CB_READ\s0|\s-1BIO_CB_RETURN\s0, out, outl, 0L, retvalue)
 255 after.
 256 .Ip "\fBBIO_write(b, in, inl)\fR" 4
 257 \fIcallback\fR\|(b, \s-1BIO_CB_WRITE\s0, in, inl, 0L, 1L) is called before
 258 the write and \fIcallback\fR\|(b, \s-1BIO_CB_WRITE\s0|\s-1BIO_CB_RETURN\s0, in, inl, 0L, retvalue)
 259 after.
 260 .Ip "\fBBIO_gets(b, out, outl)\fR" 4
 261 \fIcallback\fR\|(b, \s-1BIO_CB_GETS\s0, out, outl, 0L, 1L) is called before
 262 the operation and \fIcallback\fR\|(b, \s-1BIO_CB_GETS\s0|\s-1BIO_CB_RETURN\s0, out, outl, 0L, retvalue)
 263 after.
 264 .Ip "\fBBIO_puts(b, in)\fR" 4
 265 \fIcallback\fR\|(b, \s-1BIO_CB_WRITE\s0, in, 0, 0L, 1L) is called before
 266 the operation and \fIcallback\fR\|(b, \s-1BIO_CB_WRITE\s0|\s-1BIO_CB_RETURN\s0, in, 0, 0L, retvalue)
 267 after.
 268 .Ip "\fBBIO_ctrl(\s-1BIO\s0 *b, int cmd, long larg, void *parg)\fR" 4
 269 \fIcallback\fR\|(b,\s-1BIO_CB_CTRL\s0,parg,cmd,larg,1L) is called before the call and
 270 \fIcallback\fR\|(b,\s-1BIO_CB_CTRL\s0|\s-1BIO_CB_RETURN\s0,parg,cmd, larg,ret) after.
 271 .SH "EXAMPLE"
 272 The \fIBIO_debug_callback()\fR function is a good example, its source is
 273 in crypto/bio/bio_cb.c
 274 .SH "SEE ALSO"
 275 TBA
 276
 277 .rn }` ''
 278 .IX Title "BIO_set_callback 3"
 279 .IX Name "BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
 280 BIO_debug_callback - BIO callback functions"
 281
 282 .IX Header "NAME"
 283
 284 .IX Header "SYNOPSIS"
 285
 286 .IX Header "DESCRIPTION"
 287
 288 .IX Header "CALLBACK OPERATIONS"
 289
 290 .IX Item "\fBBIO_free(b)\fR"
 291
 292 .IX Item "\fBBIO_read(b, out, outl)\fR"
 293
 294 .IX Item "\fBBIO_write(b, in, inl)\fR"
 295
 296 .IX Item "\fBBIO_gets(b, out, outl)\fR"
 297
 298 .IX Item "\fBBIO_puts(b, in)\fR"
 299
 300 .IX Item "\fBBIO_ctrl(\s-1BIO\s0 *b, int cmd, long larg, void *parg)\fR"
 301
 302 .IX Header "EXAMPLE"
 303
 304 .IX Header "SEE ALSO"
 305