secure/lib/libcrypto/man/BIO_set_callback.3

   1 .\" Automatically generated by Pod::Man version 1.15
   2 .\" Wed Feb 19 16:42:46 2003
   3 .\"
   4 .\" Standard preamble:
   5 .\" ======================================================================
   6 .de Sh \" Subsection heading
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp \" Vertical space (when we can't use .PP)
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip \" List item
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb \" Begin verbatim text
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve \" End verbatim text
  30 .ft R
  31
  32 .fi
  33 ..
  34 .\" Set up some character translations and predefined strings.  \*(-- will
  35 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  36 .\" double quote, and \*(R" will give a right double quote.  | will give a
  37 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
  38 .\" to do unbreakable dashes and therefore won't be available.  \*(C` and
  39 .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
  40 .tr \(*W-|\(bv\*(Tr
  41 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  42 .ie n \{\
  43 .    ds -- \(*W-
  44 .    ds PI pi
  45 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  46 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  47 .    ds L" ""
  48 .    ds R" ""
  49 .    ds C` ""
  50 .    ds C' ""
  51 'br\}
  52 .el\{\
  53 .    ds -- \|\(em\|
  54 .    ds PI \(*p
  55 .    ds L" ``
  56 .    ds R" ''
  57 'br\}
  58 .\"
  59 .\" If the F register is turned on, we'll generate index entries on stderr
  60 .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
  61 .\" index entries marked with X<> in POD.  Of course, you'll have to process
  62 .\" the output yourself in some meaningful fashion.
  63 .if \nF \{\
  64 .    de IX
  65 .    tm Index:\\$1\t\\n%\t"\\$2"
  66 ..
  67 .    nr % 0
  68 .    rr F
  69 .\}
  70 .\"
  71 .\" For nroff, turn off justification.  Always turn off hyphenation; it
  72 .\" makes way too many mistakes in technical documents.
  73 .hy 0
  74 .if n .na
  75 .\"
  76 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  77 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  78 .bd B 3
  79 .    \" fudge factors for nroff and troff
  80 .if n \{\
  81 .    ds #H 0
  82 .    ds #V .8m
  83 .    ds #F .3m
  84 .    ds #[ \f1
  85 .    ds #] \fP
  86 .\}
  87 .if t \{\
  88 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  89 .    ds #V .6m
  90 .    ds #F 0
  91 .    ds #[ \&
  92 .    ds #] \&
  93 .\}
  94 .    \" simple accents for nroff and troff
  95 .if n \{\
  96 .    ds ' \&
  97 .    ds ` \&
  98 .    ds ^ \&
  99 .    ds , \&
 100 .    ds ~ ~
 101 .    ds /
 102 .\}
 103 .if t \{\
 104 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 105 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 106 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 107 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 108 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 109 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 110 .\}
 111 .    \" troff and (daisy-wheel) nroff accents
 112 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 113 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 114 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 115 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 116 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 117 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 118 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 119 .ds ae a\h'-(\w'a'u*4/10)'e
 120 .ds Ae A\h'-(\w'A'u*4/10)'E
 121 .    \" corrections for vroff
 122 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 123 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 124 .    \" for low resolution devices (crt and lpr)
 125 .if \n(.H>23 .if \n(.V>19 \
 126 \{\
 127 .    ds : e
 128 .    ds 8 ss
 129 .    ds o a
 130 .    ds d- d\h'-1'\(ga
 131 .    ds D- D\h'-1'\(hy
 132 .    ds th \o'bp'
 133 .    ds Th \o'LP'
 134 .    ds ae ae
 135 .    ds Ae AE
 136 .\}
 137 .rm #[ #] #H #V #F C
 138 .\" ======================================================================
 139 .\"
 140 .IX Title "BIO_set_callback 3"
 141 .TH BIO_set_callback 3 "0.9.7a" "2003-02-19" "OpenSSL"
 142 .UC
 143 .SH "NAME"
 144 BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
 145 BIO_debug_callback \- \s-1BIO\s0 callback functions
 146 .SH "SYNOPSIS"
 147 .IX Header "SYNOPSIS"
 148 .Vb 1
 149 \& #include <openssl/bio.h>
 150 .Ve
 151 .Vb 4
 152 \& #define BIO_set_callback(b,cb)         ((b)->callback=(cb))
 153 \& #define BIO_get_callback(b)            ((b)->callback)
 154 \& #define BIO_set_callback_arg(b,arg)    ((b)->cb_arg=(char *)(arg))
 155 \& #define BIO_get_callback_arg(b)                ((b)->cb_arg)
 156 .Ve
 157 .Vb 2
 158 \& long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
 159 \&        long argl,long ret);
 160 .Ve
 161 .Vb 2
 162 \& typedef long callback(BIO *b, int oper, const char *argp,
 163 \&                        int argi, long argl, long retvalue);
 164 .Ve
 165 .SH "DESCRIPTION"
 166 .IX Header "DESCRIPTION"
 167 \&\fIBIO_set_callback()\fR and \fIBIO_get_callback()\fR set and retrieve the \s-1BIO\s0 callback,
 168 they are both macros. The callback is called during most high level \s-1BIO\s0
 169 operations. It can be used for debugging purposes to trace operations on
 170 a \s-1BIO\s0 or to modify its operation.
 171 .PP
 172 \&\fIBIO_set_callback_arg()\fR and \fIBIO_get_callback_arg()\fR are macros which can be
 173 used to set and retrieve an argument for use in the callback.
 174 .PP
 175 \&\fIBIO_debug_callback()\fR is a standard debugging callback which prints
 176 out information relating to each \s-1BIO\s0 operation. If the callback
 177 argument is set if is interpreted as a \s-1BIO\s0 to send the information
 178 to, otherwise stderr is used.
 179 .PP
 180 \&\fIcallback()\fR is the callback function itself. The meaning of each
 181 argument is described below.
 182 .PP
 183 The \s-1BIO\s0 the callback is attached to is passed in \fBb\fR.
 184 .PP
 185 \&\fBoper\fR is set to the operation being performed. For some operations
 186 the callback is called twice, once before and once after the actual
 187 operation, the latter case has \fBoper\fR or'ed with \s-1BIO_CB_RETURN\s0.
 188 .PP
 189 The meaning of the arguments \fBargp\fR, \fBargi\fR and \fBargl\fR depends on
 190 the value of \fBoper\fR, that is the operation being performed.
 191 .PP
 192 \&\fBretvalue\fR is the return value that would be returned to the
 193 application if no callback were present. The actual value returned
 194 is the return value of the callback itself. In the case of callbacks
 195 called before the actual \s-1BIO\s0 operation 1 is placed in retvalue, if
 196 the return value is not positive it will be immediately returned to
 197 the application and the \s-1BIO\s0 operation will not be performed.
 198 .PP
 199 The callback should normally simply return \fBretvalue\fR when it has
 200 finished processing, unless if specifically wishes to modify the
 201 value returned to the application.
 202 .SH "CALLBACK OPERATIONS"
 203 .IX Header "CALLBACK OPERATIONS"
 204 .Ip "\fB\f(BIBIO_free\fB\|(b)\fR" 4
 205 .IX Item "BIO_free"
 206 callback(b, \s-1BIO_CB_FREE\s0, \s-1NULL\s0, 0L, 0L, 1L) is called before the
 207 free operation.
 208 .Ip "\fBBIO_read(b, out, outl)\fR" 4
 209 .IX Item "BIO_read(b, out, outl)"
 210 callback(b, \s-1BIO_CB_READ\s0, out, outl, 0L, 1L) is called before
 211 the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
 212 after.
 213 .Ip "\fBBIO_write(b, in, inl)\fR" 4
 214 .IX Item "BIO_write(b, in, inl)"
 215 callback(b, \s-1BIO_CB_WRITE\s0, in, inl, 0L, 1L) is called before
 216 the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
 217 after.
 218 .Ip "\fBBIO_gets(b, out, outl)\fR" 4
 219 .IX Item "BIO_gets(b, out, outl)"
 220 callback(b, \s-1BIO_CB_GETS\s0, out, outl, 0L, 1L) is called before
 221 the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
 222 after.
 223 .Ip "\fBBIO_puts(b, in)\fR" 4
 224 .IX Item "BIO_puts(b, in)"
 225 callback(b, \s-1BIO_CB_WRITE\s0, in, 0, 0L, 1L) is called before
 226 the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
 227 after.
 228 .Ip "\fBBIO_ctrl(\s-1BIO\s0 *b, int cmd, long larg, void *parg)\fR" 4
 229 .IX Item "BIO_ctrl(BIO *b, int cmd, long larg, void *parg)"
 230 callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
 231 callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
 232 .SH "EXAMPLE"
 233 .IX Header "EXAMPLE"
 234 The \fIBIO_debug_callback()\fR function is a good example, its source is
 235 in crypto/bio/bio_cb.c
 236 .SH "SEE ALSO"
 237 .IX Header "SEE ALSO"
 238 \&\s-1TBA\s0