From: schwarze <schwarze@openbsd.org>
Date: Tue, 13 Feb 2018 02:39:29 +0000 (+0000)
Subject: Correctly describe BN_get_word(3) and BN_set_word(3).
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=051ddd90a1e4f29d69d7e618aa1fe7db6ffd3b26;p=openbsd

Correctly describe BN_get_word(3) and BN_set_word(3).
These functions constitute an obvious portability nightmare,
but that's no excuse for incorrect documentation.

Pointed out by Nicolas Schodet
via OpenSSL commit b713c4ff Jan 22 14:41:09 2018 -0500.
---

diff --git a/lib/libcrypto/man/BN_zero.3 b/lib/libcrypto/man/BN_zero.3
index 49d08717e4b..8343beebc41 100644
--- a/lib/libcrypto/man/BN_zero.3
+++ b/lib/libcrypto/man/BN_zero.3
@@ -1,8 +1,10 @@
-.\"	$OpenBSD: BN_zero.3,v 1.6 2016/12/10 21:13:25 schwarze Exp $
-.\"	OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400
+.\" $OpenBSD: BN_zero.3,v 1.7 2018/02/13 02:39:29 schwarze Exp $
+.\" full merge up to: OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400
+.\" selective merge up to: OpenSSL b713c4ff Jan 22 14:41:09 2018 -0500
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
-.\" Copyright (c) 2000, 2001, 2002 The OpenSSL Project.  All rights reserved.
+.\" Copyright (c) 2000, 2001, 2002, 2018 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
@@ -48,7 +50,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 10 2016 $
+.Dd $Mdocdate: February 13 2018 $
 .Dt BN_ZERO 3
 .Os
 .Sh NAME
@@ -75,13 +77,17 @@
 .Ft int
 .Fo BN_set_word
 .Fa "BIGNUM *a"
-.Fa "unsigned long w"
+.Fa "BN_ULONG w"
 .Fc
-.Ft unsigned long
+.Ft BN_ULONG
 .Fo BN_get_word
 .Fa "BIGNUM *a"
 .Fc
 .Sh DESCRIPTION
+.Vt BN_ULONG
+is a macro that expands to an unsigned integral type optimized
+for the most efficient implementation on the local platform.
+.Pp
 .Fn BN_zero ,
 .Fn BN_one ,
 and
@@ -100,21 +106,15 @@ are macros.
 returns a
 .Vt BIGNUM
 constant of value 1.
-This constant is useful for use in comparisons and assignment.
-.Pp
-.Fn BN_get_word
-returns
-.Fa a
-if it can be represented as an
-.Vt unsigned long .
+This constant is useful for comparisons and assignments.
 .Sh RETURN VALUES
 .Fn BN_get_word
 returns the value
 .Fa a ,
-or 0xffffffffL if
+or a number with all bits set if
 .Fa a
-cannot be represented as an
-.Vt unsigned long .
+cannot be represented as a
+.Vt BN_ULONG .
 .Pp
 .Fn BN_zero ,
 .Fn BN_one ,
@@ -146,8 +146,13 @@ in OpenSSL 0.9.7.
 .Sh BUGS
 Someone might change the constant.
 .Pp
-If a
+If the value of a
 .Vt BIGNUM
-is equal to 0xffffffffL; it can be represented as an
-.Vt unsigned long
-but this value is also returned on error.
+is equal to a
+.Vt BN_ULONG
+with all bits set, the return value of
+.Fn BN_get_word
+collides with return value used to indicate errors.
+.Pp
+.Vt BN_ULONG
+should probably be a typedef rather than a macro.