168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisBIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, 668651SkrisBIO_debug_callback - BIO callback functions 768651Skris 868651Skris=head1 SYNOPSIS 968651Skris 1068651Skris #include <openssl/bio.h> 1168651Skris 1268651Skris #define BIO_set_callback(b,cb) ((b)->callback=(cb)) 1368651Skris #define BIO_get_callback(b) ((b)->callback) 1468651Skris #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) 1568651Skris #define BIO_get_callback_arg(b) ((b)->cb_arg) 1668651Skris 1768651Skris long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi, 1868651Skris long argl,long ret); 1968651Skris 20167612Ssimon typedef long (*callback)(BIO *b, int oper, const char *argp, 2168651Skris int argi, long argl, long retvalue); 2268651Skris 2368651Skris=head1 DESCRIPTION 2468651Skris 2568651SkrisBIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback, 2668651Skristhey are both macros. The callback is called during most high level BIO 2768651Skrisoperations. It can be used for debugging purposes to trace operations on 2868651Skrisa BIO or to modify its operation. 2968651Skris 3068651SkrisBIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be 3168651Skrisused to set and retrieve an argument for use in the callback. 3268651Skris 3368651SkrisBIO_debug_callback() is a standard debugging callback which prints 3468651Skrisout information relating to each BIO operation. If the callback 3568651Skrisargument is set if is interpreted as a BIO to send the information 3668651Skristo, otherwise stderr is used. 3768651Skris 3868651Skriscallback() is the callback function itself. The meaning of each 3968651Skrisargument is described below. 4068651Skris 4168651SkrisThe BIO the callback is attached to is passed in B<b>. 4268651Skris 4368651SkrisB<oper> is set to the operation being performed. For some operations 4468651Skristhe callback is called twice, once before and once after the actual 4568651Skrisoperation, the latter case has B<oper> or'ed with BIO_CB_RETURN. 4668651Skris 4768651SkrisThe meaning of the arguments B<argp>, B<argi> and B<argl> depends on 4868651Skristhe value of B<oper>, that is the operation being performed. 4968651Skris 5068651SkrisB<retvalue> is the return value that would be returned to the 5168651Skrisapplication if no callback were present. The actual value returned 5268651Skrisis the return value of the callback itself. In the case of callbacks 5368651Skriscalled before the actual BIO operation 1 is placed in retvalue, if 5468651Skristhe return value is not positive it will be immediately returned to 5568651Skristhe application and the BIO operation will not be performed. 5668651Skris 5768651SkrisThe callback should normally simply return B<retvalue> when it has 5868651Skrisfinished processing, unless if specifically wishes to modify the 5968651Skrisvalue returned to the application. 6068651Skris 6168651Skris=head1 CALLBACK OPERATIONS 6268651Skris 6368651Skris=over 4 6468651Skris 6568651Skris=item B<BIO_free(b)> 6668651Skris 6768651Skriscallback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the 6868651Skrisfree operation. 6968651Skris 7068651Skris=item B<BIO_read(b, out, outl)> 7168651Skris 7268651Skriscallback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before 7368651Skristhe read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue) 7468651Skrisafter. 7568651Skris 7668651Skris=item B<BIO_write(b, in, inl)> 7768651Skris 7868651Skriscallback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before 7968651Skristhe write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue) 8068651Skrisafter. 8168651Skris 8268651Skris=item B<BIO_gets(b, out, outl)> 8368651Skris 8468651Skriscallback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before 8568651Skristhe operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue) 8668651Skrisafter. 8768651Skris 8868651Skris=item B<BIO_puts(b, in)> 8968651Skris 9068651Skriscallback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before 9168651Skristhe operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue) 9268651Skrisafter. 9368651Skris 9468651Skris=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)> 9568651Skris 9668651Skriscallback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and 9768651Skriscallback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after. 9868651Skris 9968651Skris=back 10068651Skris 10168651Skris=head1 EXAMPLE 10268651Skris 10368651SkrisThe BIO_debug_callback() function is a good example, its source is 10468651Skrisin crypto/bio/bio_cb.c 10568651Skris 10668651Skris=head1 SEE ALSO 10768651Skris 10868651SkrisTBA 109