xref: /openssl/doc/man3/OSSL_PARAM_dup.pod (revision 7ed6de99)
1=pod
2
3=head1 NAME
4
5OSSL_PARAM_dup, OSSL_PARAM_merge, OSSL_PARAM_free
6- OSSL_PARAM array copy functions
7
8=head1 SYNOPSIS
9
10 #include <openssl/params.h>
11
12 OSSL_PARAM *OSSL_PARAM_dup(const OSSL_PARAM *params);
13 OSSL_PARAM *OSSL_PARAM_merge(const OSSL_PARAM *params, const OSSL_PARAM *params1);
14 void OSSL_PARAM_free(OSSL_PARAM *params);
15
16=head1 DESCRIPTION
17
18Algorithm parameters can be exported/imported from/to providers using arrays of
19L<OSSL_PARAM(3)>. The following utility functions allow the parameters to be
20duplicated and merged with other L<OSSL_PARAM(3)> to assist in this process.
21
22OSSL_PARAM_dup() duplicates the parameter array I<params>. This function does a
23deep copy of the data.
24
25OSSL_PARAM_merge() merges the parameter arrays I<params> and I<params1> into a
26new parameter array. If I<params> and I<params1> contain values with the same
27'key' then the value from I<params1> will replace the I<param> value. This
28function does a shallow copy of the parameters. Either I<params> or I<params1>
29may be NULL. The behaviour of the merge is unpredictable if I<params> and
30I<params1> contain the same key, and there are multiple entries within either
31array that have the same key.
32
33OSSL_PARAM_free() frees the parameter array I<params> that was created using
34OSSL_PARAM_dup(), OSSL_PARAM_merge() or OSSL_PARAM_BLD_to_param().
35If the argument to OSSL_PARAM_free() is NULL, nothing is done.
36
37=head1 RETURN VALUES
38
39The functions OSSL_PARAM_dup() and OSSL_PARAM_merge() return a newly allocated
40L<OSSL_PARAM(3)> array, or NULL if there was an error. If both parameters are NULL
41 then NULL is returned.
42
43=head1 SEE ALSO
44
45L<OSSL_PARAM(3)>, L<OSSL_PARAM_BLD(3)>
46
47=head1 HISTORY
48
49The functions were added in OpenSSL 3.0.
50
51=head1 COPYRIGHT
52
53Copyright 2021-2024 The OpenSSL Project Authors. All Rights Reserved.
54
55Licensed under the Apache License 2.0 (the "License").  You may not use
56this file except in compliance with the License.  You can obtain a copy
57in the file LICENSE in the source distribution or at
58L<https://www.openssl.org/source/license.html>.
59
60=cut
61