OpenBSD manual page server

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:

• 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.
• 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.
• 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) already 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, if 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 argument, 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 argument is a NULL pointer, strcmp(3) is used instead. If the free_func argument 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 lexicographic 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 allocation 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 because 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. Consequently, 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 allocations fails, it does nothing at all without telling the caller about the problem.