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