Module Name: src
Committed By: jruoho
Date: Thu Mar 4 08:09:52 UTC 2010
Modified Files:
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: roundup.9
Log Message:
Document the counting and rounding macros from <sys/param.h>.
To generate a diff of this commit:
cvs rdiff -u -r1.318 -r1.319 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/roundup.9
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/man9/Makefile
diff -u src/share/man/man9/Makefile:1.318 src/share/man/man9/Makefile:1.319
--- src/share/man/man9/Makefile:1.318 Mon Mar 1 19:09:41 2010
+++ src/share/man/man9/Makefile Thu Mar 4 08:09:51 2010
@@ -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 \
Added files:
Index: src/share/man/man9/roundup.9
diff -u /dev/null src/share/man/man9/roundup.9:1.1
--- /dev/null Thu Mar 4 08:09:52 2010
+++ src/share/man/man9/roundup.9 Thu Mar 4 08:09:52 2010
@@ -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.
