Enhance documentation for `BN_mask_bits()`

Fixes #5537

Added a note that the error check for `BN_mask_bits()` depends
on the internal representation that depends on the platform's word size.
Included a reference to the `BN_num_bits()` function for precise bit checking.

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/24812)

diff --git a/doc/man3/BN_set_bit.pod b/doc/man3/BN_set_bit.pod
index 349ef9e0562cc39426685445cf7552d2c1653a47..e4d66791e886f25c1215d8097d5afa2dd886eaea 100644 (file)
--- a/doc/man3/BN_set_bit.pod
+++ b/doc/man3/BN_set_bit.pod
@@ -33,8 +33,11 @@ error occurs if B<a> is shorter than B<n> bits.
 BN_is_bit_set() tests if bit B<n> in B<a> is set.
 
 BN_mask_bits() truncates B<a> to an B<n> bit number
-(C<a&=~((~0)E<lt>E<lt>n)>).  An error occurs if B<a> already is
-shorter than B<n> bits.
+(C<a&=~((~0)E<lt>E<lt>n)>). An error occurs if B<n> is negative. An error is
+also returned if the internal representation of B<a> is already shorter than
+B<n> bits. The internal representation depends on the platform's word size, and
+this error can be safely ignored. Use L<BN_num_bits(3)> to determine the exact
+number of bits if needed.
 
 BN_lshift() shifts B<a> left by B<n> bits and places the result in
 B<r> (C<r=a*2^n>). Note that B<n> must be nonnegative. BN_lshift1() shifts