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