secure/lib/libcrypto/man/BIO_set_callback.3

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  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 "2007-10-12" "0.9.8f" "OpenSSL"
 133 .SH "NAME"
 134 BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
 135 BIO_debug_callback \- BIO callback functions
 136 .SH "SYNOPSIS"
 137 .IX Header "SYNOPSIS"
 138 .Vb 1
 139 \& #include <openssl/bio.h>
 140 .Ve
 141 .PP
 142 .Vb 4
 143 \& #define BIO_set_callback(b,cb)         ((b)->callback=(cb))
 144 \& #define BIO_get_callback(b)            ((b)->callback)
 145 \& #define BIO_set_callback_arg(b,arg)    ((b)->cb_arg=(char *)(arg))
 146 \& #define BIO_get_callback_arg(b)                ((b)->cb_arg)
 147 .Ve
 148 .PP
 149 .Vb 2
 150 \& long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
 151 \&        long argl,long ret);
 152 .Ve
 153 .PP
 154 .Vb 2
 155 \& typedef long (*callback)(BIO *b, int oper, const char *argp,
 156 \&                        int argi, long argl, long retvalue);
 157 .Ve
 158 .SH "DESCRIPTION"
 159 .IX Header "DESCRIPTION"
 160 \&\fIBIO_set_callback()\fR and \fIBIO_get_callback()\fR set and retrieve the \s-1BIO\s0 callback,
 161 they are both macros. The callback is called during most high level \s-1BIO\s0
 162 operations. It can be used for debugging purposes to trace operations on
 163 a \s-1BIO\s0 or to modify its operation.
 164 .PP
 165 \&\fIBIO_set_callback_arg()\fR and \fIBIO_get_callback_arg()\fR are macros which can be
 166 used to set and retrieve an argument for use in the callback.
 167 .PP
 168 \&\fIBIO_debug_callback()\fR is a standard debugging callback which prints
 169 out information relating to each \s-1BIO\s0 operation. If the callback
 170 argument is set if is interpreted as a \s-1BIO\s0 to send the information
 171 to, otherwise stderr is used.
 172 .PP
 173 \&\fIcallback()\fR is the callback function itself. The meaning of each
 174 argument is described below.
 175 .PP
 176 The \s-1BIO\s0 the callback is attached to is passed in \fBb\fR.
 177 .PP
 178 \&\fBoper\fR is set to the operation being performed. For some operations
 179 the callback is called twice, once before and once after the actual
 180 operation, the latter case has \fBoper\fR or'ed with \s-1BIO_CB_RETURN\s0.
 181 .PP
 182 The meaning of the arguments \fBargp\fR, \fBargi\fR and \fBargl\fR depends on
 183 the value of \fBoper\fR, that is the operation being performed.
 184 .PP
 185 \&\fBretvalue\fR is the return value that would be returned to the
 186 application if no callback were present. The actual value returned
 187 is the return value of the callback itself. In the case of callbacks
 188 called before the actual \s-1BIO\s0 operation 1 is placed in retvalue, if
 189 the return value is not positive it will be immediately returned to
 190 the application and the \s-1BIO\s0 operation will not be performed.
 191 .PP
 192 The callback should normally simply return \fBretvalue\fR when it has
 193 finished processing, unless if specifically wishes to modify the
 194 value returned to the application.
 195 .SH "CALLBACK OPERATIONS"
 196 .IX Header "CALLBACK OPERATIONS"
 197 .IP "\fBBIO_free(b)\fR" 4
 198 .IX Item "BIO_free(b)"
 199 callback(b, \s-1BIO_CB_FREE\s0, \s-1NULL\s0, 0L, 0L, 1L) is called before the
 200 free operation.
 201 .IP "\fBBIO_read(b, out, outl)\fR" 4
 202 .IX Item "BIO_read(b, out, outl)"
 203 callback(b, \s-1BIO_CB_READ\s0, out, outl, 0L, 1L) is called before
 204 the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
 205 after.
 206 .IP "\fBBIO_write(b, in, inl)\fR" 4
 207 .IX Item "BIO_write(b, in, inl)"
 208 callback(b, \s-1BIO_CB_WRITE\s0, in, inl, 0L, 1L) is called before
 209 the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
 210 after.
 211 .IP "\fBBIO_gets(b, out, outl)\fR" 4
 212 .IX Item "BIO_gets(b, out, outl)"
 213 callback(b, \s-1BIO_CB_GETS\s0, out, outl, 0L, 1L) is called before
 214 the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
 215 after.
 216 .IP "\fBBIO_puts(b, in)\fR" 4
 217 .IX Item "BIO_puts(b, in)"
 218 callback(b, \s-1BIO_CB_WRITE\s0, in, 0, 0L, 1L) is called before
 219 the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
 220 after.
 221 .IP "\fBBIO_ctrl(\s-1BIO\s0 *b, int cmd, long larg, void *parg)\fR" 4
 222 .IX Item "BIO_ctrl(BIO *b, int cmd, long larg, void *parg)"
 223 callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
 224 callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
 225 .SH "EXAMPLE"
 226 .IX Header "EXAMPLE"
 227 The \fIBIO_debug_callback()\fR function is a good example, its source is
 228 in crypto/bio/bio_cb.c
 229 .SH "SEE ALSO"
 230 .IX Header "SEE ALSO"
 231 \&\s-1TBA\s0