[src/trunk]: src/share/man/man9 Document the counting and rounding macros fro...

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

details:   https://anonhg.NetBSD.org/src/rev/2b6df7d83a18
branches:  trunk
changeset: 752693:2b6df7d83a18
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Thu Mar 04 08:09:51 2010 +0000

description:
Document the counting and rounding macros from <sys/param.h>.

diffstat:

 share/man/man9/Makefile  |  10 +++-
 share/man/man9/roundup.9 |  96 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+), 3 deletions(-)

diffs (131 lines):

diff -r ed81727f4076 -r 2b6df7d83a18 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Thu Mar 04 08:01:35 2010 +0000
+++ b/share/man/man9/Makefile   Thu Mar 04 08:09:51 2010 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.318 2010/03/01 19:09:41 jruoho Exp $
+#       $NetBSD: Makefile,v 1.319 2010/03/04 08:09:51 jruoho Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -41,8 +41,8 @@
        pcmcia.9 pcq.9 percpu.9 pfil.9 physio.9 pmap.9 pmatch.9 pmc.9 pmf.9 \
        pool.9 pool_cache.9 powerhook_establish.9 ppsratecheck.9 \
        preempt.9 putter.9 \
-       radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rssadapt.9 \
-       rt_timer.9 rwlock.9 RUN_ONCE.9 \
+       radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 roundup.9 \
+       rssadapt.9 rt_timer.9 rwlock.9 RUN_ONCE.9 \
        sched_4bsd.9 scsipi.9 \
        secmodel.9 secmodel_bsd44.9 secmodel_overlay.9 secmodel_securelevel.9 \
        secmodel_suser.9 setbit.9 setjmp.9 shutdownhook_establish.9 \
@@ -577,6 +577,10 @@
        rasops.9 rasops_reconfig.9
 MLINKS+=rnd.9 rnd_attach_source.9 rnd.9 rnd_detach_source.9 \
        rnd.9 rnd_add_data.9 rnd.9 rnd_add_uint32.9
+MLINKS+=roundup.9 howmany.9 \
+       roundup.9 rounddown.9 \
+       roundup.9 roundup2.9 \
+       roundup.9 powerof2.9
 MLINKS+=rssadapt.9 ieee80211_rssadapt_choose.9 \
        rssadapt.9 ieee80211_rssadapt_input.9 \
        rssadapt.9 ieee80211_rssadapt_lower_rate.9 \
diff -r ed81727f4076 -r 2b6df7d83a18 share/man/man9/roundup.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/roundup.9  Thu Mar 04 08:09:51 2010 +0000
@@ -0,0 +1,96 @@
+.\" $NetBSD: roundup.9,v 1.1 2010/03/04 08:09:52 jruoho Exp $
+.\"
+.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jukka Ruohonen.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd March 4, 2010
+.Dt ROUNDUP 9
+.Os
+.Sh NAME
+.Nm roundup
+.Nd macros for counting and rounding
+.Sh SYNOPSIS
+.In sys/param.h
+.Ft size
+.Fn howmany "x" "size"
+.Ft size
+.Fn roundup "x" "size"
+.Ft size
+.Fn rounddown "x" "size"
+.Ft size
+.Fn roundup2 "x" "size"
+.Ft int
+.Fn powerof2 "x"
+.Sh DESCRIPTION
+The
+.Fn roundup
+and
+.Fn rounddown
+macros return an integer from rounding
+.Fa x
+up and down, respectively, to the next
+.Fa size .
+The
+.Fn howmany
+macro in turn reveals how many times
+.Fa size
+fits into
+.Fa x ,
+rounding the residual up.
+.Pp
+The
+.Fn roundup2
+macro also rounds up, but with the assumption that
+.Fa x
+is a power of two.
+If
+.Fa x
+is indeed a power of two,
+.Fn powerof2
+return 1.
+.Sh RETURN VALUES
+The return value is an integer from the respective operation.
+If
+.Fa x
+is 0, all macros except
+.Fn powerof2
+return 0.
+The behavior is undefined if
+.Fa size
+is 0.
+.Sh EXAMPLES
+.Bd -literal -offset indent
+uint16_t rx;
+
+\&...
+
+/* Round up to 32-bit boundary. */
+rx = roundup2(rx, sizeof(uint32_t));
+.Ed
+.Sh CAVEATS
+All described macros make no assumptions about the type of the parameters.
+These are implicitly assumed to be unsigned integers.