1.Dd $Mdocdate: February 16 2015 $ 2.Dt BIO_SET_CALLBACK 3 3.Os 4.Sh NAME 5.Nm BIO_set_callback , 6.Nm BIO_get_callback , 7.Nm BIO_set_callback_arg , 8.Nm BIO_get_callback_arg , 9.Nm BIO_debug_callback 10.Nd BIO callback functions 11.Sh SYNOPSIS 12.In openssl/bio.h 13.Fd #define BIO_set_callback(b,cb) ((b)->callback=(cb)) 14.Fd #define BIO_get_callback(b) ((b)->callback) 15.Fd #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) 16.Fd #define BIO_get_callback_arg(b) ((b)->cb_arg) 17.Ft long 18.Fo BIO_debug_callback 19.Fa "BIO *bio" 20.Fa "int cmd" 21.Fa "const char *argp" 22.Fa "int argi" 23.Fa "long argl" 24.Fa "long ret" 25.Fc 26.Ft typedef long * 27.Fo callback 28.Fa "BIO *b" 29.Fa "int oper" 30.Fa "const char *argp" 31.Fa "int argi" 32.Fa "long argl" 33.Fa "long retvalue" 34.Fc 35.Sh DESCRIPTION 36.Fn BIO_set_callback 37and 38.Fn BIO_get_callback 39set and retrieve the BIO callback, they are both macros. 40The callback is called during most high level BIO operations. 41It can be used for debugging purposes to trace operations on a BIO 42or to modify its operation. 43.Pp 44.Fn BIO_set_callback_arg 45and 46.Fn BIO_get_callback_arg 47are macros which can be used to set and retrieve an argument 48for use in the callback. 49.Pp 50.Fn BIO_debug_callback 51is a standard debugging callback which prints 52out information relating to each BIO operation. 53If the callback argument is set, it is interpreted as a BIO 54to send the information to, otherwise stderr is used. 55.Pp 56.Fn callback 57is the callback function itself. 58The meaning of each argument is described below. 59.Pp 60The BIO the callback is attached to is passed in 61.Fa b . 62.Pp 63.Fa oper 64is set to the operation being performed. 65For some operations the callback is called twice, 66once before and once after the actual operation. 67The latter case has 68.Fa oper 69or'ed with 70.Dv BIO_CB_RETURN . 71.Pp 72The meaning of the arguments 73.Fa argp , 74.Fa argi 75and 76.Fa argl 77depends on the value of 78.Fa oper , 79that is the operation being performed. 80.Pp 81.Fa retvalue 82is the return value that would be returned to the application 83if no callback were present. 84The actual value returned is the return value of the callback itself. 85In the case of callbacks called before the actual BIO operation, 861 is placed in retvalue. 87If the return value is not positive, it will be immediately returned to 88the application and the BIO operation will not be performed. 89.Pp 90The callback should normally simply return 91.Fa retvalue 92when it has finished processing, unless it specifically wishes 93to modify the value returned to the application. 94.Ss Callback operations 95.Bl -tag -width Ds 96.It Fn BIO_free b 97.Fn callback b BIO_CB_FREE NULL 0L 0L 1L 98is called before the free operation. 99.It Fn BIO_read b out outl 100.Fn callback b BIO_CB_READ out outl 0L 1L 101is called before the read and 102.Fn callback b BIO_CB_READ|BIO_CB_RETURN out outl 0L retvalue 103after. 104.It Fn BIO_write b in inl 105.Fn callback b BIO_CB_WRITE in inl 0L 1L 106is called before the write and 107.Fn callback b BIO_CB_WRITE|BIO_CB_RETURN in inl 0L retvalue 108after. 109.It Fn BIO_gets b out outl 110.Fn callback b BIO_CB_GETS out outl 0L 1L 111is called before the operation and 112.Fn callback b BIO_CB_GETS|BIO_CB_RETURN out outl 0L retvalue 113after. 114.It Fn BIO_puts b in 115.Fn callback b BIO_CB_WRITE in 0 0L 1L 116is called before the operation and 117.Fn callback b BIO_CB_WRITE|BIO_CB_RETURN in 0 0L retvalue 118after. 119.It Fn BIO_ctrl b cmd larg parg 120.Fn callback b BIO_CB_CTRL parg cmd larg 1L 121is called before the call and 122.Fn callback b BIO_CB_CTRL|BIO_CB_RETURN parg cmd larg ret 123after. 124.El 125.Sh EXAMPLES 126The 127.Fn BIO_debug_callback 128function is a good example, its source is in the file 129.Pa crypto/bio/bio_cb.c . 130