Merge branch 'vendor/PAM_PASSWDQC'
[dragonfly.git] / 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 "2008-09-27" "0.9.8i" "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