ossl_namemap_new.pod 4.7 KB

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