From: tb <tb@openbsd.org>
Date: Sat, 17 Dec 2022 22:23:31 +0000 (+0000)
Subject: Merge documentation of UI_null() from OpenSSL 1.1
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=74a4f7c0d02da6587208900c9b7be4dd770f3312;p=openbsd

Merge documentation of UI_null() from OpenSSL 1.1

jsing doesn't like it, but it's better than nothing.

ok jsing
---

diff --git a/lib/libcrypto/man/UI_new.3 b/lib/libcrypto/man/UI_new.3
index ab7dfb36ec7..d7113591964 100644
--- a/lib/libcrypto/man/UI_new.3
+++ b/lib/libcrypto/man/UI_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: UI_new.3,v 1.10 2020/06/19 17:17:13 schwarze Exp $
+.\" $OpenBSD: UI_new.3,v 1.11 2022/12/17 22:23:31 tb Exp $
 .\" full merge up to: OpenSSL 78b19e90 Jan 11 00:12:01 2017 +0100
 .\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
 .\"
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 19 2020 $
+.Dd $Mdocdate: December 17 2022 $
 .Dt UI_NEW 3
 .Os
 .Sh NAME
@@ -76,7 +76,8 @@
 .Nm UI_get_default_method ,
 .Nm UI_get_method ,
 .Nm UI_set_method ,
-.Nm UI_OpenSSL
+.Nm UI_OpenSSL ,
+.Nm UI_null
 .Nd New User Interface
 .Sh SYNOPSIS
 .In openssl/ui.h
@@ -226,6 +227,10 @@
 .Fo UI_OpenSSL
 .Fa void
 .Fc
+.Ft const UI_METHOD *
+.Fo UI_null
+.Fa void
+.Fc
 .Sh DESCRIPTION
 UI stands for User Interface, and is a general purpose set of routines
 to prompt the user for text-based information.
@@ -298,6 +303,12 @@ See further on).
 This method is the most machine/OS dependent part of OpenSSL and
 normally generates the most problems when porting.
 .Pp
+.Fn UI_null
+returns a UI method that does nothing.
+Its use is to avoid getting internal defaults for passed
+.Vt UI_METHOD
+pointers.
+.Pp
 .Fn UI_free
 removes
 .Fa ui
@@ -478,9 +489,10 @@ returns 0 on success or a negative value on error.
 .Fn UI_ctrl
 returns a mask on success or \-1 on error.
 .Pp
-.Fn UI_get_default_method
-and
+.Fn UI_get_default_method ,
 .Fn UI_OpenSSL
+and
+.Fn UI_null
 always return a pointer to a valid
 .Vt UI_METHOD
 structure.
@@ -509,6 +521,10 @@ argument.
 These functions first appeared in  OpenSSL 0.9.7
 and have been available since
 .Ox 3.2 .
+.Pp
+.Fn UI_null
+first appeared in OpenSSL 1.1.1 and has been available since
+.Ox 7.3 .
 .Sh AUTHORS
 .An Richard Levitte Aq Mt richard@levitte.org
 for the OpenSSL project.