155\& typedef long (*callback)(BIO *b, int oper, const char *argp,
156\& int argi, long argl, long retvalue);
157.Ve
158.SH "DESCRIPTION"
159.IX Header "DESCRIPTION"
160\&\fIBIO_set_callback()\fR and \fIBIO_get_callback()\fR set and retrieve the \s-1BIO\s0 callback,
161they are both macros. The callback is called during most high level \s-1BIO\s0
162operations. It can be used for debugging purposes to trace operations on
163a \s-1BIO\s0 or to modify its operation.
164.PP
165\&\fIBIO_set_callback_arg()\fR and \fIBIO_get_callback_arg()\fR are macros which can be
166used to set and retrieve an argument for use in the callback.
167.PP
168\&\fIBIO_debug_callback()\fR is a standard debugging callback which prints
169out information relating to each \s-1BIO\s0 operation. If the callback
170argument is set if is interpreted as a \s-1BIO\s0 to send the information
171to, otherwise stderr is used.
172.PP
173\&\fIcallback()\fR is the callback function itself. The meaning of each
174argument is described below.
175.PP
176The \s-1BIO\s0 the callback is attached to is passed in \fBb\fR.
177.PP
178\&\fBoper\fR is set to the operation being performed. For some operations
179the callback is called twice, once before and once after the actual
180operation, the latter case has \fBoper\fR or'ed with \s-1BIO_CB_RETURN\s0.
181.PP
182The meaning of the arguments \fBargp\fR, \fBargi\fR and \fBargl\fR depends on
183the value of \fBoper\fR, that is the operation being performed.
184.PP
185\&\fBretvalue\fR is the return value that would be returned to the
186application if no callback were present. The actual value returned
187is the return value of the callback itself. In the case of callbacks
188called before the actual \s-1BIO\s0 operation 1 is placed in retvalue, if
189the return value is not positive it will be immediately returned to
190the application and the \s-1BIO\s0 operation will not be performed.
191.PP
192The callback should normally simply return \fBretvalue\fR when it has
193finished processing, unless if specifically wishes to modify the
194value returned to the application.
195.SH "CALLBACK OPERATIONS"
196.IX Header "CALLBACK OPERATIONS"
197.IP "\fBBIO_free(b)\fR" 4
198.IX Item "BIO_free(b)"
199callback(b, \s-1BIO_CB_FREE\s0, \s-1NULL\s0, 0L, 0L, 1L) is called before the
200free operation.
201.IP "\fBBIO_read(b, out, outl)\fR" 4
202.IX Item "BIO_read(b, out, outl)"
203callback(b, \s-1BIO_CB_READ\s0, out, outl, 0L, 1L) is called before
204the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
205after.
206.IP "\fBBIO_write(b, in, inl)\fR" 4
207.IX Item "BIO_write(b, in, inl)"
208callback(b, \s-1BIO_CB_WRITE\s0, in, inl, 0L, 1L) is called before
209the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
210after.
211.IP "\fBBIO_gets(b, out, outl)\fR" 4
212.IX Item "BIO_gets(b, out, outl)"
213callback(b, \s-1BIO_CB_GETS\s0, out, outl, 0L, 1L) is called before
214the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
215after.
216.IP "\fBBIO_puts(b, in)\fR" 4
217.IX Item "BIO_puts(b, in)"
218callback(b, \s-1BIO_CB_WRITE\s0, in, 0, 0L, 1L) is called before
219the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
220after.
221.IP "\fBBIO_ctrl(\s-1BIO\s0 *b, int cmd, long larg, void *parg)\fR" 4
222.IX Item "BIO_ctrl(BIO *b, int cmd, long larg, void *parg)"
223callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
224callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
225.SH "EXAMPLE"
226.IX Header "EXAMPLE"
227The \fIBIO_debug_callback()\fR function is a good example, its source is
228in crypto/bio/bio_cb.c
229.SH "SEE ALSO"
230.IX Header "SEE ALSO"
231\&\s-1TBA\s0
| 148\& typedef long (*callback)(BIO *b, int oper, const char *argp,
149\& int argi, long argl, long retvalue);
150.Ve
151.SH "DESCRIPTION"
152.IX Header "DESCRIPTION"
153\&\fIBIO_set_callback()\fR and \fIBIO_get_callback()\fR set and retrieve the \s-1BIO\s0 callback,
154they are both macros. The callback is called during most high level \s-1BIO\s0
155operations. It can be used for debugging purposes to trace operations on
156a \s-1BIO\s0 or to modify its operation.
157.PP
158\&\fIBIO_set_callback_arg()\fR and \fIBIO_get_callback_arg()\fR are macros which can be
159used to set and retrieve an argument for use in the callback.
160.PP
161\&\fIBIO_debug_callback()\fR is a standard debugging callback which prints
162out information relating to each \s-1BIO\s0 operation. If the callback
163argument is set if is interpreted as a \s-1BIO\s0 to send the information
164to, otherwise stderr is used.
165.PP
166\&\fIcallback()\fR is the callback function itself. The meaning of each
167argument is described below.
168.PP
169The \s-1BIO\s0 the callback is attached to is passed in \fBb\fR.
170.PP
171\&\fBoper\fR is set to the operation being performed. For some operations
172the callback is called twice, once before and once after the actual
173operation, the latter case has \fBoper\fR or'ed with \s-1BIO_CB_RETURN\s0.
174.PP
175The meaning of the arguments \fBargp\fR, \fBargi\fR and \fBargl\fR depends on
176the value of \fBoper\fR, that is the operation being performed.
177.PP
178\&\fBretvalue\fR is the return value that would be returned to the
179application if no callback were present. The actual value returned
180is the return value of the callback itself. In the case of callbacks
181called before the actual \s-1BIO\s0 operation 1 is placed in retvalue, if
182the return value is not positive it will be immediately returned to
183the application and the \s-1BIO\s0 operation will not be performed.
184.PP
185The callback should normally simply return \fBretvalue\fR when it has
186finished processing, unless if specifically wishes to modify the
187value returned to the application.
188.SH "CALLBACK OPERATIONS"
189.IX Header "CALLBACK OPERATIONS"
190.IP "\fBBIO_free(b)\fR" 4
191.IX Item "BIO_free(b)"
192callback(b, \s-1BIO_CB_FREE\s0, \s-1NULL\s0, 0L, 0L, 1L) is called before the
193free operation.
194.IP "\fBBIO_read(b, out, outl)\fR" 4
195.IX Item "BIO_read(b, out, outl)"
196callback(b, \s-1BIO_CB_READ\s0, out, outl, 0L, 1L) is called before
197the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
198after.
199.IP "\fBBIO_write(b, in, inl)\fR" 4
200.IX Item "BIO_write(b, in, inl)"
201callback(b, \s-1BIO_CB_WRITE\s0, in, inl, 0L, 1L) is called before
202the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
203after.
204.IP "\fBBIO_gets(b, out, outl)\fR" 4
205.IX Item "BIO_gets(b, out, outl)"
206callback(b, \s-1BIO_CB_GETS\s0, out, outl, 0L, 1L) is called before
207the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
208after.
209.IP "\fBBIO_puts(b, in)\fR" 4
210.IX Item "BIO_puts(b, in)"
211callback(b, \s-1BIO_CB_WRITE\s0, in, 0, 0L, 1L) is called before
212the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
213after.
214.IP "\fBBIO_ctrl(\s-1BIO\s0 *b, int cmd, long larg, void *parg)\fR" 4
215.IX Item "BIO_ctrl(BIO *b, int cmd, long larg, void *parg)"
216callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
217callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
218.SH "EXAMPLE"
219.IX Header "EXAMPLE"
220The \fIBIO_debug_callback()\fR function is a good example, its source is
221in crypto/bio/bio_cb.c
222.SH "SEE ALSO"
223.IX Header "SEE ALSO"
224\&\s-1TBA\s0
|