BIO_debug_callback_ex(3ossl)

1BIO_SET_CALLBACK(3ossl)             OpenSSL            BIO_SET_CALLBACK(3ossl)
2
3
4

NAME

6       BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback,
7       BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
8       BIO_debug_callback, BIO_debug_callback_ex, BIO_callback_fn_ex,
9       BIO_callback_fn - BIO callback functions
10

SYNOPSIS

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
27       The following functions have been deprecated since OpenSSL 3.0, and can
28       be hidden entirely by defining OPENSSL_API_COMPAT with a suitable
29       version value, see 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

DESCRIPTION

39       BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the
40       BIO callback. The callback is called during most high-level BIO
41       operations. It can be used for debugging purposes to trace operations
42       on a BIO or to modify its operation.
43
44       BIO_set_callback() and BIO_get_callback() set and retrieve the old
45       format BIO callback. New code should not use these functions, but they
46       are retained for backwards compatibility. Any callback set via
47       BIO_set_callback_ex() will get called in preference to any set by
48       BIO_set_callback().
49
50       BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can
51       be used to set and retrieve an argument for use in the callback.
52
53       BIO_debug_callback_ex() is a standard debugging callback which prints
54       out information relating to each BIO operation. If the callback
55       argument is set it is interpreted as a BIO to send the information to,
56       otherwise stderr is used. The BIO_debug_callback() function is the
57       deprecated version of the same callback for use with the old callback
58       format BIO_set_callback() function.
59
60       BIO_callback_fn_ex is the type of the callback function and
61       BIO_callback_fn is the type of the old format callback function. The
62       meaning of each argument is described below:
63
64       b   The BIO the callback is attached to is passed in b.
65
66       oper
67           oper is set to the operation being performed. For some operations
68           the callback is called twice, once before and once after the actual
69           operation, the latter case has oper or'ed with BIO_CB_RETURN.
70
71       len The length of the data requested to be read or written. This is
72           only useful if oper is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS.
73
74       argp argi argl
75           The meaning of the arguments argp, argi and argl depends on the
76           value of oper, that is the operation being performed.
77
78       processed
79           processed is a pointer to a location which will be updated with the
80           amount of data that was actually read or written. Only used for
81           BIO_CB_READ, BIO_CB_WRITE, BIO_CB_GETS and BIO_CB_PUTS.
82
83       ret ret is the return value that would be returned to the application
84           if no callback were present. The actual value returned is the
85           return value of the callback itself. In the case of callbacks
86           called before the actual BIO operation 1 is placed in ret, if the
87           return value is not positive it will be immediately returned to the
88           application and the BIO operation will not be performed.
89
90       The callback should normally simply return ret when it has finished
91       processing, unless it specifically wishes to modify the value returned
92       to the application.
93

CALLBACK OPERATIONS

95       In the notes below, callback defers to the actual callback function
96       that is called.
97
98       BIO_free(b)
99            callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
100
101           or
102
103            callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
104
105           is called before the free operation.
106
107       BIO_read_ex(b, data, dlen, readbytes)
108            callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, NULL)
109
110           or
111
112            callback(b, BIO_CB_READ, data, dlen, 0L, 1L)
113
114           is called before the read and
115
116            callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
117                        &readbytes)
118
119           or
120
121            callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue)
122
123           after.
124
125       BIO_write(b, data, dlen, written)
126            callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, NULL)
127
128           or
129
130            callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L)
131
132           is called before the write and
133
134            callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
135                        &written)
136
137           or
138
139            callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue)
140
141           after.
142
143       BIO_gets(b, buf, size)
144            callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL)
145
146           or
147
148            callback(b, BIO_CB_GETS, buf, size, 0L, 1L)
149
150           is called before the operation and
151
152            callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue,
153                        &readbytes)
154
155           or
156
157            callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue)
158
159           after.
160
161       BIO_puts(b, buf)
162            callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL);
163
164           or
165
166            callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L)
167
168           is called before the operation and
169
170            callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, &written)
171
172           or
173
174            callback(b, BIO_CB_PUTS|BIO_CB_RETURN, buf, 0, 0L, retvalue)
175
176           after.
177
178       BIO_ctrl(BIO *b, int cmd, long larg, void *parg)
179            callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
180
181           or
182
183            callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
184
185           is called before the call and
186
187            callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
188
189           or
190
191            callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
192
193           after.
194
195           Note: cmd == BIO_CTRL_SET_CALLBACK is special, because parg is not
196           the argument of type BIO_info_cb itself.  In this case parg is a
197           pointer to the actual call parameter, see BIO_callback_ctrl.
198

RETURN VALUES

200       BIO_get_callback_ex() and BIO_get_callback() return the callback
201       function previously set by a call to BIO_set_callback_ex() and
202       BIO_set_callback() respectively.
203
204       BIO_get_callback_arg() returns a char pointer to the value previously
205       set via a call to BIO_set_callback_arg().
206
207       BIO_debug_callback() returns 1 or ret if it's called after specific BIO
208       operations.
209

EXAMPLES

211       The BIO_debug_callback_ex() function is an example, its source is in
212       crypto/bio/bio_cb.c
213

HISTORY

215       The BIO_debug_callback_ex() function was added in OpenSSL 3.0.
216
217       BIO_set_callback(), BIO_get_callback(), and BIO_debug_callback() were
218       deprecated in OpenSSL 3.0. Use the non-deprecated _ex functions
219       instead.
220

COPYRIGHT

222       Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
223
224       Licensed under the Apache License 2.0 (the "License").  You may not use
225       this file except in compliance with the License.  You can obtain a copy
226       in the file LICENSE in the source distribution or at
227       <https://www.openssl.org/source/license.html>.
228
229
230
2313.1.1                             2023-08-31           BIO_SET_CALLBACK(3ossl)