diff options
Diffstat (limited to 'doc/internal/man3/ossl_lib_ctx_get_data.pod')
-rw-r--r-- | doc/internal/man3/ossl_lib_ctx_get_data.pod | 81 |
1 files changed, 12 insertions, 69 deletions
diff --git a/doc/internal/man3/ossl_lib_ctx_get_data.pod b/doc/internal/man3/ossl_lib_ctx_get_data.pod index faedf7275f..2ffd000da1 100644 --- a/doc/internal/man3/ossl_lib_ctx_get_data.pod +++ b/doc/internal/man3/ossl_lib_ctx_get_data.pod @@ -11,14 +11,7 @@ ossl_lib_ctx_is_child #include <openssl/types.h> #include "internal/cryptlib.h" - typedef struct ossl_lib_ctx_method { - int priority; - void *(*new_func)(OSSL_LIB_CTX *ctx); - void (*free_func)(void *); - } OSSL_LIB_CTX_METHOD; - - void *ossl_lib_ctx_get_data(OSSL_LIB_CTX *ctx, int index, - const OSSL_LIB_CTX_METHOD *meth); + void *ossl_lib_ctx_get_data(OSSL_LIB_CTX *ctx, int index); int ossl_lib_ctx_run_once(OSSL_LIB_CTX *ctx, unsigned int idx, ossl_lib_ctx_run_once_fn run_once_fn); @@ -28,38 +21,24 @@ ossl_lib_ctx_is_child =head1 DESCRIPTION -Internally, the OpenSSL library context B<OSSL_LIB_CTX> is implemented -as a B<CRYPTO_EX_DATA>, which allows data from diverse parts of the -library to be added and removed dynamically. -Each such data item must have a corresponding CRYPTO_EX_DATA index -associated with it. Unlike normal CRYPTO_EX_DATA objects we use static indexes -to identify data items. These are mapped transparently to CRYPTO_EX_DATA dynamic -indexes internally to the implementation. -See the example further down to see how that's done. - -ossl_lib_ctx_get_data() is used to retrieve a pointer to the data in -the library context I<ctx> associated with the given I<index>. An -OSSL_LIB_CTX_METHOD must be defined and given in the I<meth> parameter. The index -for it should be defined in cryptlib.h. The functions through the method are -used to create or free items that are stored at that index whenever a library -context is created or freed, meaning that the code that use a data item of that -index doesn't have to worry about that, just use the data available. - -Deallocation of an index happens automatically when the library -context is freed. - -ossl_lib_ctx_run_once is used to run some initialisation routine I<run_once_fn> +ossl_lib_ctx_run_once() is used to run some initialisation routine I<run_once_fn> exactly once per library context I<ctx> object. Each initialisation routine should be allocate a unique run once index in cryptlib.h. Any resources allocated via a run once initialisation routine can be cleaned up -using ossl_lib_ctx_onfree. This associates an "on free" routine I<onfreefn> with +using ossl_lib_ctx_onfree(). This associates an "on free" routine I<onfreefn> with the library context I<ctx>. When I<ctx> is freed all associated "on free" routines are called. ossl_lib_ctx_is_child() returns 1 if this library context is a child and 0 otherwise. +ossl_lib_ctx_get_data() allows different parts of the library to retrieve +pointers to structures used in diverse parts of the library. The lifetime of +these structures is managed by B<OSSL_LIB_CTX>. The different objects which can +be retrieved are specified with the given argument I<index>. The valid values of +I<index> are specified in cryptlib.h. + =head1 RETURN VALUES ossl_lib_ctx_get_data() returns a pointer on success, or NULL on @@ -67,51 +46,15 @@ failure. =head1 EXAMPLES -=head2 Initialization - -For a type C<FOO> that should end up in the OpenSSL library context, a -small bit of initialization is needed, i.e. to associate a constructor -and a destructor to an index. - - typedef struct foo_st { - int i; - void *data; - } FOO; - - static void *foo_new(OSSL_LIB_CTX *ctx) - { - FOO *ptr = OPENSSL_zalloc(sizeof(*foo)); - if (ptr != NULL) - ptr->i = 42; - return ptr; - } - static void foo_free(void *ptr) - { - OPENSSL_free(ptr); - } - - /* - * Include a reference to this in the methods table in context.c - * OSSL_LIB_CTX_FOO_INDEX should be added to internal/cryptlib.h - * Priorities can be OSSL_LIB_CTX_METHOD_DEFAULT_PRIORITY, - * OSSL_LIB_CTX_METHOD_PRIORITY_1, OSSL_LIB_CTX_METHOD_PRIORITY_2, etc. - * Default priority is low (0). The higher the priority the earlier the - * method's destructor will be called when the library context is cleaned up. - */ - const OSSL_LIB_CTX_METHOD foo_method = { - OSSL_LIB_CTX_METHOD_DEFAULT_PRIORITY, - foo_new, - foo_free - }; - =head2 Usage -To get and use the data stored in the library context, simply do this: +To obtain a pointer for an object managed by the library context, simply do +this: /* * ctx is received from a caller, */ - FOO *data = ossl_lib_ctx_get_data(ctx, OSSL_LIB_CTX_FOO_INDEX, &foo_method); + FOO *data = ossl_lib_ctx_get_data(ctx, OSSL_LIB_CTX_FOO_INDEX); =head2 Run Once |