doc/internal/man3/ossl_lib_ctx_get_data.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree,
   6 ossl_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
  24 ossl_lib_ctx_run_once() is used to run some initialisation routine I<run_once_fn>
  25 exactly once per library context I<ctx> object. Each initialisation routine
  26 should be allocate a unique run once index in cryptlib.h.
  27
  28 Any resources allocated via a run once initialisation routine can be cleaned up
  29 using ossl_lib_ctx_onfree(). This associates an "on free" routine I<onfreefn> with
  30 the library context I<ctx>. When I<ctx> is freed all associated "on free"
  31 routines are called.
  32
  33 ossl_lib_ctx_is_child() returns 1 if this library context is a child and 0
  34 otherwise.
  35
  36 ossl_lib_ctx_get_data() allows different parts of the library to retrieve
  37 pointers to structures used in diverse parts of the library. The lifetime of
  38 these structures is managed by B<OSSL_LIB_CTX>. The different objects which can
  39 be retrieved are specified with the given argument I<index>. The valid values of
  40 I<index> are specified in cryptlib.h.
  41
  42 =head1 RETURN VALUES
  43
  44 ossl_lib_ctx_get_data() returns a pointer on success, or NULL on
  45 failure.
  46
  47 =head1 EXAMPLES
  48
  49 =head2 Usage
  50
  51 To obtain a pointer for an object managed by the library context, simply do
  52 this:
  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
  86 L<OSSL_LIB_CTX(3)>
  87
  88 =head1 COPYRIGHT
  89
  90 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
  91
  92 Licensed under the Apache License 2.0 (the "License").  You may not use
  93 this file except in compliance with the License.  You can obtain a copy
  94 in the file LICENSE in the source distribution or at
  95 L<https://www.openssl.org/source/license.html>.
  96
  97 =cut