Module Name: src
Committed By: riastradh
Date: Fri Nov 5 22:39:36 UTC 2021
Modified Files:
src/share/man/man3: ilog2.3
Log Message:
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.
To generate a diff of this commit:
cvs rdiff -u -r1.5 -r1.6 src/share/man/man3/ilog2.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man3/ilog2.3
diff -u src/share/man/man3/ilog2.3:1.5 src/share/man/man3/ilog2.3:1.6
--- src/share/man/man3/ilog2.3:1.5 Tue May 10 06:39:45 2011
+++ src/share/man/man3/ilog2.3 Fri Nov 5 22:39:35 2021
@@ -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 ,
