BIO_callback_fn(3ssl)

1BIO_SET_CALLBACK(3)                 OpenSSL                BIO_SET_CALLBACK(3)
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_callback_fn_ex, BIO_callback_fn - BIO callback
9       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        typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
18                                        long argl, long ret);
19
20        void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
21        BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
22
23        void BIO_set_callback(BIO *b, BIO_callback_fn cb);
24        BIO_callback_fn BIO_get_callback(BIO *b);
25        void BIO_set_callback_arg(BIO *b, char *arg);
26        char *BIO_get_callback_arg(const BIO *b);
27
28        long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
29                                long argl, long ret);
30

DESCRIPTION

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

CALLBACK OPERATIONS

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

RETURN VALUES

191       BIO_get_callback_ex() and BIO_get_callback() return the callback
192       function previously set by a call to BIO_set_callback_ex() and
193       BIO_set_callback() respectively.
194
195       BIO_get_callback_arg() returns a char pointer to the value previously
196       set via a call to BIO_set_callback_arg().
197
198       BIO_debug_callback() returns 1 or ret if it's called after specific BIO
199       operations.
200

EXAMPLES

202       The BIO_debug_callback() function is a good example, its source is in
203       crypto/bio/bio_cb.c
204

COPYRIGHT

206       Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
207
208       Licensed under the OpenSSL license (the "License").  You may not use
209       this file except in compliance with the License.  You can obtain a copy
210       in the file LICENSE in the source distribution or at
211       <https://www.openssl.org/source/license.html>.
212
213
214
2151.1.1l                            2021-09-15               BIO_SET_CALLBACK(3)