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_name, ossl_namemap_number
   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, const char *name);
  19  const char *ossl_namemap_name(const OSSL_NAMEMAP *namemap, int number);
  20  int ossl_namemap_number(const OSSL_NAMEMAP *namemap, const char *name);
  21
  22 =head1 DESCRIPTION
  23
  24 A B<OSSL_NAMEMAP> is a simple number E<lt>-E<gt> name map, which can
  25 be used to give any arbitrary name (any string) a unique dynamic
  26 identity that is valid throughout the lifetime of the associated
  27 library context.
  28
  29 ossl_namemap_new() and ossl_namemap_free() construct and destruct a
  30 new B<OSSL_NAMEMAP>.
  31 This is suitable to use when the B<OSSL_NAMEMAP> is embedded in other
  32 structures, or should be independent for any reason.
  33
  34 ossl_namemap_stored() finds or auto-creates the default namemap in the
  35 given library context.
  36 The returned B<OSSL_NAMEMAP> can't be destructed using
  37 ossl_namemap_free().
  38
  39 ossl_namemap_add() adds a new name to the namemap if it's not already
  40 present.
  41
  42 ossl_namemap_name() finds the name corresponding to the given number.
  43
  44 ossl_namemap_number() finds the number corresponding to the given
  45 name.
  46
  47 =head1 RETURN VALUES
  48
  49 ossl_namemap_new() and ossl_namemap_stored() return the pointer to a
  50 B<OSSL_NAMEMAP>, or NULL on error.
  51
  52 ossl_namemap_add() returns the number associated with the added
  53 string, or zero on error.
  54
  55 ossl_namemap_name() returns a pointer to the name corresponding to the
  56 given number, or NULL if it's undefined in the given B<OSSL_NAMEMAP>.
  57
  58 ossl_namemap_number() returns the number corresponding to the given
  59 name, or 0 if it's undefined in the given B<OSSL_NAMEMAP>.
  60
  61 =head1 HISTORY
  62
  63 The functions described here were all added in OpenSSL 3.0.
  64
  65 =head1 COPYRIGHT
  66
  67 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
  68
  69 Licensed under the Apache License 2.0 (the "License").  You may not use
  70 this file except in compliance with the License.  You can obtain a copy
  71 in the file LICENSE in the source distribution or at
  72 L<https://www.openssl.org/source/license.html>.
  73
  74 =cut