Rewrite the ENGINE_*(3) documentation from scratch (step 1,

covering 60% of the documented functions).  The old, abominable
engine(3) manual page shall die soon.

1 files changed, 122 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/ENGINE_init.3 b/src/lib/libcrypto/man/ENGINE_init.3
new file mode 100644
index 0000000000..d94c6a8b66
--- /dev/null
+++ b/src/lib/libcrypto/man/ENGINE_init.3
@@ -0,0 +1,122 @@
+.\" $OpenBSD: ENGINE_init.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $
+.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: April 15 2018 $
+.Dt ENGINE_INIT 3
+.Os
+.Sh NAME
+.Nm ENGINE_init ,
+.Nm ENGINE_finish ,
+.Nm ENGINE_set_init_function ,
+.Nm ENGINE_set_finish_function ,
+.Nm ENGINE_get_init_function ,
+.Nm ENGINE_get_finish_function
+.Nd initialize ENGINE objects
+.Sh SYNOPSIS
+.In openssl/engine.h
+.Ft int
+.Fo ENGINE_init
+.Fa "ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_finish
+.Fa "ENGINE *e"
+.Fc
+.Ft typedef int
+.Fo (*ENGINE_GEN_INT_FUNC_PTR)
+.Fa "ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_set_init_function
+.Fa "ENGINE *e"
+.Fa "ENGINE_GEN_INT_FUNC_PTR init_f"
+.Fc
+.Ft int
+.Fo ENGINE_set_finish_function
+.Fa "ENGINE *e"
+.Fa "ENGINE_GEN_INT_FUNC_PTR finish_f"
+.Fc
+.Ft ENGINE_GEN_INT_FUNC_PTR
+.Fo ENGINE_get_init_function
+.Fa "const ENGINE *e"
+.Fc
+.Ft ENGINE_GEN_INT_FUNC_PTR
+.Fo ENGINE_get_finish_function
+.Fa "const ENGINE *e"
+.Fc
+.Sh DESCRIPTION
+.Fn ENGINE_init
+initializes
+.Fa e
+by calling the
+.Fa init_f
+previously installed with
+.Fn ENGINE_set_init_function ,
+if any.
+In case of success, it also increments both the structural
+and the functional reference count by 1.
+If no
+.Fa init_f
+was installed,
+.Fn ENGINE_init
+always succeeds.
+Calling
+.Fn ENGINE_init
+again after it already succeeded always succeeds, but has no effect
+except that it increments both the structural and the functional
+reference count by 1.
+.Pp
+.Fn ENGINE_finish
+decrements the functional reference count by 1.
+When it reaches 0, it calls the
+.Fa finish_f
+previously installed with
+.Fn ENGINE_set_finish_function ,
+if any.
+If no
+.Fa finish_f
+was installed,
+.Fn ENGINE_finish
+always succeeds.
+Unless
+.Fa finish_f
+fails,
+.Fn ENGINE_finish
+also calls
+.Xr ENGINE_free 3 .
+.Pp
+.Fn ENGINE_init
+is internally called by the functions documented in the
+.Xr ENGINE_get_default_RSA 3
+manual page.
+.Sh RETURN VALUES
+.Fn ENGINE_init
+and
+.Fn ENGINE_finish
+return 1 on success or 0 on error.
+.Pp
+.Fn ENGINE_set_init_function
+and
+.Fn ENGINE_set_finish_function
+always return 1.
+.Pp
+.Fn ENGINE_get_init_function
+and
+.Fn ENGINE_get_finish_function
+return a function pointer to the respective callback, or
+.Dv NULL
+if none is installed.
+.Sh SEE ALSO
+.Xr ENGINE_get_default_RSA 3