Drop ossl_namemap_add_name_n() and simplify ossl_namemap_add_names()

[thirdparty/openssl.git] / doc / internal / man3 / ossl_namemap_new.pod

=pod

=head1 NAME

ossl_namemap_new, ossl_namemap_free, ossl_namemap_stored, ossl_namemap_empty,
ossl_namemap_add_name, ossl_namemap_add_names,
ossl_namemap_name2num, ossl_namemap_name2num_n,
ossl_namemap_doall_names
- internal number E<lt>-E<gt> name map

=head1 SYNOPSIS

 #include "internal/cryptlib.h"

 OSSL_NAMEMAP *ossl_namemap_stored(OSSL_LIB_CTX *libctx);

 OSSL_NAMEMAP *ossl_namemap_new(void);
 void ossl_namemap_free(OSSL_NAMEMAP *namemap);
 int ossl_namemap_empty(OSSL_NAMEMAP *namemap);

 int ossl_namemap_add_name(OSSL_NAMEMAP *namemap, int number, const char *name);

 int ossl_namemap_name2num(const OSSL_NAMEMAP *namemap, const char *name);
 int ossl_namemap_name2num_n(const OSSL_NAMEMAP *namemap,
                             const char *name, size_t name_len);
 int ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number,
                              void (*fn)(const char *name, void *data),
                              void *data);

 int ossl_namemap_add_names(OSSL_NAMEMAP *namemap, int number,
                            const char *names, const char separator);

=head1 DESCRIPTION

A B<OSSL_NAMEMAP> is a one-to-many number E<lt>-E<gt> names map, which
can be used to give any arbitrary set of names (any string) a unique
dynamic identity that is valid throughout the lifetime of the associated
library context.

ossl_namemap_new() and ossl_namemap_free() construct and destruct a
new B<OSSL_NAMEMAP>.
This is suitable to use when the B<OSSL_NAMEMAP> is embedded in other
structures, or should be independent for any reason.

ossl_namemap_empty() checks if the given B<OSSL_NAMEMAP> is empty or
not.

ossl_namemap_stored() finds or auto-creates the default namemap in the
given library context.
The returned B<OSSL_NAMEMAP> can't be destructed using
ossl_namemap_free().

ossl_namemap_add_name() adds a new name to the namemap if it's not already
present.
If the given I<number> is zero, a new number will be allocated to
identify this I<name>.
If the given I<number> is nonzero, the I<name> is added to the set of
names already associated with that number.

ossl_namemap_name2num() finds the number corresponding to the given
I<name>.

ossl_namemap_name2num_n() does the same thing as
ossl_namemap_name2num(), but takes a string length I<name_len> as well,
allowing the caller to use a fragment of a string as a name.

ossl_namemap_doall_names() walks through all names associated with
I<number> in the given I<namemap> and calls the function I<fn> for
each of them.
I<fn> is also passed the I<data> argument, which allows any caller to
pass extra data for that function to use.

ossl_namemap_add_names() divides up a set of names given in I<names>,
separated by I<separator>, and adds each to the I<namemap>, all with
the same number.  If some of them already exist in the I<namemap>,
they must all have the same associated number, which will be adopted
for any name that doesn't exist yet.

=head1 RETURN VALUES

ossl_namemap_new() and ossl_namemap_stored() return the pointer to a
B<OSSL_NAMEMAP>, or NULL on error.

ossl_namemap_empty() returns 1 if the B<OSSL_NAMEMAP> is NULL or
empty, 0 if it's not empty, or -1 on internal error (such as inability
to lock).

ossl_namemap_add_name() returns the number associated with the added
string, or zero on error.

ossl_namemap_num2names() returns a pointer to a NULL-terminated list of
pointers to the names corresponding to the given number, or NULL if
it's undefined in the given B<OSSL_NAMEMAP>.

ossl_namemap_name2num() and ossl_namemap_name2num_n() return the number
corresponding to the given name, or 0 if it's undefined in the given
B<OSSL_NAMEMAP>.

ossl_namemap_doall_names() returns 1 if the callback was called for all names. A
return value of 0 means that the callback was not called for any names.

ossl_namemap_add_names() returns the number associated with the added
names, or zero on error.

=head1 NOTES

The result from ossl_namemap_num2names() isn't thread safe, other threads
dealing with the same namemap may cause the list of names to change
location.
It is therefore strongly recommended to only use the result in code
guarded by a thread lock.

=head1 HISTORY

The functions described here were all added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut