1=pod
2
3=head1 NAME
4
5ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree,
6ossl_lib_ctx_is_child
7- internal OSSL_LIB_CTX routines
8
9=head1 SYNOPSIS
10
11 #include <openssl/types.h>
12 #include "internal/cryptlib.h"
13
14 void *ossl_lib_ctx_get_data(OSSL_LIB_CTX *ctx, int index);
15
16 int ossl_lib_ctx_run_once(OSSL_LIB_CTX *ctx, unsigned int idx,
17                           ossl_lib_ctx_run_once_fn run_once_fn);
18 int ossl_lib_ctx_onfree(OSSL_LIB_CTX *ctx, ossl_lib_ctx_onfree_fn onfreefn);
19
20 int ossl_lib_ctx_is_child(OSSL_LIB_CTX *ctx);
21
22=head1 DESCRIPTION
23
24ossl_lib_ctx_run_once() is used to run some initialisation routine I<run_once_fn>
25exactly once per library context I<ctx> object. Each initialisation routine
26should be allocate a unique run once index in cryptlib.h.
27
28Any resources allocated via a run once initialisation routine can be cleaned up
29using ossl_lib_ctx_onfree(). This associates an "on free" routine I<onfreefn> with
30the library context I<ctx>. When I<ctx> is freed all associated "on free"
31routines are called.
32
33ossl_lib_ctx_is_child() returns 1 if this library context is a child and 0
34otherwise.
35
36ossl_lib_ctx_get_data() allows different parts of the library to retrieve
37pointers to structures used in diverse parts of the library. The lifetime of
38these structures is managed by B<OSSL_LIB_CTX>. The different objects which can
39be retrieved are specified with the given argument I<index>. The valid values of
40I<index> are specified in cryptlib.h.
41
42=head1 RETURN VALUES
43
44ossl_lib_ctx_get_data() returns a pointer on success, or NULL on
45failure.
46
47=head1 EXAMPLES
48
49=head2 Usage
50
51To obtain a pointer for an object managed by the library context, simply do
52this:
53
54 /*
55  * ctx is received from a caller,
56  */
57 FOO *data = ossl_lib_ctx_get_data(ctx, OSSL_LIB_CTX_FOO_INDEX);
58
59=head2 Run Once
60
61 void foo_cleanup(OSSL_LIB_CTX *ctx)
62 {
63     /* Free foo resources associated with ctx */
64 }
65
66 static ossl_lib_ctx_run_once_fn do_foo_init;
67 static int do_foo_init(OSSL_LIB_CTX *ctx)
68 {
69     /* Allocate and initialise some foo resources and associated with ctx */
70     return ossl_lib_ctx_onfree(ctx, &foo_cleanup)
71 }
72
73 int foo_some_function(OSSL_LIB_CTX *ctx)
74 {
75    if (!ossl_lib_ctx_run_once(ctx,
76                               OSSL_LIB_CTX_FOO_RUN_ONCE_INDEX,
77                               do_foo_init))
78        return 0;
79
80    /* Do some work using foo resources in ctx */
81 }
82
83
84=head1 SEE ALSO
85
86L<OSSL_LIB_CTX(3)>
87
88=head1 COPYRIGHT
89
90Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
91
92Licensed under the Apache License 2.0 (the "License").  You may not use
93this file except in compliance with the License.  You can obtain a copy
94in the file LICENSE in the source distribution or at
95L<https://www.openssl.org/source/license.html>.
96
97=cut
98