From d56c8fa8260d226f98b26f017b45b9c2b135f38d Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Wed, 18 Aug 2021 16:06:57 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20210818'. --- src/lib/libcrypto/man/ENGINE_ctrl.3 | 470 ------------------------------------ 1 file changed, 470 deletions(-) delete mode 100644 src/lib/libcrypto/man/ENGINE_ctrl.3 (limited to 'src/lib/libcrypto/man/ENGINE_ctrl.3') diff --git a/src/lib/libcrypto/man/ENGINE_ctrl.3 b/src/lib/libcrypto/man/ENGINE_ctrl.3 deleted file mode 100644 index c02e9b5a94..0000000000 --- a/src/lib/libcrypto/man/ENGINE_ctrl.3 +++ /dev/null @@ -1,470 +0,0 @@ -.\" $OpenBSD: ENGINE_ctrl.3,v 1.4 2018/04/19 18:43:58 schwarze Exp $ -.\" content checked up to: -.\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800 -.\" -.\" Copyright (c) 2018 Ingo Schwarze -.\" -.\" 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 19 2018 $ -.Dt ENGINE_CTRL 3 -.Os -.Sh NAME -.Nm ENGINE_ctrl , -.Nm ENGINE_cmd_is_executable , -.Nm ENGINE_ctrl_cmd , -.Nm ENGINE_ctrl_cmd_string , -.Nm ENGINE_set_ctrl_function , -.Nm ENGINE_get_ctrl_function , -.Nm ENGINE_set_cmd_defns , -.Nm ENGINE_get_cmd_defns -.Nd control commands for ENGINE objects -.Sh SYNOPSIS -.In openssl/engine.h -.Ft int -.Fo ENGINE_ctrl -.Fa "ENGINE *e" -.Fa "int cmd" -.Fa "long i" -.Fa "void *p" -.Fa "void (*f)(void)" -.Fc -.Ft int -.Fo ENGINE_cmd_is_executable -.Fa "ENGINE *e" -.Fa "int cmd" -.Fc -.Ft int -.Fo ENGINE_ctrl_cmd -.Fa "ENGINE *e" -.Fa "const char *cmd_name" -.Fa "long i" -.Fa "void *p" -.Fa "void (*f)(void)" -.Fa "int cmd_optional" -.Fc -.Ft int -.Fo ENGINE_ctrl_cmd_string -.Fa "ENGINE *e" -.Fa "const char *cmd_name" -.Fa "const char *arg" -.Fa "int cmd_optional" -.Fc -.Ft typedef int -.Fo (*ENGINE_CTRL_FUNC_PTR) -.Fa "ENGINE *e" -.Fa "int cmd" -.Fa "long i" -.Fa "void *p" -.Fa "void (*f)(void)" -.Fc -.Ft int -.Fo ENGINE_set_ctrl_function -.Fa "ENGINE *e" -.Fa "ENGINE_CTRL_FUNC_PTR ctrl_f" -.Fc -.Ft ENGINE_CTRL_FUNC_PTR -.Fo ENGINE_get_ctrl_function -.Fa "const ENGINE *e" -.Fc -.Ft int -.Fo ENGINE_set_cmd_defns -.Fa "ENGINE *e" -.Fa "const ENGINE_CMD_DEFN *defns" -.Fc -.Ft const ENGINE_CMD_DEFN * -.Fo ENGINE_get_cmd_defns -.Fa "const ENGINE *e" -.Fc -.Sh DESCRIPTION -.Fn ENGINE_ctrl -calls the built-in or user-defined -.Fa cmd -for the engine -.Fa e , -passing the arguments -.Fa i -and -.Fa p . -.Pp -User-defined commands can be used before -.Xr ENGINE_init 3 -to provide data required for initialization -or at any time to modify the behaviour of an engine. -.Pp -Most built-in commands operate on user-defined commands installed with -.Fn ENGINE_set_cmd_defns , -either using the -.Fa p -argument to indicate the user-defined command with the command name -.Fa cmd_name -or using the -.Fa i -argument to indicate the user-defined command with the command number -.Fa cmd_num . -The -.Fa cmd -arguments to call the built-in commands are as follows: -.Bl -tag -width Ds -.It Dv ENGINE_CTRL_GET_CMD_FLAGS -Return the -.Fa cmd_flags -of the user-defined command with the number -.Fa 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 -.Fa e -is -.Dv NULL -or has a reference count of 0, or success if -.Fa e -is valid. -.It Dv ENGINE_CTRL_GET_CMD_FROM_NAME -Return the positive command number -of the user-defined command with the name -.Fa p , -or a number less than or equal to 0 if an error occurs or no -matching name is found. -.It Dv ENGINE_CTRL_GET_DESC_FROM_CMD -Copy the description of the user-defined command with the number -.Fa i -into the buffer -.Fa p -and NUL-terminate it. -It is the reponsability of the caller to make sure that the buffer -.Fa p -is large enough, either by calling -.Dv ENGINE_CTRL_GET_DESC_LEN_FROM_CMD -first or using knowledge about the array passed to -.Fn ENGINE_set_cmd_defns . -The return value is the number of bytes written -.Em including -the terminating NUL byte, or a number less than or equal to 0 -if an error occurs. -.It Dv ENGINE_CTRL_GET_DESC_LEN_FROM_CMD -Return the length in bytes -.Em excluding -the terminating NUL byte -of the description of the user-defined command with the number -.Fa i , -or a number less than or equal to 0 if an error occurs. -A return value of 0 indicates failure if -.Fa e -is -.Dv NULL -or has a reference count of 0, or success if -.Fa e -is valid. -.It Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE -Return the positive command number -of the first user-defined command installed with -.Fn 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. -.It Dv ENGINE_CTRL_GET_NAME_FROM_CMD -Copy the name of the user-defined command with the number -.Fa i -into the buffer -.Fa p -and NUL-terminate it. -It is the reponsability of the caller to make sure that the buffer -.Fa p -is large enough, either by calling -.Dv ENGINE_CTRL_GET_NAME_LEN_FROM_CMD -first or using knowledge about the array passed to -.Fn ENGINE_set_cmd_defns . -The return value is the number of bytes written -.Em including -the terminating NUL byte, or a number less than or equal to 0 -if an error occurs. -.It Dv ENGINE_CTRL_GET_NAME_LEN_FROM_CMD -Return the length in bytes -.Em excluding -the terminating NULL byte -of the name of the user-defined command with the number -.Fa i , -or a number less than or equal to 0 if an error occurs. -A return value of 0 indicates failure if -.Fa e -is -.Dv NULL -or has a reference count of 0, or success if -.Fa e -is valid. -.It Dv 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 -.Fa i , -or a number less than or equal to 0 if an error occurs or if -.Fa i -is the last user-defined command. -Together with -.Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE , -this can be used to iterate the user-defined commands installed with -.Fn ENGINE_set_cmd_defns . -.It Dv ENGINE_CTRL_HAS_CTRL_FUNCTION -Return 1 if -.Fa e -has its own -.Fa ctrl_f -installed with -.Fn ENGINE_set_ctrl_function -or 0 otherwise. -.El -.Pp -.Fn ENGINE_ctrl_cmd -translates the -.Fa cmd_name -of a user-defined command to a -.Fa cmd -number and calls -.Fn ENGINE_ctrl -on it. -If -.Fa cmd_optional -is non-zero, lack of a -.Fa ctrl_f -in -.Fa e -and translation failure with -.Dv ENGINE_CTRL_GET_CMD_FROM_NAME -are considered success, and the command has no effect. -Otherwise, these problems cause -.Fn ENGINE_ctrl_cmd -to fail. -.Pp -Neither -.Fn ENGINE_ctrl -nor -.Fn ENGINE_ctrl_cmd -ever call the -.Fa f -callback, but merely pass it on as an argument to the engine-specific -.Fa ctrl_f -control function. -It is up to -.Fa ctrl_f -how to use it, or alternatively to ignore it as well. -.Pp -.Fn ENGINE_ctrl_cmd_string -translates the -.Fa cmd_name -of a user-defined command to a -.Fa cmd -number. -If that command has the -.Dv ENGINE_CMD_FLAG_NO_INPUT -flag set, -.Fa arg -must be -.Dv NULL -and -.Fn ENGINE_ctrl -is called with -.Fa i -set to 0 and -.Fa p -set to -.Dv NULL . -Otherwise, -.Fa arg -must not be -.Dv NULL . -If the command accepts string input, -.Fa i -is set to 0 and -.Fa arg -is passed as the -.Fa p -argument to -.Fn ENGINE_ctrl . -Otherwise, -.Fa arg -is converted with -.Xr strtol 3 -and passed as the -.Fa i -argument to -.Fn ENGINE_ctrl , -setting -.Fa p -to -.Dv NULL . -.Pp -.Fn ENGINE_set_ctrl_function -installs -.Fa ctrl_f -as the engine-specific control function for -.Fa e . -Future calls to -.Fn ENGINE_ctrl -will call that function, passing on their arguments unchanged, if the -.Fa cmd -is not built-in to the library or if the -.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL -flag is set in -.Fa e . -Let the -.Fa ctrl_f -return positive values on success or negative values on failure. -Avoid return values of 0 because they cause dangerous ambiguity. -In particular, -.Fn ENGINE_ctrl_cmd -and -.Fn ENGINE_ctrl_cmd_string -cannot be used with user-defined commands -that may return 0 on success. -.Pp -.Fn ENGINE_set_cmd_defns -install an array of command definitions in -.Fa e . -.Pp -The structure -.Vt ENGINE_CMD_DEFN -has the following fields: -.Bl -tag -width Ds -.It Fa "unsigned int cmd_num" -A positive, unique, monotonically increasing command number. -Avoid using numbers below -.Dv ENGINE_CMD_BASE . -.It Fa "const char *cmd_name" -The unique name of the command. -.It Fa "const char *cmd_desc" -A short description of the command. -.It Fa "unsigned int cmd_flags" -The bitwise OR of zero or more of the following flags: -.Bl -tag -width Ds -.It Dv ENGINE_CMD_FLAG_NUMERIC -The command uses -.Fa i . -.It Dv ENGINE_CMD_FLAG_STRING -The command uses -.Fa p . -.It Dv ENGINE_CMD_FLAG_NO_INPUT -The command neither uses -.Fa i -nor -.Fa p . -.It Dv ENGINE_CMD_FLAG_INTERNAL -This flag has no effect and is only provided for compatibility. -.El -.El -.Pp -The last element of -.Fa defns -does not specify a command, but must have a -.Fa cmd_num -of 0 and a -.Fa cmd_name -of -.Dv NULL -to indicate the end of the array. -.Sh RETURN VALUES -For -.Fn ENGINE_ctrl , -positive return values indicate success and negative return values -indicate failure. -The meaning of a zero return value depends on the particular -.Fa cmd -and may indicate both success and failure, which is pathetic. -.Pp -Regardless of the -.Fa cmd , -.Fn ENGINE_ctrl -returns 0 if -.Fa e -is -.Dv NULL -or has a reference count of 0. -This is quite unfortunate for commands like -.Dv ENGINE_CTRL_GET_CMD_FLAGS -where 0 may indicate success, so make sure -.Fa e -is valid before issuing a control command. -.Pp -For built-in commands except -.Dv ENGINE_CTRL_HAS_CTRL_FUNCTION , -.Fn ENGINE_ctrl -returns \-1 if -.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL -is set but no -.Fa ctrl_f -has been installed with -.Fn ENGINE_set_ctrl_function . -.Pp -For commands that are not built in, -.Fn ENGINE_ctrl -returns 0 if no -.Fa ctrl_f -has been installed with -.Fn ENGINE_set_ctrl_function . -.Pp -.Fn ENGINE_cmd_is_executable -returns 1 if the user-defined -.Fa cmd -is executable and has at least one of the flags -.Dv ENGINE_CMD_FLAG_NUMERIC , -.Dv ENGINE_CMD_FLAG_STRING , -and -.Dv ENGINE_CMD_FLAG_NO_INPUT -set, or 0 otherwise. -.Pp -.Fn ENGINE_ctrl_cmd -and -.Fn ENGINE_ctrl_cmd_string -return 1 on success or 0 on error. -.Pp -.Fn ENGINE_set_ctrl_function -and -.Fn ENGINE_set_cmd_defns -always return 1. -.Pp -.Fn ENGINE_get_ctrl_function -returns a pointer to the function -.Fa ctrl_f -installed with -.Fn ENGINE_set_ctrl_function , -or -.Dv NULL -if none has been installed. -.Pp -.Fn ENGINE_get_cmd_defns -returns the array of command definitions installed in -.Fa e -or -.Dv NULL -if none is installed. -.Sh SEE ALSO -.Xr ENGINE_add 3 , -.Xr ENGINE_init 3 , -.Xr ENGINE_new 3 , -.Xr ENGINE_register_RSA 3 , -.Xr ENGINE_set_flags 3 , -.Xr ENGINE_set_RSA 3 -.Sh HISTORY -.Fn ENGINE_ctrl , -.Fn ENGINE_set_ctrl_function , -and -.Fn ENGINE_get_ctrl_function -first appeared in OpenSSL 0.9.7 and have been available since -.Ox 2.9 . -.Pp -.Fn ENGINE_cmd_is_executable , -.Fn ENGINE_ctrl_cmd , -.Fn ENGINE_ctrl_cmd_string , -.Fn ENGINE_set_cmd_defns , -and -.Fn ENGINE_get_cmd_defns -first appeared in OpenSSL 0.9.7 and have been available since -.Ox 3.2 . -- cgit v1.2.3-55-g6feb