"Fossies" - the Fresh Open Source Software Archive

Member "libressl-2.9.2/man/ENGINE_ctrl.3" (4 Dec 2018, 10857 Bytes) of package /linux/misc/libressl-2.9.2.tar.gz:


Caution: As a special service "Fossies" has tried to format the requested manual source page into HTML format but links to other man pages may be missing or even errorneous. Alternatively you can here view or download the uninterpreted manual source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

ENGINE_CTRL(3) BSD 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 reponsability 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 command 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 terminating 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 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_NEXT_CMD_TYPE

Return the positive command number of the next user-defined command after the user-defined command with the number i, or a number 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 command 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 particular, 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 compatibility.

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 reference 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 executable 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.

BSD April 19, 2018 BSD