doc/internal/man3/ossl_namemap_new.pod

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