NAME
BIO_callback_fn_ex
,
BIO_set_callback_ex
,
BIO_get_callback_ex
,
BIO_callback_fn
,
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>
typedef long
(*BIO_callback_fn_ex)
(BIO *b,
int oper, const char *argp,
size_t len, int argi,
long argl, int ret,
size_t *processed);
void
BIO_set_callback_ex
(BIO *b,
BIO_callback_fn_ex cb_ex);
BIO_callback_fn_ex
BIO_get_callback_ex
(const BIO
*b);
typedef long
(*BIO_callback_fn)
(BIO *b,
int oper, const char *argp,
int argi, long argl,
long ret);
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 *pointer);
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);
DESCRIPTION
BIO_set_callback_ex
()
and
BIO_get_callback_ex
()
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
()
and
BIO_get_callback
()
are deprecated functions that set and retrieve the old-style BIO callback,
which is only used if no new-style callback is set with
BIO_set_callback_ex
().
BIO_set_callback_arg
()
stores the pointer internally in
b and
BIO_get_callback_arg
()
retrieves it from b. The name of these two functions
is badly misleading: the pointer is never passed as an
argument to any callback function. But of course, callback functions can
call BIO_get_callback_arg
() and access the pointer,
just like any other code can.
BIO_debug_callback
()
is a standard debugging callback which prints out information related to
each BIO operation. If BIO_set_callback_arg
() was
called with a non-NULL
argument, information is sent
to the BIO pointed to by the pointer; otherwise,
standard error output is used.
The arguments of the callback functions are as follows:
- b
- The BIO the callback is attached to.
- oper
- 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
. - argp, argi, argl
- The meaning of these three arguments depends on the value of oper, that is on the operation being performed.
- len
- The length of the data requested to be read or written. This is only
useful if oper is
BIO_CB_READ
,BIO_CB_WRITE
, orBIO_CB_GETS
. - ret
- 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. - processed
- The location pointed to is updated with the number of bytes actually read
or written. Only used for
BIO_CB_READ
,BIO_CB_WRITE
,BIO_CB_GETS
, andBIO_CB_PUTS
.
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.
The callbacks are called as follows:
- In
BIO_free
(BIO *b): -
before the free operation: cb_ex(b, BIO_CB_FREE, NULL, 0, 0, 0, 1, NULL) or cb(b, BIO_CB_FREE, NULL, 0, 0, 1)
- In
BIO_read
(BIO *b, void *out, int outl): -
before the read operation: cb_ex(b, BIO_CB_READ, out, outl, 0, 0, 1, NULL) or cb(b, BIO_CB_READ, out, outl, 0, 1) after the read operation: cb_ex(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes) or cb(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0, ret)
- In
BIO_write
(BIO *b, const void *in, int inl): -
before the write operation: cb_ex(b, BIO_CB_WRITE, in, inl, 0, 0, 1, NULL) or cb(b, BIO_CB_WRITE, in, inl, 0, 1) after the write operation: cb_ex(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0, 0, ret, &bytes) or cb(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0, ret)
- In
BIO_gets
(BIO *b, char *out, int outl): -
before the read operation: cb_ex(b, BIO_CB_GETS, out, outl, 0, 0, 1, NULL) or cb(b, BIO_CB_GETS, out, outl, 0, 1) after the read operation: cb_ex(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes) or cb(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0, ret)
- In
BIO_puts
(BIO *b, const char *in): -
before the write operation: cb_ex(b, BIO_CB_PUTS, in, 0, 0, 0, 1, NULL) or cb(b, BIO_CB_PUTS, in, 0, 0, 1) after the write operation: cb_ex(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0, 0, ret, &bytes) or cb(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0, ret)
- In
BIO_ctrl
(BIO *b, int cmd, long larg, void *parg): -
before the control operation: cb_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1, NULL) or cb(b, BIO_CB_CTRL, parg, cmd, larg, 1) after the control operation: cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL) or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
- In
BIO_callback_ctrl
(BIO *b, int cmd, BIO_info_cb *fp): -
before the control operation: cb_ex(b, BIO_CB_CTRL, fp, 0, cmd, 0, 1, NULL) or cb(b, BIO_CB_CTRL, fp, cmd, 0, 1) after the control operation: cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, fp, 0, cmd, 0, ret, NULL) or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, fp, cmd, 0, ret)
RETURN VALUES
BIO_get_callback_ex
() returns a pointer to
the function cb_ex previously installed with
BIO_set_callback_cb
(), or
NULL
if no such callback was installed.
BIO_get_callback
() returns a pointer to
the function cb previously installed with
BIO_set_callback
(), or NULL
if no such callback was installed.
BIO_get_callback_arg
() returns the
pointer previously set with
BIO_set_callback_arg
(), or
NULL
if no such pointer was set.
BIO_debug_callback
() returns
ret if the bit BIO_CB_RETURN
is set in cmd, or 1 otherwise.
EXAMPLES
The BIO_debug_callback
() function is a
good example. Its source is in the file
crypto/bio/bio_cb.c.
SEE ALSO
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. These functions have been available since OpenBSD
2.4.
BIO_callback_fn
() first appeared in
OpenSSL 1.1.0. BIO_callback_fn_ex
(),
BIO_set_callback_ex
(), and
BIO_get_callback_ex
() first appeared in OpenSSL
1.1.1. These functions have been available since OpenBSD
7.1.