crypto/external/bsd/openssl/lib/libcrypto/man/BIO_set_callback.3

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