Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OBJ_NAME_ADD(3)	       FreeBSD Library Functions Manual	       OBJ_NAME_ADD(3)

NAME
     OBJ_NAME_add, OBJ_NAME_remove, OBJ_NAME_get, OBJ_NAME_new_index,
     OBJ_NAME_init, OBJ_NAME_cleanup, OBJ_NAME_do_all, OBJ_NAME_do_all_sorted
     --	global associative array

SYNOPSIS
     #include <openssl/objects.h>

     int
     OBJ_NAME_add(const	char *name, int	type, const char *data);

     int
     OBJ_NAME_remove(const char	*name, int type);

     const char	*
     OBJ_NAME_get(const	char *name, int	type);

     int
     OBJ_NAME_new_index(unsigned long (*hash_func)(const char *name),
	 int (*cmp_func)(const char *name1, const char *name2),
	 void (*free_func)(const char *name, int type, const char *value));

     int
     OBJ_NAME_init(void);

     void
     OBJ_NAME_cleanup(int type);

     typedef struct {
	     int	 type;
	     int	 alias;
	     const char	*name;
	     const char	*data;
     } OBJ_NAME;

     void
     OBJ_NAME_do_all(int type, void (*fn)(const	OBJ_NAME *pair,	void *arg),
	 void *arg);

     void
     OBJ_NAME_do_all_sorted(int	type,
	 void (*fn)(const OBJ_NAME *pair, void *arg), void *arg);

DESCRIPTION
     These functions implement a single, static	associative array with the
     following properties:

     +o	 The keys are ordered pairs consisting of a NUL-terminated string
	 (called the name) and an int number (called the type).	 Two types are
	 predefined and	used internally	by the library:	OBJ_NAME_TYPE_MD_METH
	 and OBJ_NAME_TYPE_CIPHER_METH.	 Two additional	types are predefined
	 but not used internally: OBJ_NAME_TYPE_PKEY_METH and
	 OBJ_NAME_TYPE_COMP_METH.  All predefined types	are greater than
	 OBJ_NAME_TYPE_UNDEF and smaller than OBJ_NAME_TYPE_NUM.

     +o	 The values are	pointers.  Formally, they are of the type const	char
	 *, but	in practice, pointers of other types, for example EVP_CIPHER *
	 or EVP_MD *, are often	stored as values and cast back to the correct
	 type on retrieval.

     +o	 The array supports type-specific aliases for names.

     OBJ_NAME_add() removes the	key-value pair or alias	with the key (name,
     type) in the same way as OBJ_NAME_remove()	and inserts a key-value	pair
     with the specified	name, type, and	value.	If the bit OBJ_NAME_ALIAS is
     set in the	type argument, that bit	is cleared before using	the type and
     the key (name, type) becomes an alias for the key (value, type) instead
     of	setting	a value.  It is	not checked whether the	key (value, type) al-
     ready exists.  Consequently, it is	possible to define an alias before
     setting the associated value.

     OBJ_NAME_remove() removes the key-value pair or alias with	the key	(name,
     type) from	the array, it it exists.  Otherwise, it	has no effect.	If the
     bit OBJ_NAME_ALIAS	is set in the type argument, it	is ignored and cleared
     before using the type.  If	the type is an application-defined type	added
     with OBJ_NAME_new_index() and the free_func associated with the type is
     not a NULL	pointer, it is called with the name, type, and value of	the
     key-value pair being removed or with the name, type, and alias target
     name of the alias being removed.  In typical usage, this function might
     free the name, and	it might free the value	in a type-specific way.

     OBJ_NAME_get() looks up the key (name, type), recursively resolving up to
     ten aliases if needed.  If	the bit	OBJ_NAME_ALIAS is set in the type ar-
     gument, it	is cleared before using	the type, processing of	aliases	is
     disabled, and if (name, type) is an alias,	the target name	of the alias
     is	returned instead of a value.

     OBJ_NAME_new_index() assigns the smallest unassigned positive integer
     number to represent a new,	application-defined type.  The three function
     pointers will be used, respectively, to hash a name for this type,	to
     compare two names for this	type, and to free the contents of a key-value
     pair holding the given name, type,	and value.  If the hash_func argument
     is	a NULL pointer,	lh_strhash(3) is used instead.	If the cmp_func	argu-
     ment is a NULL pointer, strcmp(3) is used instead.	 If the	free_func ar-
     gument is a NULL pointer, the name	and value pointers contained in	the
     key-value pair are	not freed, only	the structure representing the pair
     itself is.	 This default behaviour	is also	used for the built-in types.

     OBJ_NAME_init() initializes the array.  After initialization, the array
     is	empty.	Calling	OBJ_NAME_init()	when the array is already initialized
     has no effect.  Application programs do not need to call this function
     because OBJ_NAME_add() and	OBJ_NAME_get() automatically call it whenever
     needed.

     OBJ_NAME_cleanup()	removes	all key-value pairs and	aliases	of the given
     type from the array by calling OBJ_NAME_remove() on every such pair and
     alias.  If	the type argument is negative, it removes all key-value	pairs
     and aliases of any	type and also reverses all effects of
     OBJ_NAME_new_index() and OBJ_NAME_init(), in particular resetting the
     list of types to the predefined types and releasing all memory reserved
     by	these functions.

     The OBJ_NAME structure represents one key-value pair or one alias with
     the key (name, type).  If the alias field is 0, the data field contains
     the value;	otherwise, it contains the alias target	name.

     OBJ_NAME_do_all() calls fn	on every pair and alias	in the array that has
     the given type, also passing the arg pointer.  OBJ_NAME_do_all_sorted()
     is	similar	except that it processes the pairs and aliases in lexico-
     graphic order of their names as determined	by strcmp(3), ignoring any
     cmp_func that may be defined for the type.

RETURN VALUES
     OBJ_NAME_add() and	OBJ_NAME_init()	return 1 on success or 0 if memory al-
     location fails.

     OBJ_NAME_remove() returns 1 if one	key-value pair or alias	was removed or
     0 otherwise.

     OBJ_NAME_get() returns the	value associated with the key (name, type) or
     NULL if name is NULL, if the array	does not contain a value for this key,
     or	if more	than ten aliases are encountered before	finding	a value.

     OBJ_NAME_new_index() returns a positive integer greater than or equal to
     OBJ_NAME_TYPE_NUM representing the	new type or 0 if memory	allocation
     fails.

SEE ALSO
     EVP_cleanup(3), EVP_get_cipherbyname(3), EVP_get_digestbyname(3),
     lh_new(3),	OBJ_add_sigid(3), OBJ_create(3), OBJ_nid2obj(3)

BUGS
     Calling OBJ_NAME_get() with the bit OBJ_NAME_ALIAS	is not very useful be-
     cause there is no way to tell whether the returned	pointer	points to a
     value or to a name, short of calling the function again without setting
     the bit and comparing the two returned pointers.

     The free_func has no way to tell whether its value	argument is indeed of
     the given type or whether it is merely the	target name of an alias.  Con-
     sequently,	to use values of a type	that requires more cleanup than	merely
     calling free(3) on	it, instances of the type need to begin	with a magic
     number or string that cannot occur	at the beginning of a name.

     OBJ_NAME_do_all_sorted() is unable	to report errors.  If memory alloca-
     tions fails, it does nothing at all without telling the caller about the
     problem.

FreeBSD	13.0		       December	18, 2021		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OBJ_NAME_add&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help