NAME
BIO_dup_chain,
BIO_dup_state —
copy a BIO chain
SYNOPSIS
#include
<openssl/bio.h>
BIO *
BIO_dup_chain(BIO
*b);
long
BIO_dup_state(BIO
*b, BIO
*new_bio);
DESCRIPTION
BIO_dup_chain()
copies the chain starting at b by iteratively copying
b and all the BIOs following it and joining the copies
in the same order as in the original chain. The copying operation is neither
a deep copy nor a shallow copy.
Some parts of the state of each BIO are copied, in particular with
respect to the values returned by
BIO_get_init(3),
BIO_test_flags(3), and
BIO_get_shutdown(3). Other parts of the state of the BIOs are
not copied but instead initialized to 0, in particular with respect to the
values returned by
BIO_number_read(3),
BIO_number_written(3), and
BIO_get_retry_reason(3). The custom data pointer that can be
used by custom BIO types and that can be retrieved with
BIO_get_data(3) is set to NULL in the
copied BIO objects rather than copied. The reference count of each BIO in
the copied chain is set to 1.
For each BIO in the chain, copying the data that was set with BIO_set_ex_data(3) is attempted, which may involve calling application-defined callback functions.
The following pointers are copied rather than creating deep copies of the objects pointed to:
- The type pointer used for creating each BIO with BIO_new(3), implying that functions like BIO_method_name(3) return pointers to the same strings for the BIOs in the copied chain, and that these strings are not copied.
- All function pointers, in particular those installed with BIO_set_callback_ex(3) and BIO_get_callback_ex(3).
- The pointer installed with BIO_set_callback_arg(3), which implies that for BIOs using BIO_debug_callback(3), those in the copied chain use the same BIOs for debugging output as the corresponding ones in the original chain, and none of the debugging output BIOs are copied.
BIO_dup_state()
is a macro that calls
BIO_ctrl(3) with a cmd argument of
BIO_CTRL_DUP. It is automatically called for each
BIO during BIO_dup_chain() after the copied BIO is
initialized and data copied into it, but before the data set with
BIO_set_ex_data(3) is copied into the new BIO and before it
is linked into the new chain.
This control operation may modify the
operation of
BIO_dup_chain()
for particular types of BIOs contained in the chain, for example
initializing or copying additional data. For BIO types provided by the
library, such additional effects are documented in the respective manual
pages, in particular in
BIO_f_buffer(3),
BIO_f_cipher(3),
BIO_f_md(3),
BIO_f_ssl(3),
BIO_s_bio(3), and
BIO_s_connect(3).
RETURN VALUES
BIO_dup_chain() returns a pointer to the
newly allocated copy of the BIO b on success or
NULL on failure .
BIO_dup_state() returns 1 on success or a
value less than or equal to zero on failure.
SEE ALSO
HISTORY
BIO_dup_chain() and
BIO_dup_state() first appeared in SSLeay 0.8.0 and
have been available since OpenBSD 2.4.