1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, 6*2175Sjp161948BIO_debug_callback - BIO callback functions 7*2175Sjp161948 8*2175Sjp161948=head1 SYNOPSIS 9*2175Sjp161948 10*2175Sjp161948 #include <openssl/bio.h> 11*2175Sjp161948 12*2175Sjp161948 #define BIO_set_callback(b,cb) ((b)->callback=(cb)) 13*2175Sjp161948 #define BIO_get_callback(b) ((b)->callback) 14*2175Sjp161948 #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) 15*2175Sjp161948 #define BIO_get_callback_arg(b) ((b)->cb_arg) 16*2175Sjp161948 17*2175Sjp161948 long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi, 18*2175Sjp161948 long argl,long ret); 19*2175Sjp161948 20*2175Sjp161948 typedef long callback(BIO *b, int oper, const char *argp, 21*2175Sjp161948 int argi, long argl, long retvalue); 22*2175Sjp161948 23*2175Sjp161948=head1 DESCRIPTION 24*2175Sjp161948 25*2175Sjp161948BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback, 26*2175Sjp161948they are both macros. The callback is called during most high level BIO 27*2175Sjp161948operations. It can be used for debugging purposes to trace operations on 28*2175Sjp161948a BIO or to modify its operation. 29*2175Sjp161948 30*2175Sjp161948BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be 31*2175Sjp161948used to set and retrieve an argument for use in the callback. 32*2175Sjp161948 33*2175Sjp161948BIO_debug_callback() is a standard debugging callback which prints 34*2175Sjp161948out information relating to each BIO operation. If the callback 35*2175Sjp161948argument is set if is interpreted as a BIO to send the information 36*2175Sjp161948to, otherwise stderr is used. 37*2175Sjp161948 38*2175Sjp161948callback() is the callback function itself. The meaning of each 39*2175Sjp161948argument is described below. 40*2175Sjp161948 41*2175Sjp161948The BIO the callback is attached to is passed in B<b>. 42*2175Sjp161948 43*2175Sjp161948B<oper> is set to the operation being performed. For some operations 44*2175Sjp161948the callback is called twice, once before and once after the actual 45*2175Sjp161948operation, the latter case has B<oper> or'ed with BIO_CB_RETURN. 46*2175Sjp161948 47*2175Sjp161948The meaning of the arguments B<argp>, B<argi> and B<argl> depends on 48*2175Sjp161948the value of B<oper>, that is the operation being performed. 49*2175Sjp161948 50*2175Sjp161948B<retvalue> is the return value that would be returned to the 51*2175Sjp161948application if no callback were present. The actual value returned 52*2175Sjp161948is the return value of the callback itself. In the case of callbacks 53*2175Sjp161948called before the actual BIO operation 1 is placed in retvalue, if 54*2175Sjp161948the return value is not positive it will be immediately returned to 55*2175Sjp161948the application and the BIO operation will not be performed. 56*2175Sjp161948 57*2175Sjp161948The callback should normally simply return B<retvalue> when it has 58*2175Sjp161948finished processing, unless if specifically wishes to modify the 59*2175Sjp161948value returned to the application. 60*2175Sjp161948 61*2175Sjp161948=head1 CALLBACK OPERATIONS 62*2175Sjp161948 63*2175Sjp161948=over 4 64*2175Sjp161948 65*2175Sjp161948=item B<BIO_free(b)> 66*2175Sjp161948 67*2175Sjp161948callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the 68*2175Sjp161948free operation. 69*2175Sjp161948 70*2175Sjp161948=item B<BIO_read(b, out, outl)> 71*2175Sjp161948 72*2175Sjp161948callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before 73*2175Sjp161948the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue) 74*2175Sjp161948after. 75*2175Sjp161948 76*2175Sjp161948=item B<BIO_write(b, in, inl)> 77*2175Sjp161948 78*2175Sjp161948callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before 79*2175Sjp161948the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue) 80*2175Sjp161948after. 81*2175Sjp161948 82*2175Sjp161948=item B<BIO_gets(b, out, outl)> 83*2175Sjp161948 84*2175Sjp161948callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before 85*2175Sjp161948the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue) 86*2175Sjp161948after. 87*2175Sjp161948 88*2175Sjp161948=item B<BIO_puts(b, in)> 89*2175Sjp161948 90*2175Sjp161948callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before 91*2175Sjp161948the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue) 92*2175Sjp161948after. 93*2175Sjp161948 94*2175Sjp161948=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)> 95*2175Sjp161948 96*2175Sjp161948callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and 97*2175Sjp161948callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after. 98*2175Sjp161948 99*2175Sjp161948=back 100*2175Sjp161948 101*2175Sjp161948=head1 EXAMPLE 102*2175Sjp161948 103*2175Sjp161948The BIO_debug_callback() function is a good example, its source is 104*2175Sjp161948in crypto/bio/bio_cb.c 105*2175Sjp161948 106*2175Sjp161948=head1 SEE ALSO 107*2175Sjp161948 108*2175Sjp161948TBA 109