1=pod
2
3=head1 NAME
4
5BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback,
6BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback,
7BIO_debug_callback_ex, BIO_callback_fn_ex, BIO_callback_fn
8- BIO callback functions
9
10=head1 SYNOPSIS
11
12 #include <openssl/bio.h>
13
14 typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
15                                    size_t len, int argi,
16                                    long argl, int ret, size_t *processed);
17
18 void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
19 BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
20
21 void BIO_set_callback_arg(BIO *b, char *arg);
22 char *BIO_get_callback_arg(const BIO *b);
23
24 long BIO_debug_callback_ex(BIO *bio, int oper, const char *argp, size_t len,
25                            int argi, long argl, int ret, size_t *processed);
26
27The following functions have been deprecated since OpenSSL 3.0, and can be
28hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
29see L<openssl_user_macros(7)>:
30
31 typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
32                                 long argl, long ret);
33 void BIO_set_callback(BIO *b, BIO_callback_fn cb);
34 BIO_callback_fn BIO_get_callback(const BIO *b);
35 long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
36                         long argl, long ret);
37
38=head1 DESCRIPTION
39
40BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO
41callback. The callback is called during most high-level BIO operations. It can
42be used for debugging purposes to trace operations on a BIO or to modify its
43operation.
44
45BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO
46callback. New code should not use these functions, but they are retained for
47backwards compatibility. Any callback set via BIO_set_callback_ex() will get
48called in preference to any set by BIO_set_callback().
49
50BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
51used to set and retrieve an argument for use in the callback.
52
53BIO_debug_callback_ex() is a standard debugging callback which prints
54out information relating to each BIO operation. If the callback
55argument is set it is interpreted as a BIO to send the information
56to, otherwise stderr is used. The BIO_debug_callback() function is the
57deprecated version of the same callback for use with the old callback
58format BIO_set_callback() function.
59
60BIO_callback_fn_ex is the type of the callback function and BIO_callback_fn
61is the type of the old format callback function. The meaning of each argument
62is described below:
63
64=over 4
65
66=item B<b>
67
68The BIO the callback is attached to is passed in B<b>.
69
70=item B<oper>
71
72B<oper> is set to the operation being performed. For some operations
73the callback is called twice, once before and once after the actual
74operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
75
76=item B<len>
77
78The length of the data requested to be read or written. This is only useful if
79B<oper> is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS.
80
81=item B<argp> B<argi> B<argl>
82
83The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
84the value of B<oper>, that is the operation being performed.
85
86=item B<processed>
87
88B<processed> is a pointer to a location which will be updated with the amount of
89data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE,
90BIO_CB_GETS and BIO_CB_PUTS.
91
92=item B<ret>
93
94B<ret> is the return value that would be returned to the
95application if no callback were present. The actual value returned
96is the return value of the callback itself. In the case of callbacks
97called before the actual BIO operation 1 is placed in B<ret>, if
98the return value is not positive it will be immediately returned to
99the application and the BIO operation will not be performed.
100
101=back
102
103The callback should normally simply return B<ret> when it has
104finished processing, unless it specifically wishes to modify the
105value returned to the application.
106
107=head1 CALLBACK OPERATIONS
108
109In the notes below, B<callback> defers to the actual callback
110function that is called.
111
112=over 4
113
114=item B<BIO_free(b)>
115
116 callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
117
118or
119
120 callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
121
122is called before the free operation.
123
124=item B<BIO_read_ex(b, data, dlen, readbytes)>
125
126 callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, NULL)
127
128or
129
130 callback(b, BIO_CB_READ, data, dlen, 0L, 1L)
131
132is called before the read and
133
134 callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
135             &readbytes)
136
137or
138
139 callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue)
140
141after.
142
143=item B<BIO_write(b, data, dlen, written)>
144
145 callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, NULL)
146
147or
148
149 callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L)
150
151is called before the write and
152
153 callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
154             &written)
155
156or
157
158 callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue)
159
160after.
161
162=item B<BIO_gets(b, buf, size)>
163
164 callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL)
165
166or
167
168 callback(b, BIO_CB_GETS, buf, size, 0L, 1L)
169
170is called before the operation and
171
172 callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue,
173             &readbytes)
174
175or
176
177 callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue)
178
179after.
180
181=item B<BIO_puts(b, buf)>
182
183 callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL);
184
185or
186
187 callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L)
188
189is called before the operation and
190
191 callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, &written)
192
193or
194
195 callback(b, BIO_CB_PUTS|BIO_CB_RETURN, buf, 0, 0L, retvalue)
196
197after.
198
199=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
200
201 callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
202
203or
204
205 callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
206
207is called before the call and
208
209 callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
210
211or
212
213 callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
214
215after.
216
217Note: B<cmd> == B<BIO_CTRL_SET_CALLBACK> is special, because B<parg> is not the
218argument of type B<BIO_info_cb> itself.  In this case B<parg> is a pointer to
219the actual call parameter, see B<BIO_callback_ctrl>.
220
221=back
222
223=head1 RETURN VALUES
224
225BIO_get_callback_ex() and BIO_get_callback() return the callback function
226previously set by a call to BIO_set_callback_ex() and BIO_set_callback()
227respectively.
228
229BIO_get_callback_arg() returns a B<char> pointer to the value previously set
230via a call to BIO_set_callback_arg().
231
232BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
233operations.
234
235=head1 EXAMPLES
236
237The BIO_debug_callback_ex() function is an example, its source is
238in crypto/bio/bio_cb.c
239
240=head1 HISTORY
241
242The BIO_debug_callback_ex() function was added in OpenSSL 3.0.
243
244BIO_set_callback(), BIO_get_callback(), and BIO_debug_callback() were
245deprecated in OpenSSL 3.0. Use the non-deprecated _ex functions instead.
246
247=head1 COPYRIGHT
248
249Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
250
251Licensed under the Apache License 2.0 (the "License").  You may not use
252this file except in compliance with the License.  You can obtain a copy
253in the file LICENSE in the source distribution or at
254L<https://www.openssl.org/source/license.html>.
255
256=cut
257