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

BIO_get_data(3), BIO_new(3), BIO_next(3), BIO_push(3)

HISTORY

BIO_dup_chain() and BIO_dup_state() first appeared in SSLeay 0.8.0 and have been available since OpenBSD 2.4.