[src/trunk]: src/share/man/man3 Rework ilog2(3) man page.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/fa78624e9886
branches:  trunk
changeset: 1024801:fa78624e9886
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Fri Nov 05 22:39:35 2021 +0000

description:
Rework ilog2(3) man page.

- Tweak title.
- Clarify semantics -- round down, not any other way.
- xref ffs(3)
- Fix return type: int.
- Fix language about input type.
  . Any unsigned type is fine.
  . Types smaller than uint32_t will be safely converted to uint32_t.
- Note that it is a constant expression if x is constant.

diffstat:

 share/man/man3/ilog2.3 |  49 ++++++++++++++++++++++++++++++++++---------------
 1 files changed, 34 insertions(+), 15 deletions(-)

diffs (77 lines):

diff -r bcc7b8e78eb4 -r fa78624e9886 share/man/man3/ilog2.3
--- a/share/man/man3/ilog2.3    Fri Nov 05 22:06:43 2021 +0000
+++ b/share/man/man3/ilog2.3    Fri Nov 05 22:39:35 2021 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: ilog2.3,v 1.5 2011/05/10 06:39:45 jruoho Exp $ $
+.\" $NetBSD: ilog2.3,v 1.6 2021/11/05 22:39:35 riastradh Exp $ $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,34 +27,53 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd May 10, 2011
+.Dd November 5, 2021
 .Dt ILOG2 3
 .Os
 .Sh NAME
 .Nm ilog2
-.Nd integer logarithm
+.Nd integer base-2 logarithm
 .Sh SYNOPSIS
 .In sys/bitops.h
-.Ft size
+.Ft int
 .Fn ilog2 "size x"
 .Sh DESCRIPTION
-The
+For positive
+.Fa x ,
+the
 .Fn ilog2
-macro returns an integer (binary) logarithm of
-.Fa x .
-It is the logarithm for base 2; the binary logarithm of
-.Fa x
-is the power to which the number 2 must be raised to obtain the value
+macro returns the integer part of the base-2 logarithm of
+.Fa x ;
+that is,
+.Fo floor
+.Fn log_2 x
+.Fc .
+If
+.Fa n Li = Fn ilog2 x ,
+then
+.Fa n
+is the largest integer such that
+.No 2** Ns Fa n Li <= Fa x ;
+in other words,
+.Fn ilog2
+returns the largest integer to which 2 can be raised to obtain a value
+at most
 .Fa x .
 .Pp
-The type of the input parameter should be either
-.Vt uint32_t
-or
-.Vt uint64_t .
+The type of the input parameter must be unsigned.
+.Pp
+If
+.Fa x
+is a constant expression, then so is
+.Fn ilog2 x .
 .Sh ERRORS
-A value \-1 is returned on error.
+.Fn ilog2
+returns \-1 when
+.Fa x
+is zero.
 .Sh SEE ALSO
 .Xr bitops 3 ,
+.Xr ffs 3 ,
 .Xr ilogb 3 ,
 .Xr log2 3 ,
 .Xr imax 9 ,