doc/internal/man3/ossl_namemap_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_namemap_new, ossl_namemap_free, ossl_namemap_stored,
   6 ossl_namemap_add, ossl_namemap_name2num, ossl_namemap_doall_names
   7 - internal number E<lt>-E<gt> name map
   8
   9 =head1 SYNOPSIS
  10
  11  #include "internal/cryptlib.h"
  12
  13  OSSL_NAMEMAP *ossl_namemap_stored(OPENSSL_CTX *libctx);
  14
  15  OSSL_NAMEMAP *ossl_namemap_new(void);
  16  void ossl_namemap_free(OSSL_NAMEMAP *namemap);
  17
  18  int ossl_namemap_add(OSSL_NAMEMAP *namemap, int number, const char *name);
  19
  20  int ossl_namemap_name2num(const OSSL_NAMEMAP *namemap, const char *name);
  21  void ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number,
  22                                void (*fn)(const char *name, void *data),
  23                                void *data);
  24
  25 =head1 DESCRIPTION
  26
  27 A B<OSSL_NAMEMAP> is a one-to-many number E<lt>-E<gt> names map, which
  28 can be used to give any arbitrary set of names (any string) a unique
  29 dynamic identity that is valid throughout the lifetime of the associated
  30 library context.
  31
  32 ossl_namemap_new() and ossl_namemap_free() construct and destruct a
  33 new B<OSSL_NAMEMAP>.
  34 This is suitable to use when the B<OSSL_NAMEMAP> is embedded in other
  35 structures, or should be independent for any reason.
  36
  37 ossl_namemap_stored() finds or auto-creates the default namemap in the
  38 given library context.
  39 The returned B<OSSL_NAMEMAP> can't be destructed using
  40 ossl_namemap_free().
  41
  42 ossl_namemap_add() adds a new name to the namemap if it's not already
  43 present.
  44 If the given I<number> is zero, a new number will be allocated to
  45 identify this I<name>.
  46 If the given I<number> is non-zero, the I<name> is added to the set of
  47 names already associated with that number.
  48
  49 ossl_namemap_name2num() finds the number corresponding to the given
  50 I<name>.
  51
  52 ossl_namemap_doall_names() walks through all names associated with
  53 I<number> in the given I<namemap> and calls the function I<fn> for
  54 each of them.
  55 I<fn> is also passed the I<data> argument, which allows any caller to
  56 pass extra data for that function to use.
  57
  58 =head1 RETURN VALUES
  59
  60 ossl_namemap_new() and ossl_namemap_stored() return the pointer to a
  61 B<OSSL_NAMEMAP>, or NULL on error.
  62
  63 ossl_namemap_add() returns the number associated with the added
  64 string, or zero on error.
  65
  66 ossl_namemap_num2names() returns a pointer to a NULL-terminated list of
  67 pointers to the names corresponding to the given number, or NULL if
  68 it's undefined in the given B<OSSL_NAMEMAP>.
  69
  70 ossl_namemap_name2num() returns the number corresponding to the given
  71 name, or 0 if it's undefined in the given B<OSSL_NAMEMAP>.
  72
  73 =head1 NOTES
  74
  75 The result from ossl_namemap_num2names() isn't thread safe, other threads
  76 dealing with the same namemap may cause the list of names to change
  77 location.
  78 It is therefore strongly recommended to only use the result in code
  79 guarded by a thread lock.
  80
  81 =head1 HISTORY
  82
  83 The functions described here were all added in OpenSSL 3.0.
  84
  85 =head1 COPYRIGHT
  86
  87 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
  88
  89 Licensed under the Apache License 2.0 (the "License").  You may not use
  90 this file except in compliance with the License.  You can obtain a copy
  91 in the file LICENSE in the source distribution or at
  92 L<https://www.openssl.org/source/license.html>.
  93
  94 =cut