Document OpenSSL_version_num(3) and OpenSSL_version(3) that jsing@

recently provided.  Many minor improvements while here, and delete
ridiculous text about MS Windows.

diff --git a/lib/libcrypto/man/OPENSSL_VERSION_NUMBER.3 b/lib/libcrypto/man/OPENSSL_VERSION_NUMBER.3
index 7c792f7..e5a66c5 100644 (file)
--- a/lib/libcrypto/man/OPENSSL_VERSION_NUMBER.3
+++ b/lib/libcrypto/man/OPENSSL_VERSION_NUMBER.3
@@ -1,9 +1,28 @@
-.\"    $OpenBSD: OPENSSL_VERSION_NUMBER.3,v 1.3 2016/11/28 14:51:03 schwarze Exp $
-.\"    OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400
+.\" $OpenBSD: OPENSSL_VERSION_NUMBER.3,v 1.4 2018/02/17 18:00:59 schwarze Exp $
+.\" full merge up to: OpenSSL 1f13ad31 Dec 25 17:50:39 2017 +0800
 .\"
-.\" This file was written by Ulf Moeller <ulf@openssl.org> and
-.\" Richard Levitte <levitte@openssl.org>.
-.\" Copyright (c) 2000, 2002, 2014 The OpenSSL Project.  All rights reserved.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" 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.
+.\"
+.\" The original file was written by Ulf Moeller <ulf@openssl.org>,
+.\" Richard Levitte <levitte@openssl.org>, and
+.\" Bodo Moeller <bodo@openssl.org>.
+.\" Copyright (c) 2000, 2002, 2015, 2016, 2017 The OpenSSL Project.
+.\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -49,18 +68,26 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 28 2016 $
+.Dd $Mdocdate: February 17 2018 $
 .Dt OPENSSL_VERSION_NUMBER 3
 .Os
 .Sh NAME
 .Nm OPENSSL_VERSION_NUMBER ,
+.Nm OpenSSL_version_num ,
+.Nm OpenSSL_version ,
 .Nm SSLeay ,
 .Nm SSLeay_version
 .Nd get OpenSSL version number
 .Sh SYNOPSIS
 .In openssl/opensslv.h
-.Fd #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL
+.Fd #define OPENSSL_VERSION_NUMBER 0x020000000L
 .In openssl/crypto.h
+.Ft unsigned long
+.Fn OpenSSL_version_num void
+.Ft const char *
+.Fo OpenSSL_version
+.Fa "int t"
+.Fc
 .Ft long
 .Fn SSLeay void
 .Ft const char *
@@ -70,21 +97,23 @@
 .Sh DESCRIPTION
 .Dv OPENSSL_VERSION_NUMBER
 is a numeric release version identifier.
-The first two digits contain the major release number,
+For OpenSSL, the first two digits contain the major release number,
 the third and fourth digits the minor release number,
 the fifth and sixth digits the fix release number,
 the seventh and eight digits the patch release number.
 The final digit is 0 for development, 1 to e for betas 1 to 14, or f
 for release.
+For LibreSSL, this number is always 0x020000000.
 .Pp
 For example:
 .Bd -literal -offset indent
 0x000906000 == 0.9.6 dev
 0x000906023 == 0.9.6b beta 3
 0x00090605f == 0.9.6e release
+0x020000000 == 2.0.0 for any version of LibreSSL
 .Ed
 .Pp
-Versions prior to 0.9.3 had identifiers < 0x0930.
+OpenSSL versions prior to 0.9.3 had identifiers < 0x0930.
 For versions between 0.9.3 and 0.9.5,
 the seventh digit was 1 for release and 0 otherwise,
 and the eighth and ninth digits were the patch release number.
@@ -95,45 +124,107 @@ For example:
 0x000905000 == 0.9.5 dev
 .Ed
 .Pp
-Version 0.9.5a had an interim interpretation that is like the current
+OpenSSL version 0.9.5a had an interim interpretation that is like the current
 one, except the patch level got the highest bit set, to keep continuity.
 The number was therefore 0x0090581f.
 .Pp
