DragonFly On-Line Manual Pages

ENGINE_NEW(3)	      DragonFly Library Functions Manual	 ENGINE_NEW(3)

NAME
     ENGINE_new, ENGINE_up_ref, ENGINE_free, ENGINE_set_destroy_function,
     ENGINE_get_destroy_function -- create and destroy ENGINE objects

SYNOPSIS
     #include <openssl/engine.h>

     ENGINE *
     ENGINE_new(void);

     int
     ENGINE_up_ref(ENGINE *e);

     int
     ENGINE_free(ENGINE *e);

     typedef int
     (*ENGINE_GEN_INT_FUNC_PTR)(ENGINE *e);

     int
     ENGINE_set_destroy_function(ENGINE *e,
	 ENGINE_GEN_INT_FUNC_PTR destroy_f);

     ENGINE_GEN_INT_FUNC_PTR
     ENGINE_get_destroy_function(const ENGINE *e);

DESCRIPTION
     ENGINE objects can be used to provide alternative implementations of
     cryptographic algorithms, to support additional algorithms, to support
     cryptographic hardware, and to switch among alternative implementations
     of algorithms at run time.  LibreSSL generally avoids engines and prefers
     providing cryptographic functionality in the crypto library itself.

     ENGINE_new() allocates and initializes an empty ENGINE object and sets
     its structural reference count to 1 and its functional reference count to
     0.  For more information about the functional reference count, see the
     ENGINE_init(3) manual page.

     Many functions increment the structural reference count by 1 when suc-
     cessful.  Some of them, including ENGINE_get_first(3),
     ENGINE_get_last(3), ENGINE_get_next(3), ENGINE_get_prev(3), and
     ENGINE_by_id(3), do so because they return a structural reference to the
     user.  Other functions, including ENGINE_add(3), ENGINE_init(3),
     ENGINE_get_cipher_engine(3), ENGINE_get_digest_engine(3), and the
     ENGINE_get_default_RSA(3) and ENGINE_set_default(3) families of functions
     do so when they store a structural refence internally.

     ENGINE_up_ref() explicitly increment the structural reference count by 1.

     ENGINE_free() decrements the structural reference count by 1, and if it
     reaches 0, the optional destroy_f previously installed with
     ENGINE_set_destroy_function() is called, if one is installed, and both
     the memory used internally by e and e itself are freed.  If e is a NULL
     pointer, no action occurs.

     Many functions internally call the equivalent of ENGINE_free().  Some of
     them, including ENGINE_get_next(3) and ENGINE_get_prev(3), thus invali-
     date the structural reference passed in by the user.  Other functions,
     including ENGINE_finish(3), ENGINE_remove(3), and the
     ENGINE_set_default(3) family of functions do so when an internally stored
     structural reference is no longer needed.

     ENGINE_set_destroy_function() installs a callback function that will be
     called by ENGINE_free(), but only when e actually gets destroyed, not
     when only its reference count gets decremented.  The value returned from
     the destroy_f will be ignored.

RETURN VALUES
     ENGINE_new() returns a structural reference to the new ENGINE object or
     NULL if an error occurs.

     ENGINE_up_ref() returns 0 if e is NULL and 1 otherwise.

     ENGINE_free() and ENGINE_set_destroy_function() always return 1.

     ENGINE_get_destroy_function() returns a function pointer to the callback,
     or NULL if none is installed.

SEE ALSO
     ENGINE_add(3), ENGINE_ctrl(3), ENGINE_get_default_RSA(3), ENGINE_init(3),
     ENGINE_register_all_RSA(3), ENGINE_register_RSA(3),
     ENGINE_set_default(3), ENGINE_set_flags(3), ENGINE_set_RSA(3),
     ENGINE_unregister_RSA(3)

HISTORY
     ENGINE_new() and ENGINE_free() first appeared in OpenSSL 0.9.7 and have
     been available since OpenBSD 2.9.

     ENGINE_set_destroy_function() and ENGINE_get_destroy_function() first
     appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2.

     ENGINE_up_ref() first appeared in OpenSSL 0.9.7 and has been available
     since OpenBSD 3.4.

DragonFly 5.5			April 18, 2018			 DragonFly 5.5