1 files changed, 129 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/BIO_set_callback.3 b/src/lib/libcrypto/man/BIO_set_callback.3
new file mode 100644
index 0000000000..39d284890e
--- /dev/null
+++ b/src/lib/libcrypto/man/BIO_set_callback.3
@@ -0,0 +1,129 @@
+.Dd $Mdocdate: February 16 2015 $
+.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 .