Sortix 1.1dev nightly manual
This manual documents Sortix 1.1dev nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
BIO_SET_CALLBACK(3) | Library Functions Manual | BIO_SET_CALLBACK(3) |
NAME
BIO_set_callback
,
BIO_get_callback
,
BIO_set_callback_arg
,
BIO_get_callback_arg
,
BIO_debug_callback
—
BIO callback functions
SYNOPSIS
#include
<openssl/bio.h>
void
BIO_set_callback
(BIO
*b, BIO_callback_fn cb);
BIO_callback_fn
BIO_get_callback
(BIO
*b);
void
BIO_set_callback_arg
(BIO
*b, char *arg);
char *
BIO_get_callback_arg
(const
BIO *b);
long
BIO_debug_callback
(BIO
*bio, int oper,
const char *argp,
int argi, long
argl, long ret);
typedef long
(*BIO_callback_fn)
(BIO
*b, int oper,
const char *argp,
int argi, long
argl, long ret);
DESCRIPTION
BIO_set_callback
() and
BIO_get_callback
() set and retrieve the BIO
callback. 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.
BIO_set_callback_arg
() and
BIO_get_callback_arg
() set and retrieve an
argument for use in the callback.
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.
BIO_callback_fn
() is the type of the callback
function. The meaning of each argument is described below.
The BIO the callback is attached to is passed in
b.
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
oper or'ed with
BIO_CB_RETURN
.
The meaning of the arguments argp,
argi and
argl depends on the value of
oper (i.e. the operation being performed).
When oper does not include
BIO_CB_RETURN
, i.e. when the callback is
invoked before an operation, the value passed into the callback via
ret is always 1. In this case, if the
callback returns a negative value, the library aborts the requested operation
and instead returns the negative return value from the callback to the
application. If the callback returns a non-negative value, that return value
is ignored by the library, and the operation is performed normally.
When oper includes
BIO_CB_RETURN
, i.e. when the callback is
invoked after an operation, the value passed into the callback via
ret is the return value that the operation
would return to the application if no callback were present. When a callback
is present, the operation only passes this value to the callback and instead
of it returns the return value of the callback to the application.
The callback should normally simply return ret
when it has finished processing, unless it specifically wishes to abort the
operation or to modify the value returned to the application.
Callback operations
BIO_free
(b)callback
(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the free operation.BIO_read
(b, out, outl)callback
(b, BIO_CB_READ, out, outl, 0L, 1L) is called before the read andcallback
(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, ret) after.BIO_write
(b, in, inl)callback
(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before the write andcallback
(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, ret) after.BIO_gets
(b, out, outl)callback
(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before the operation andcallback
(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, ret) after.BIO_puts
(b, in)callback
(b, BIO_CB_PUTS, in, 0, 0L, 1L) is called before the operation andcallback
(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0L, ret) after.BIO_ctrl
(b, oper, larg, parg)callback
(b, BIO_CB_CTRL, parg, oper, larg, 1L) is called before the call andcallback
(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, oper, larg, ret) after.
RETURN VALUES
BIO_get_callback
() returns a pointer to the
function cb previously installed with
BIO_set_callback
(), or
NULL
if no callback was installed.
BIO_get_callback_arg
() returns a pointer to
the arg previously set with
BIO_set_callback_arg
(), or
NULL
if no such argument was set.
BIO_debug_callback
() returns
ret if the bit
BIO_CB_RETURN
is set in
cmd, or 1 otherwise.
EXAMPLES
TheBIO_debug_callback
() function is a good
example. Its source is in the file
crypto/bio/bio_cb.c.
SEE ALSO
BIO_new(3)HISTORY
BIO_set_callback
(),
BIO_get_callback
(),
BIO_set_callback_arg
(), and
BIO_debug_callback
() first appeared in
SSLeay 0.6.0. BIO_get_callback_arg
() first
appeared in SSLeay 0.8.0. All these functions have been available since
OpenBSD 2.4.March 29, 2018 | Debian |