.\"	$OpenBSD: BIO_set_callback.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
.\"
.Dd $Mdocdate: November 6 2016 $
.Dt BIO_SET_CALLBACK 3
.Os
.Sh NAME
.Nm BIO_set_callback ,
.Nm BIO_get_callback ,
.Nm BIO_set_callback_arg ,
.Nm BIO_get_callback_arg ,
.Nm BIO_debug_callback
.Nd BIO callback functions
.Sh SYNOPSIS
.In openssl/bio.h
.Fd #define BIO_set_callback(b,cb)		((b)->callback=(cb))
.Fd #define BIO_get_callback(b)			((b)->callback)
.Fd #define BIO_set_callback_arg(b,arg)	((b)->cb_arg=(char *)(arg))
.Fd #define BIO_get_callback_arg(b)		((b)->cb_arg)
.Ft long
.Fo BIO_debug_callback
.Fa "BIO *bio"
.Fa "int cmd"
.Fa "const char *argp"
.Fa "int argi"
.Fa "long argl"
.Fa "long ret"
.Fc
.Ft typedef long *
.Fo callback
.Fa "BIO *b"
.Fa "int oper"
.Fa "const char *argp"
.Fa "int argi"
.Fa "long argl"
.Fa "long retvalue"
.Fc
.Sh DESCRIPTION
.Fn BIO_set_callback
and
.Fn BIO_get_callback
set and retrieve the BIO callback, they are both macros.
The callback is called during most high level BIO operations.
It can be used for debugging purposes to trace operations on a BIO
or to modify its operation.
.Pp
.Fn BIO_set_callback_arg
and
.Fn BIO_get_callback_arg
are macros which can be used to set and retrieve an argument
for use in the callback.
.Pp
.Fn BIO_debug_callback
is a standard debugging callback which prints
out information relating to each BIO operation.
If the callback argument is set, it is interpreted as a BIO
to send the information to, otherwise stderr is used.
.Pp
.Fn callback
is the callback function itself.
The meaning of each argument is described below.
.Pp
The BIO the callback is attached to is passed in
.Fa b .
.Pp
.Fa oper
is set to the operation being performed.
For some operations the callback is called twice,
once before and once after the actual operation.
The latter case has
.Fa oper
or'ed with
.Dv BIO_CB_RETURN .
.Pp
The meaning of the arguments
.Fa argp ,
.Fa argi
and
.Fa argl
depends on the value of
.Fa oper ,
that is the operation being performed.
.Pp
.Fa retvalue
is the return value that would be returned to the application
if no callback were present.
The actual value returned is the return value of the callback itself.
In the case of callbacks called before the actual BIO operation,
1 is placed in retvalue.
If the return value is not positive, it will be immediately returned to
the application and the BIO operation will not be performed.
.Pp
The callback should normally simply return
.Fa retvalue
when it has finished processing, unless it specifically wishes
to modify the value returned to the application.
.Ss Callback operations
.Bl -tag -width Ds
.It Fn BIO_free b
.Fn callback b BIO_CB_FREE NULL 0L 0L 1L
is called before the free operation.
.It Fn BIO_read b out outl
.Fn callback b BIO_CB_READ out outl 0L 1L
is called before the read and
.Fn callback b BIO_CB_READ|BIO_CB_RETURN out outl 0L retvalue
after.
.It Fn BIO_write b in inl
.Fn callback b BIO_CB_WRITE in inl 0L 1L
is called before the write and
.Fn callback b BIO_CB_WRITE|BIO_CB_RETURN in inl 0L retvalue
after.
.It Fn BIO_gets b out outl
.Fn callback b BIO_CB_GETS out outl 0L 1L
is called before the operation and
.Fn callback b BIO_CB_GETS|BIO_CB_RETURN out outl 0L retvalue
after.
.It Fn BIO_puts b in
.Fn callback b BIO_CB_WRITE in 0 0L 1L
is called before the operation and
.Fn callback b BIO_CB_WRITE|BIO_CB_RETURN in 0 0L retvalue
after.
.It Fn BIO_ctrl b cmd larg parg
.Fn callback b BIO_CB_CTRL parg cmd larg 1L
is called before the call and
.Fn callback b BIO_CB_CTRL|BIO_CB_RETURN parg cmd larg ret
after.
.El
.Sh EXAMPLES
The
.Fn BIO_debug_callback
function is a good example, its source is in the file
.Pa crypto/bio/bio_cb.c .