[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_name_n, 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_add_name_n(OSSL_NAMEMAP *namemap, int number,
                             const char *name, size_t name_len);

 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_add_name_n() and ossl_namemap_name2num_n() do the same thing
as ossl_namemap_add_name() and ossl_namemap_name2num(), but take 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, or 0 if it's not empty.

ossl_namemap_add_name() and ossl_namemap_add_name_n() return 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
Commit	Line	Data
f2182a4e RL	1	=pod
	2
	3	=head1 NAME
	4
6a835fcf	5	ossl_namemap_new, ossl_namemap_free, ossl_namemap_stored, ossl_namemap_empty,
3d83c735	6	ossl_namemap_add_name, ossl_namemap_add_name_n, ossl_namemap_add_names,
695d195b RL	7	ossl_namemap_name2num, ossl_namemap_name2num_n,
695d195b RL	8	ossl_namemap_doall_names
f2182a4e RL	9	- internal number E<lt>-E<gt> name map
	10
	11	=head1 SYNOPSIS
	12
	13	#include "internal/cryptlib.h"
	14
b4250010	15	OSSL_NAMEMAP ossl_namemap_stored(OSSL_LIB_CTX libctx);
f2182a4e RL	16
	17	OSSL_NAMEMAP *ossl_namemap_new(void);
	18	void ossl_namemap_free(OSSL_NAMEMAP *namemap);
6a835fcf	19	int ossl_namemap_empty(OSSL_NAMEMAP *namemap);
f2182a4e	20
3d83c735 RL	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);
651d4418 RL	24
651d4418 RL	25	int ossl_namemap_name2num(const OSSL_NAMEMAP namemap, const char name);
695d195b RL	26	int ossl_namemap_name2num_n(const OSSL_NAMEMAP *namemap,
695d195b RL	27	const char *name, size_t name_len);
d84f5515 MC	28	int ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number,
	29	void (fn)(const char name, void *data),
	30	void *data);
f2182a4e	31
3d83c735 RL	32	int ossl_namemap_add_names(OSSL_NAMEMAP *namemap, int number,
	33	const char *names, const char separator);
	34
f2182a4e RL	35	=head1 DESCRIPTION
f2182a4e RL	36
651d4418 RL	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
f2182a4e RL	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
6a835fcf RL	47	ossl_namemap_empty() checks if the given B<OSSL_NAMEMAP> is empty or
	48	not.
	49
f2182a4e RL	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
3d83c735	55	ossl_namemap_add_name() adds a new name to the namemap if it's not already
f2182a4e	56	present.
651d4418 RL	57	If the given I<number> is zero, a new number will be allocated to
651d4418 RL	58	identify this I<name>.
9c0586d5	59	If the given I<number> is nonzero, the I<name> is added to the set of
651d4418	60	names already associated with that number.
f2182a4e	61
651d4418 RL	62	ossl_namemap_name2num() finds the number corresponding to the given
651d4418 RL	63	I<name>.
f2182a4e	64
3d83c735 RL	65	ossl_namemap_add_name_n() and ossl_namemap_name2num_n() do the same thing
3d83c735 RL	66	as ossl_namemap_add_name() and ossl_namemap_name2num(), but take a string
695d195b RL	67	length I<name_len> as well, allowing the caller to use a fragment of
	68	a string as a name.
	69
651d4418 RL	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.
f2182a4e	75
3d83c735 RL	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
f2182a4e RL	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
6a835fcf RL	87	ossl_namemap_empty() returns 1 if the B<OSSL_NAMEMAP> is NULL or
	88	empty, or 0 if it's not empty.
	89
3d83c735 RL	90	ossl_namemap_add_name() and ossl_namemap_add_name_n() return the number
3d83c735 RL	91	associated with the added string, or zero on error.
f2182a4e	92
651d4418 RL	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>.
f2182a4e	96
695d195b RL	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>.
f2182a4e	100
d84f5515 MC	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
3d83c735 RL	104	ossl_namemap_add_names() returns the number associated with the added
	105	names, or zero on error.
	106
651d4418 RL	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
f2182a4e RL	115	=head1 HISTORY
	116
	117	The functions described here were all added in OpenSSL 3.0.
	118
	119	=head1 COPYRIGHT
	120
8020d79b	121	Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
f2182a4e RL	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