Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_set_callback.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH BIO_set_callback 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
74dab6c2 192BIO_debug_callback \- BIO callback functions
984263bc 193.SH "SYNOPSIS"
74dab6c2 194.PP
984263bc
MD
195.Vb 1
196\& #include <openssl/bio.h>
197.Ve
198.Vb 4
199\& #define BIO_set_callback(b,cb) ((b)->callback=(cb))
200\& #define BIO_get_callback(b) ((b)->callback)
201\& #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg))
202\& #define BIO_get_callback_arg(b) ((b)->cb_arg)
203.Ve
204.Vb 2
205\& long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
206\& long argl,long ret);
207.Ve
208.Vb 2
209\& typedef long callback(BIO *b, int oper, const char *argp,
210\& int argi, long argl, long retvalue);
211.Ve
212.SH "DESCRIPTION"
74dab6c2
JR
213\fIBIO_set_callback()\fR and \fIBIO_get_callback()\fR set and retrieve the BIO callback,
214they are both macros. The callback is called during most high level BIO
984263bc 215operations. It can be used for debugging purposes to trace operations on
74dab6c2 216a BIO or to modify its operation.
984263bc 217.PP
74dab6c2 218\fIBIO_set_callback_arg()\fR and \fIBIO_get_callback_arg()\fR are macros which can be
984263bc
MD
219used to set and retrieve an argument for use in the callback.
220.PP
74dab6c2
JR
221\fIBIO_debug_callback()\fR is a standard debugging callback which prints
222out information relating to each BIO operation. If the callback
223argument is set if is interpreted as a BIO to send the information
984263bc
MD
224to, otherwise stderr is used.
225.PP
74dab6c2 226\fIcallback()\fR is the callback function itself. The meaning of each
984263bc
MD
227argument is described below.
228.PP
74dab6c2 229The BIO the callback is attached to is passed in \fBb\fR.
984263bc 230.PP
74dab6c2 231\fBoper\fR is set to the operation being performed. For some operations
984263bc 232the callback is called twice, once before and once after the actual
74dab6c2 233operation, the latter case has \fBoper\fR or'ed with BIO_CB_RETURN.
984263bc
MD
234.PP
235The meaning of the arguments \fBargp\fR, \fBargi\fR and \fBargl\fR depends on
236the value of \fBoper\fR, that is the operation being performed.
237.PP
74dab6c2 238\fBretvalue\fR is the return value that would be returned to the
984263bc
MD
239application if no callback were present. The actual value returned
240is the return value of the callback itself. In the case of callbacks
74dab6c2 241called before the actual BIO operation 1 is placed in retvalue, if
984263bc 242the return value is not positive it will be immediately returned to
74dab6c2 243the application and the BIO operation will not be performed.
984263bc
MD
244.PP
245The callback should normally simply return \fBretvalue\fR when it has
246finished processing, unless if specifically wishes to modify the
247value returned to the application.
248.SH "CALLBACK OPERATIONS"
74dab6c2
JR
249.Ip "\fBBIO_free(b)\fR" 4
250\fIcallback\fR\|(b, \s-1BIO_CB_FREE\s0, \s-1NULL\s0, 0L, 0L, 1L) is called before the
984263bc
MD
251free operation.
252.Ip "\fBBIO_read(b, out, outl)\fR" 4
74dab6c2
JR
253\fIcallback\fR\|(b, \s-1BIO_CB_READ\s0, out, outl, 0L, 1L) is called before
254the read and \fIcallback\fR\|(b, \s-1BIO_CB_READ\s0|\s-1BIO_CB_RETURN\s0, out, outl, 0L, retvalue)
984263bc
MD
255after.
256.Ip "\fBBIO_write(b, in, inl)\fR" 4
74dab6c2
JR
257\fIcallback\fR\|(b, \s-1BIO_CB_WRITE\s0, in, inl, 0L, 1L) is called before
258the write and \fIcallback\fR\|(b, \s-1BIO_CB_WRITE\s0|\s-1BIO_CB_RETURN\s0, in, inl, 0L, retvalue)
984263bc
MD
259after.
260.Ip "\fBBIO_gets(b, out, outl)\fR" 4
74dab6c2
JR
261\fIcallback\fR\|(b, \s-1BIO_CB_GETS\s0, out, outl, 0L, 1L) is called before
262the operation and \fIcallback\fR\|(b, \s-1BIO_CB_GETS\s0|\s-1BIO_CB_RETURN\s0, out, outl, 0L, retvalue)
984263bc
MD
263after.
264.Ip "\fBBIO_puts(b, in)\fR" 4
74dab6c2
JR
265\fIcallback\fR\|(b, \s-1BIO_CB_WRITE\s0, in, 0, 0L, 1L) is called before
266the operation and \fIcallback\fR\|(b, \s-1BIO_CB_WRITE\s0|\s-1BIO_CB_RETURN\s0, in, 0, 0L, retvalue)
984263bc
MD
267after.
268.Ip "\fBBIO_ctrl(\s-1BIO\s0 *b, int cmd, long larg, void *parg)\fR" 4
74dab6c2
JR
269\fIcallback\fR\|(b,\s-1BIO_CB_CTRL\s0,parg,cmd,larg,1L) is called before the call and
270\fIcallback\fR\|(b,\s-1BIO_CB_CTRL\s0|\s-1BIO_CB_RETURN\s0,parg,cmd, larg,ret) after.
984263bc 271.SH "EXAMPLE"
984263bc
MD
272The \fIBIO_debug_callback()\fR function is a good example, its source is
273in crypto/bio/bio_cb.c
274.SH "SEE ALSO"
74dab6c2
JR
275TBA
276
277.rn }` ''
278.IX Title "BIO_set_callback 3"
279.IX Name "BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
280BIO_debug_callback - BIO callback functions"
281
282.IX Header "NAME"
283
284.IX Header "SYNOPSIS"
285
286.IX Header "DESCRIPTION"
287
288.IX Header "CALLBACK OPERATIONS"
289
290.IX Item "\fBBIO_free(b)\fR"
291
292.IX Item "\fBBIO_read(b, out, outl)\fR"
293
294.IX Item "\fBBIO_write(b, in, inl)\fR"
295
296.IX Item "\fBBIO_gets(b, out, outl)\fR"
297
298.IX Item "\fBBIO_puts(b, in)\fR"
299
300.IX Item "\fBBIO_ctrl(\s-1BIO\s0 *b, int cmd, long larg, void *parg)\fR"
301
302.IX Header "EXAMPLE"
303
984263bc 304.IX Header "SEE ALSO"
74dab6c2 305