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