DragonFly On-Line Manual Pages
ENGINE_CTRL(3) DragonFly Library Functions Manual ENGINE_CTRL(3)
NAME
ENGINE_ctrl, ENGINE_cmd_is_executable, ENGINE_ctrl_cmd,
ENGINE_ctrl_cmd_string, ENGINE_set_ctrl_function,
ENGINE_get_ctrl_function, ENGINE_set_cmd_defns, ENGINE_get_cmd_defns --
control commands for ENGINE objects
SYNOPSIS
#include <openssl/engine.h>
int
ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));
int
ENGINE_cmd_is_executable(ENGINE *e, int cmd);
int
ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, long i, void *p,
void (*f)(void), int cmd_optional);
int
ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
int cmd_optional);
typedef int
(*ENGINE_CTRL_FUNC_PTR)(ENGINE *e, int cmd, long i, void *p,
void (*f)(void));
int
ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
ENGINE_CTRL_FUNC_PTR
ENGINE_get_ctrl_function(const ENGINE *e);
int
ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
const ENGINE_CMD_DEFN *
ENGINE_get_cmd_defns(const ENGINE *e);
DESCRIPTION
ENGINE_ctrl() calls the built-in or user-defined cmd for the engine e,
passing the arguments i and p.
User-defined commands can be used before ENGINE_init(3) to provide data
required for initialization or at any time to modify the behaviour of an
engine.
Most built-in commands operate on user-defined commands installed with
ENGINE_set_cmd_defns(), either using the p argument to indicate the user-
defined command with the command name cmd_name or using the i argument to
indicate the user-defined command with the command number cmd_num. The
cmd arguments to call the built-in commands are as follows:
ENGINE_CTRL_GET_CMD_FLAGS
Return the cmd_flags of the user-defined command with the number
i, or a number less than or equal to 0 if an error occurs or the
command number does not exist. A return value of 0 indicates
failure if e is NULL or has a reference count of 0, or success if
e is valid.
ENGINE_CTRL_GET_CMD_FROM_NAME
Return the positive command number of the user-defined command
with the name p, or a number less than or equal to 0 if an error
occurs or no matching name is found.
ENGINE_CTRL_GET_DESC_FROM_CMD
Copy the description of the user-defined command with the number
i into the buffer p and NUL-terminate it. It is the reponsabil-
ity of the caller to make sure that the buffer p is large enough,
either by calling ENGINE_CTRL_GET_DESC_LEN_FROM_CMD first or
using knowledge about the array passed to ENGINE_set_cmd_defns().
The return value is the number of bytes written including the
terminating NUL byte, or a number less than or equal to 0 if an
error occurs.
ENGINE_CTRL_GET_DESC_LEN_FROM_CMD
Return the length in bytes excluding the terminating NUL byte of
the description of the user-defined command with the number i, or
a number less than or equal to 0 if an error occurs. A return
value of 0 indicates failure if e is NULL or has a reference
count of 0, or success if e is valid.
ENGINE_CTRL_GET_FIRST_CMD_TYPE
Return the positive command number of the first user-defined com-
mand installed with ENGINE_set_cmd_defns() or a number less than
or equal to 0 if an error occurs or no user-defined command has
been installed.
ENGINE_CTRL_GET_NAME_FROM_CMD
Copy the name of the user-defined command with the number i into
the buffer p and NUL-terminate it. It is the reponsability of
the caller to make sure that the buffer p is large enough, either
by calling ENGINE_CTRL_GET_NAME_LEN_FROM_CMD first or using
knowledge about the array passed to ENGINE_set_cmd_defns(). The
return value is the number of bytes written including the termi-
nating NUL byte, or a number less than or equal to 0 if an error
occurs.
ENGINE_CTRL_GET_NAME_LEN_FROM_CMD
Return the length in bytes excluding the terminating NULL byte of
the name of the user-defined command with the number i, or a num-
ber less than or equal to 0 if an error occurs. A return value
of 0 indicates failure if e is NULL or has a reference count of
0, or success if e is valid.
ENGINE_CTRL_GET_NEXT_CMD_TYPE
Return the positive command number of the next user-defined com-
mand after the user-defined command with the number i, or a num-
ber less than or equal to 0 if an error occurs or if i is the
last user-defined command. Together with
ENGINE_CTRL_GET_FIRST_CMD_TYPE, this can be used to iterate the
user-defined commands installed with ENGINE_set_cmd_defns().
ENGINE_CTRL_HAS_CTRL_FUNCTION
Return 1 if e has its own ctrl_f installed with
ENGINE_set_ctrl_function() or 0 otherwise.
ENGINE_ctrl_cmd() translates the cmd_name of a user-defined command to a
cmd number and calls ENGINE_ctrl() on it. If cmd_optional is non-zero,
lack of a ctrl_f in e and translation failure with
ENGINE_CTRL_GET_CMD_FROM_NAME are considered success, and the command has
no effect. Otherwise, these problems cause ENGINE_ctrl_cmd() to fail.
Neither ENGINE_ctrl() nor ENGINE_ctrl_cmd() ever call the f callback, but
merely pass it on as an argument to the engine-specific ctrl_f control
function. It is up to ctrl_f how to use it, or alternatively to ignore
it as well.
ENGINE_ctrl_cmd_string() translates the cmd_name of a user-defined com-
mand to a cmd number. If that command has the ENGINE_CMD_FLAG_NO_INPUT
flag set, arg must be NULL and ENGINE_ctrl() is called with i set to 0
and p set to NULL. Otherwise, arg must not be NULL. If the command
accepts string input, i is set to 0 and arg is passed as the p argument
to ENGINE_ctrl(). Otherwise, arg is converted with strtol(3) and passed
as the i argument to ENGINE_ctrl(), setting p to NULL.
ENGINE_set_ctrl_function() installs ctrl_f as the engine-specific control
function for e. Future calls to ENGINE_ctrl() will call that function,
passing on their arguments unchanged, if the cmd is not built-in to the
library or if the ENGINE_FLAGS_MANUAL_CMD_CTRL flag is set in e. Let the
ctrl_f return positive values on success or negative values on failure.
Avoid return values of 0 because they cause dangerous ambiguity. In par-
ticular, ENGINE_ctrl_cmd() and ENGINE_ctrl_cmd_string() cannot be used
with user-defined commands that may return 0 on success.
ENGINE_set_cmd_defns() install an array of command definitions in e.
The structure ENGINE_CMD_DEFN has the following fields:
unsigned int cmd_num
A positive, unique, monotonically increasing command number.
Avoid using numbers below ENGINE_CMD_BASE.
const char *cmd_name
The unique name of the command.
const char *cmd_desc
A short description of the command.
unsigned int cmd_flags
The bitwise OR of zero or more of the following flags:
ENGINE_CMD_FLAG_NUMERIC
The command uses i.
ENGINE_CMD_FLAG_STRING
The command uses p.
ENGINE_CMD_FLAG_NO_INPUT
The command neither uses i nor p.
ENGINE_CMD_FLAG_INTERNAL
This flag has no effect and is only provided for compati-
bility.
The last element of defns does not specify a command, but must have a
cmd_num of 0 and a cmd_name of NULL to indicate the end of the array.
RETURN VALUES
For ENGINE_ctrl(), positive return values indicate success and negative
return values indicate failure. The meaning of a zero return value
depends on the particular cmd and may indicate both success and failure,
which is pathetic.
Regardless of the cmd, ENGINE_ctrl() returns 0 if e is NULL or has a ref-
erence count of 0. This is quite unfortunate for commands like
ENGINE_CTRL_GET_CMD_FLAGS where 0 may indicate success, so make sure e is
valid before issuing a control command.
For built-in commands except ENGINE_CTRL_HAS_CTRL_FUNCTION, ENGINE_ctrl()
returns -1 if ENGINE_FLAGS_MANUAL_CMD_CTRL is set but no ctrl_f has been
installed with ENGINE_set_ctrl_function().
For commands that are not built in, ENGINE_ctrl() returns 0 if no ctrl_f
has been installed with ENGINE_set_ctrl_function().
ENGINE_cmd_is_executable() returns 1 if the user-defined cmd is exe-
cutable and has at least one of the flags ENGINE_CMD_FLAG_NUMERIC,
ENGINE_CMD_FLAG_STRING, and ENGINE_CMD_FLAG_NO_INPUT set, or 0 otherwise.
ENGINE_ctrl_cmd() and ENGINE_ctrl_cmd_string() return 1 on success or 0
on error.
ENGINE_set_ctrl_function() and ENGINE_set_cmd_defns() always return 1.
ENGINE_get_ctrl_function() returns a pointer to the function ctrl_f
installed with ENGINE_set_ctrl_function(), or NULL if none has been
installed.
ENGINE_get_cmd_defns() returns the array of command definitions installed
in e or NULL if none is installed.
SEE ALSO
ENGINE_add(3), ENGINE_init(3), ENGINE_new(3), ENGINE_register_RSA(3),
ENGINE_set_flags(3), ENGINE_set_RSA(3)
HISTORY
ENGINE_ctrl(), ENGINE_set_ctrl_function(), and ENGINE_get_ctrl_function()
first appeared in OpenSSL 0.9.7 and have been available since
OpenBSD 2.9.
ENGINE_cmd_is_executable(), ENGINE_ctrl_cmd(), ENGINE_ctrl_cmd_string(),
ENGINE_set_cmd_defns(), and ENGINE_get_cmd_defns() first appeared in
OpenSSL 0.9.7 and have been available since OpenBSD 3.2.
DragonFly 5.5 April 19, 2018 DragonFly 5.5