secure/lib/libcrypto/man/BIO_set_callback.3

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