-For backward compatibility, SSLEAY_VERSION_NUMBER is also defined.
+.Fn OpenSSL_version_num
+returns this version number.
 .Pp
-.Fn SSLeay
-returns this number.
-The return value can be compared to the macro to make sure that the
-correct version of the library has been loaded, especially when using
-DLLs on Windows systems.
-.Pp
-.Fn SSLeay_version
+.Fn OpenSSL_version
 returns different strings depending on
 .Fa t :
 .Bl -tag -width Ds
-.It Dv SSLEAY_VERSION
-The text variant of the version number and the release date.
-For example, "OpenSSL 0.9.5a 1 Apr 2000".
-.It Dv SSLEAY_CFLAGS
+.It Dv OPENSSL_VERSION
+The text variant of the version number.
+For OpenSSL, it is followed by the release date.
+For example,
+.Qq OpenSSL 0.9.5a 1 Apr 2000
+or
+.Qq LibreSSL 2.7.0 .
+.It Dv OPENSSL_CFLAGS
 The compiler flags set for the compilation process in the form
-"compiler: ..." if available or "compiler: information not available"
+.Qq compiler: ...
+if available or
+.Qq compiler: information not available
+otherwise.
+LibreSSL never provides compiler information.
+.It Dv OPENSSL_BUILT_ON
+The date of the build process in the form
+.Qq built on: ...
+if available or
+.Qq built on: date not available
+otherwise.
+LibreSSL never provides information on the build date.
+.It Dv OPENSSL_PLATFORM
+The Configure target of the library build in the form
+.Qq platform: ...
+if available or
+.Qq platform: information not available
+otherwise.
+LibreSSL never provides platform information.
+.It Dv OPENSSL_DIR
+The
+.Dv OPENSSLDIR
+setting of the library build in the form
+.Qq OPENSSLDIR: Qq ...
+if available or
+.Qq OPENSSLDIR: N/A
+otherwise.
+For LibreSSL, the default is
+.Qq OPENSSLDIR: Qq /etc/ssl .
+.It Dv OPENSSL_ENGINES_DIR
+The
+.Dv ENGINESDIR
+setting of the library build in the form
+.Qq ENGINESDIR: Qq ...
+if available or
+.Qq ENGINESDIR: N/A
 otherwise.
-.It Dv SSLEAY_BUILT_ON
-The date of the build process in the form "built on: ..." if available
-or "built on: date not available" otherwise.
-.It Dv SSLEAY_PLATFORM
-The "Configure" target of the library build in the form "platform: ..."
-if available or "platform: information not available" otherwise.
-.It Dv SSLEAY_DIR
-The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR:
-"..."" if available or "OPENSSLDIR: N/A" otherwise.
+LibreSSL never provides or uses an
+.Dv ENGINESDIR .
 .El
 .Pp
 For an unknown
 .Fa t ,
-the text "not available" is returned.
+the text
+.Qq not available
+is returned.
+.Pp
+For backward compatibility,
+.Dv SSLEAY_VERSION_NUMBER
+is an alias for
+.Dv OPENSSL_VERSION_NUMBER
+and
+.Fn SSLeay
+for
+.Dv OpenSSL_version_num .
+The legacy function
+.Fn SSLeay_version
+is similar to
+.Fn OpenSSL_version
+except that it takes arguments
+.Dv SSLEAY_VERSION ,
+.Dv SSLEAY_CFLAGS ,
+.Dv SSLEAY_BUILT_ON ,
+.Dv SSLEAY_PLATFORM ,
+and
+.Dv SSLEAY_DIR
+which expand to
+.Em other
+numerical values than the corresponding
+.Dv OPENSSL_*
+macros.
 .Sh RETURN VALUES
-The version number.
+.Fn OpenSSL_version_num
+and
+.Fn SSLeay
+return a constant version number.
+.Pp
+.Fn OpenSSL_version
+and
+.Fn SSLeay_version
+return pointers to static strings.
 .Sh SEE ALSO
 .Xr crypto 3
 .Sh HISTORY