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