From: schwarze <schwarze@openbsd.org>
Date: Tue, 13 Feb 2018 22:51:23 +0000 (+0000)
Subject: Add the missing RETURN VALUES section.
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=14ce64510619b147b8bc4f4d1c72a2e30270c9ff;p=openbsd

Add the missing RETURN VALUES section.
Mostly from Paul Yang via OpenSSL commit 1f13ad31 Dec 25 17:50:39 2017 +0800,
tweaked by me for conciseness and accuracy.
---

diff --git a/lib/libcrypto/man/engine.3 b/lib/libcrypto/man/engine.3
index a8ef6a89516..c27c574f28d 100644
--- a/lib/libcrypto/man/engine.3
+++ b/lib/libcrypto/man/engine.3
@@ -1,8 +1,10 @@
-.\"	$OpenBSD: engine.3,v 1.10 2017/01/06 20:35:23 schwarze Exp $
-.\"	OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400
+.\" $OpenBSD: engine.3,v 1.11 2018/02/13 22:51:23 schwarze Exp $
+.\" full merge up to: OpenSSL crypto/engine e6390aca Jul 21 10:06:03 2015 -0400
+.\" selective merge up to: man3/ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
 .\"
-.\" This file was written by Geoff Thorpe <geoff@openssl.org>.
-.\" Copyright (c) 2002, 2004, 2007, 2015 The OpenSSL Project.
+.\" This file was written by Geoff Thorpe <geoff@openssl.org>
+.\" with contributions from Paul Yang <yang.yang@baishancloud.com>.
+.\" Copyright (c) 2002, 2004, 2007, 2015, 2017 The OpenSSL Project.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -49,7 +51,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: January 6 2017 $
+.Dd $Mdocdate: February 13 2018 $
 .Dt ENGINE 3
 .Os
 .Sh NAME
@@ -1197,6 +1199,117 @@ to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - and
 .Vt ENGINE
 could therefore decide whether or not to support this "foo"-specific
 extension).
+.Sh RETURN VALUES
+.Fn ENGINE_get_first ,
+.Fn ENGINE_get_last ,
+.Fn ENGINE_get_next ,
+.Fn ENGINE_get_prev ,
+.Fn ENGINE_by_id ,
+.Fn ENGINE_get_cipher_engine ,
+.Fn ENGINE_get_digest_engine ,
+.Fn ENGINE_new ,
+and all
+.Fn ENGINE_get_default_*
+functions return a valid
+.Vt ENGINE
+structure or
+.Dv NULL
+if an error occurred.
+.Pp
+.Fn ENGINE_add ,
+.Fn ENGINE_remove ,
+.Fn ENGINE_init ,
+.Fn ENGINE_finish ,
+.Fn ENGINE_ctrl_cmd ,
+.Fn ENGINE_ctrl_cmd_string ,
+.Fn ENGINE_free ,
+.Fn ENGINE_up_ref ,
+and all
+.Fn ENGINE_set_*
+and
+.Fn ENGINE_register_*
+functions return 1 on success or 0 on error.
+.Pp
+.Fn ENGINE_get_table_flags
+returns an unsigned integer value representing the global table
+flags which are used to control the registration behaviour of
+.Vt ENGINE
+implementations.
+.Pp
+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
+.Fn ENGINE_cmd_is_executable
+returns 1 if
+.Fa cmd
+is executable or 0 otherwise.
+.Pp
+.Fn ENGINE_get_id
+and
+.Fn ENGINE_get_name
+return a pointer to an internal string representing the identifier
+and the name of
+.Fa e ,
+respectively.
+.Pp
+.Fn ENGINE_get_RSA ,
+.Fn ENGINE_get_DSA ,
+.Fn ENGINE_get_DH ,
+.Fn ENGINE_get_RAND ,
+and
+.Fn ENGINE_get_STORE
+return a method structure for the respective algorithm.
+.Pp
+.Fn ENGINE_get_destroy_function ,
+.Fn ENGINE_get_init_function ,
+.Fn ENGINE_get_finish_function ,
+.Fn ENGINE_get_ctrl_function ,
+.Fn ENGINE_get_load_privkey_function ,
+.Fn ENGINE_get_load_pubkey_function ,
+.Fn ENGINE_get_ciphers ,
+and
+.Fn ENGINE_get_digests
+return a function pointer to the respective callback.
+.Pp
+.Fn ENGINE_get_cipher
+returns a valid
+.Vt EVP_CIPHER
+structure on success or
+.Dv NULL
+if an error occurred.
+.Pp
+.Fn ENGINE_get_digest
+returns a valid
+.Vt EVP_MD
+structure on success or
+.Dv NULL
+if an error occurred.
+.Pp
+.Fn ENGINE_get_flags
+returns an integer representing the flags
+which are used to control various behaviours of an
+.Vt ENGINE .
+.Pp
+.Fn ENGINE_get_cmd_defns
+returns an
+.Vt ENGINE_CMD_DEFN
+structure or
+.Dv NULL
+if none is set.
+.Pp
+.Fn ENGINE_load_private_key
+and
+.Fn ENGINE_load_public_key
+return a valid
+.Vt EVP_PKEY
+structure on success or
+.Dv NULL
+if an error occurred.
 .Sh SEE ALSO
 .Xr DH_new 3 ,
 .Xr DSA_new 3 ,