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_name, ossl_namemap_add_name_n, ossl_namemap_add_names,
   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(OSSL_LIB_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_name(OSSL_NAMEMAP *namemap, int number, const char *name);
  22  int ossl_namemap_add_name_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  int ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number,
  29                               void (*fn)(const char *name, void *data),
  30                               void *data);
  31
  32  int ossl_namemap_add_names(OSSL_NAMEMAP *namemap, int number,
  33                             const char *names, const char separator);
  34
  35 =head1 DESCRIPTION
  36
  37 A B<OSSL_NAMEMAP> is a one-to-many number E<lt>-E<gt> names map, which
  38 can be used to give any arbitrary set of names (any string) a unique
  39 dynamic identity that is valid throughout the lifetime of the associated
  40 library context.
  41
  42 ossl_namemap_new() and ossl_namemap_free() construct and destruct a
  43 new B<OSSL_NAMEMAP>.
  44 This is suitable to use when the B<OSSL_NAMEMAP> is embedded in other
  45 structures, or should be independent for any reason.
  46
  47 ossl_namemap_empty() checks if the given B<OSSL_NAMEMAP> is empty or
  48 not.
  49
  50 ossl_namemap_stored() finds or auto-creates the default namemap in the
  51 given library context.
  52 The returned B<OSSL_NAMEMAP> can't be destructed using
  53 ossl_namemap_free().
  54
  55 ossl_namemap_add_name() adds a new name to the namemap if it's not already
  56 present.
  57 If the given I<number> is zero, a new number will be allocated to
  58 identify this I<name>.
  59 If the given I<number> is nonzero, the I<name> is added to the set of
  60 names already associated with that number.
  61
  62 ossl_namemap_name2num() finds the number corresponding to the given
  63 I<name>.
  64
  65 ossl_namemap_add_name_n() and ossl_namemap_name2num_n() do the same thing
  66 as ossl_namemap_add_name() and ossl_namemap_name2num(), but take a string
  67 length I<name_len> as well, allowing the caller to use a fragment of
  68 a string as a name.
  69
  70 ossl_namemap_doall_names() walks through all names associated with
  71 I<number> in the given I<namemap> and calls the function I<fn> for
  72 each of them.
  73 I<fn> is also passed the I<data> argument, which allows any caller to
  74 pass extra data for that function to use.
  75
  76 ossl_namemap_add_names() divides up a set of names given in I<names>,
  77 separated by I<separator>, and adds each to the I<namemap>, all with
  78 the same number.  If some of them already exist in the I<namemap>,
  79 they must all have the same associated number, which will be adopted
  80 for any name that doesn't exist yet.
  81
  82 =head1 RETURN VALUES
  83
  84 ossl_namemap_new() and ossl_namemap_stored() return the pointer to a
  85 B<OSSL_NAMEMAP>, or NULL on error.
  86
  87 ossl_namemap_empty() returns 1 if the B<OSSL_NAMEMAP> is NULL or
  88 empty, or 0 if it's not empty.
  89
  90 ossl_namemap_add_name() and ossl_namemap_add_name_n() return the number
  91 associated with the added string, or zero on error.
  92
  93 ossl_namemap_num2names() returns a pointer to a NULL-terminated list of
  94 pointers to the names corresponding to the given number, or NULL if
  95 it's undefined in the given B<OSSL_NAMEMAP>.
  96
  97 ossl_namemap_name2num() and ossl_namemap_name2num_n() return the number
  98 corresponding to the given name, or 0 if it's undefined in the given
  99 B<OSSL_NAMEMAP>.
 100
 101 ossl_namemap_doall_names() returns 1 if the callback was called for all names. A
 102 return value of 0 means that the callback was not called for any names.
 103
 104 ossl_namemap_add_names() returns the number associated with the added
 105 names, or zero on error.
 106
 107 =head1 NOTES
 108
 109 The result from ossl_namemap_num2names() isn't thread safe, other threads
 110 dealing with the same namemap may cause the list of names to change
 111 location.
 112 It is therefore strongly recommended to only use the result in code
 113 guarded by a thread lock.
 114
 115 =head1 HISTORY
 116
 117 The functions described here were all added in OpenSSL 3.0.
 118
 119 =head1 COPYRIGHT
 120
 121 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
 122
 123 Licensed under the Apache License 2.0 (the "License").  You may not use
 124 this file except in compliance with the License.  You can obtain a copy
 125 in the file LICENSE in the source distribution or at
 126 L<https://www.openssl.org/source/license.html>.
 127
 128 =cut