1.\" $OpenBSD: BIO_dup_chain.3,v 1.2 2023/04/09 06:27:52 jsg Exp $ 2.\" 3.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 9 2023 $ 18.Dt BIO_DUP_CHAIN 3 19.Os 20.Sh NAME 21.Nm BIO_dup_chain , 22.Nm BIO_dup_state 23.Nd copy a BIO chain 24.Sh SYNOPSIS 25.In openssl/bio.h 26.Ft BIO * 27.Fn BIO_dup_chain "BIO *b" 28.Ft long 29.Fn BIO_dup_state "BIO *b" "BIO *new_bio" 30.Sh DESCRIPTION 31.Fn BIO_dup_chain 32copies the chain starting at 33.Fa b 34by iteratively copying 35.Fa b 36and all the BIOs following it 37and joining the copies in the same order as in the original chain. 38The copying operation is neither a deep copy nor a shallow copy. 39.Pp 40Some parts of the state of each BIO are copied, 41in particular with respect to the values returned by 42.Xr BIO_get_init 3 , 43.Xr BIO_test_flags 3 , 44and 45.Xr BIO_get_shutdown 3 . 46.\" XXX new_bio->num = bio->num; 47Other parts of the state of the BIOs are not copied 48but instead initialized to 0, 49in particular with respect to the values returned by 50.Xr BIO_number_read 3 , 51.Xr BIO_number_written 3 , 52and 53.Xr BIO_get_retry_reason 3 . 54The custom data pointer that can be used by custom BIO types 55and that can be retrieved with 56.Xr BIO_get_data 3 57is set to 58.Dv NULL 59in the copied BIO objects rather than copied. 60The reference count of each BIO in the copied chain is set to 1. 61.Pp 62For each BIO in the chain, copying the data that was set with 63.Xr BIO_set_ex_data 3 64is attempted, which may involve calling application-defined 65callback functions. 66.Pp 67The following pointers are copied 68rather than creating deep copies of the objects pointed to: 69.Bl -bullet 70.It 71The 72.Fa type 73pointer used for creating each BIO with 74.Xr BIO_new 3 , 75implying that functions like 76.Xr BIO_method_name 3 77return pointers to the same strings for the BIOs in the copied chain, 78and that these strings are not copied. 79.It 80All function pointers, in particular those installed with 81.Xr BIO_set_callback_ex 3 82and 83.Xr BIO_get_callback_ex 3 . 84.It 85The pointer installed with 86.Xr BIO_set_callback_arg 3 , 87which implies that for BIOs using 88.Xr BIO_debug_callback 3 , 89those in the copied chain use the same BIOs for debugging output 90as the corresponding ones in the original chain, 91and none of the debugging output BIOs are copied. 92.El 93.Pp 94.Fn BIO_dup_state 95is a macro that calls 96.Xr BIO_ctrl 3 97with a 98.Fa cmd 99argument of 100.Dv BIO_CTRL_DUP . 101It is automatically called for each BIO during 102.Fn BIO_dup_chain 103after the copied BIO is initialized and data copied into it, 104but before the data set with 105.Xr BIO_set_ex_data 3 106is copied into the new BIO and before it is linked into the new chain. 107.Pp 108This control operation may modify the operation of 109.Fn BIO_dup_chain 110for particular types of BIOs contained in the chain, 111for example initializing or copying additional data. 112For BIO types provided by the library, such additional effects 113are documented in the respective manual pages, in particular in 114.Xr BIO_f_buffer 3 , 115.Xr BIO_f_cipher 3 , 116.Xr BIO_f_md 3 , 117.Xr BIO_f_ssl 3 , 118.Xr BIO_s_bio 3 , 119and 120.Xr BIO_s_connect 3 . 121.Sh RETURN VALUES 122.Fn BIO_dup_chain 123returns a pointer to the newly allocated copy of the BIO 124.Fa b 125on success or 126.Dv NULL 127on failure . 128.Pp 129.Fn BIO_dup_state 130returns 1 on success or a value less than or equal to zero on failure. 131.Sh SEE ALSO 132.Xr BIO_get_data 3 , 133.Xr BIO_new 3 , 134.Xr BIO_next 3 , 135.Xr BIO_push 3 136.Sh HISTORY 137.Fn BIO_dup_chain 138and 139.Fn BIO_dup_state 140first appeared in SSLeay 0.8.0 and have been available since 141.Ox 2.4 . 142