lib/libcrypto/man/ENGINE_init.3

   1 .\" $OpenBSD: ENGINE_init.3,v 1.2 2018/04/18 03:39:22 schwarze Exp $
   2 .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .Dd $Mdocdate: April 18 2018 $
  17 .Dt ENGINE_INIT 3
  18 .Os
  19 .Sh NAME
  20 .Nm ENGINE_init ,
  21 .Nm ENGINE_finish ,
  22 .Nm ENGINE_set_init_function ,
  23 .Nm ENGINE_set_finish_function ,
  24 .Nm ENGINE_get_init_function ,
  25 .Nm ENGINE_get_finish_function
  26 .Nd initialize ENGINE objects
  27 .Sh SYNOPSIS
  28 .In openssl/engine.h
  29 .Ft int
  30 .Fo ENGINE_init
  31 .Fa "ENGINE *e"
  32 .Fc
  33 .Ft int
  34 .Fo ENGINE_finish
  35 .Fa "ENGINE *e"
  36 .Fc
  37 .Ft typedef int
  38 .Fo (*ENGINE_GEN_INT_FUNC_PTR)
  39 .Fa "ENGINE *e"
  40 .Fc
  41 .Ft int
  42 .Fo ENGINE_set_init_function
  43 .Fa "ENGINE *e"
  44 .Fa "ENGINE_GEN_INT_FUNC_PTR init_f"
  45 .Fc
  46 .Ft int
  47 .Fo ENGINE_set_finish_function
  48 .Fa "ENGINE *e"
  49 .Fa "ENGINE_GEN_INT_FUNC_PTR finish_f"
  50 .Fc
  51 .Ft ENGINE_GEN_INT_FUNC_PTR
  52 .Fo ENGINE_get_init_function
  53 .Fa "const ENGINE *e"
  54 .Fc
  55 .Ft ENGINE_GEN_INT_FUNC_PTR
  56 .Fo ENGINE_get_finish_function
  57 .Fa "const ENGINE *e"
  58 .Fc
  59 .Sh DESCRIPTION
  60 .Fn ENGINE_init
  61 initializes
  62 .Fa e
  63 by calling the
  64 .Fa init_f
  65 previously installed with
  66 .Fn ENGINE_set_init_function ,
  67 if any.
  68 In case of success, it also increments both the structural
  69 and the functional reference count by 1.
  70 If no
  71 .Fa init_f
  72 was installed,
  73 .Fn ENGINE_init
  74 always succeeds.
  75 Calling
  76 .Fn ENGINE_init
  77 again after it already succeeded always succeeds, but has no effect
  78 except that it increments both the structural and the functional
  79 reference count by 1.
  80 .Pp
  81 .Fn ENGINE_finish
  82 decrements the functional reference count by 1.
  83 When it reaches 0, it calls the
  84 .Fa finish_f
  85 previously installed with
  86 .Fn ENGINE_set_finish_function ,
  87 if any.
  88 If no
  89 .Fa finish_f
  90 was installed,
  91 .Fn ENGINE_finish
  92 always succeeds.
  93 Unless
  94 .Fa finish_f
  95 fails,
  96 .Fn ENGINE_finish
  97 also calls
  98 .Xr ENGINE_free 3 .
  99 .Pp
 100 .Fn ENGINE_init
 101 is internally called by the functions documented in the
 102 .Xr ENGINE_get_default_RSA 3
 103 manual page.
 104 .Sh RETURN VALUES
 105 .Fn ENGINE_init
 106 and
 107 .Fn ENGINE_finish
 108 return 1 on success or 0 on error.
 109 .Pp
 110 .Fn ENGINE_set_init_function
 111 and
 112 .Fn ENGINE_set_finish_function
 113 always return 1.
 114 .Pp
 115 .Fn ENGINE_get_init_function
 116 and
 117 .Fn ENGINE_get_finish_function
 118 return a function pointer to the respective callback, or
 119 .Dv NULL
 120 if none is installed.
 121 .Sh SEE ALSO
 122 .Xr ENGINE_add 3 ,
 123 .Xr ENGINE_ctrl 3 ,
 124 .Xr ENGINE_get_default_RSA 3 ,
 125 .Xr ENGINE_new 3 ,
 126 .Xr ENGINE_register_RSA 3 ,
 127 .Xr ENGINE_set_default 3 ,
 128 .Xr ENGINE_set_flags 3 ,
 129 .Xr ENGINE_set_RSA 3 ,
 130 .Xr ENGINE_unregister_RSA 3
 131 .Sh HISTORY
 132 These functions first appeared in OpenSSL 0.9.7
 133 and have been available since
 134 .Ox 2.9 .