doc/man3/OSSL_PARAM_dup.pod

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