[src/trunk]: src/share/man/man3 add documentation for the bitmap macros

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

details:   https://anonhg.NetBSD.org/src/rev/48088ddb10e2
branches:  trunk
changeset: 783014:48088ddb10e2
user:      christos <christos%NetBSD.org@localhost>
date:      Sat Dec 01 20:33:02 2012 +0000

description:
add documentation for the bitmap macros

diffstat:

 share/man/man3/Makefile |    9 ++-
 share/man/man3/bitmap.3 |  133 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 140 insertions(+), 2 deletions(-)

diffs (167 lines):

diff -r f54c0a52a06c -r 48088ddb10e2 share/man/man3/Makefile
--- a/share/man/man3/Makefile   Sat Dec 01 16:30:00 2012 +0000
+++ b/share/man/man3/Makefile   Sat Dec 01 20:33:02 2012 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.79 2011/08/09 17:58:27 jruoho Exp $
+#      $NetBSD: Makefile,v 1.80 2012/12/01 20:33:02 christos Exp $
 #      @(#)Makefile    8.2 (Berkeley) 12/13/93
 
 MAN=   _DIAGASSERT.3 __CONCAT.3 __UNCONST.3 CMSG_DATA.3 \
@@ -6,7 +6,7 @@
        __builtin_constant_p.3 __builtin_prefetch.3 \
        __builtin_return_address.3 \
        __builtin_types_compatible_p.3 __insn_barrier.3 \
-       assert.3 attribute.3 bitops.3 bits.3 bitstring.3 \
+       assert.3 attribute.3 bitmap.3 bitops.3 bits.3 bitstring.3 \
        cdefs.3 dirent.3 dlfcn.3 dl_iterate_phdr.3 end.3 \
        fast_divide32.3 ffs32.3 gcq.3 \
        ilog2.3 intro.3 inttypes.3 iso646.3 limits.3 \
@@ -268,6 +268,11 @@
        CMSG_DATA.3 CMSG_NXTHDR.3 \
        CMSG_DATA.3 CMSG_SPACE.3 \
        CMSG_DATA.3 cmsg.3
+MLINKS+=bitmap.3 __BITMAP_CLR.3 \
+       bitmap.3 __BITMAP_ISSET.3 \
+       bitmap.3 __BITMAP_SET.3 \
+       bitmap.3 __BITMAP_SIZE.3 \
+       bitmap.3 __BITMAP_ZERO.3
 
 .include <bsd.man.mk>
 .include <bsd.subdir.mk>
diff -r f54c0a52a06c -r 48088ddb10e2 share/man/man3/bitmap.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man3/bitmap.3   Sat Dec 01 20:33:02 2012 +0000
@@ -0,0 +1,133 @@
+.\"    $NetBSD: bitmap.3,v 1.1 2012/12/01 20:33:02 christos Exp $
+.\"
+.\" Copyright (c) 2012 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Christos Zoulas.
+.\"
+.\" 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 December 1, 2012
+.Dt bitmap 3
+.Os
+.Sh NAME
+.Nm __BITMAP_CLR ,
+.Nm __BITMAP_ISSET,
+.Nm __BITMAP_SET ,
+.Nm __BITMAP_SIZE ,
+.Nm __BITMAP_ZERO 
+.Nd bitmap manipulation macros
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In sys/bitops.h
+.Fn __BITMAP_CLR "int bit" "type *bitmap"
+.Fn __BITMAP_ISSET "int bit" "type *bitmap"
+.Fn __BITMAP_SET "int bit" "type *bitmap"
+.Fn __BITMAP_SIZE "type" "int nbits"
+.Fn __BITMAP_ZERO "type *bitmap"
+.Sh DESCRIPTION
+The supplied macros are similar to the 
+.Xr select 2
+.Fn FD_SET
+family, and to the 
+.Xr bitstring 3
+library.
+They are different from
+.Fn FD_SET
+because they are designed to handle multiple sized bitmaps at the same time,
+and they can be of any integral type.
+They are different from
+.Xr bitstring 3
+because they are just macros, they don't allocate memory or use code,
+and they can be used in both kernel and userland.
+.Pp
+The following macros are provided for manipulating creating and manipulating
+bitmaps:
+.Pp
+.Fn __BITMAP_CLR bit, bitmap
+initializes a descriptor set pointed to by
+.Fa bitmap
+to the null set.
+.Pp
+.Fn __BITMAP_ISSET bit bitmap
+is non-zero if
+.Fa bit
+is a member of
+.Fa bitmap ,
+zero otherwise.
+.Pp
+.Fn __BITMAP_SIZE type nbits
+Returns the number of elements would be required of the given
+.Fa type
+to hold
+.Fa nbits .
+.Pp
+.Fn __BITMAP_SET bit bitmap
+Sets the given
+.Fa bit
+in the
+.Fa bitmap .
+.Pp
+.Fn __BITMAP_CLR bit bitmap
+removes the given
+.Fa bit
+from the
+.Fa bitmap .
+.Pp
+The behavior of these macros is undefined for negative
+bit values or ones greater than the number of bits the bitmap can hold.
+.Sh EXAMPLES
+.Bd -literal
+#include \*[Lt]sys/bitops.h\*[Gt]
+
+int
+main(int argc, char **argv)
+{
+       uint32_t bitmap[__BITMAP_SIZE(uint32_t, 5000)];
+
+       /* Initialize the read set to null */
+       __BITMAP_ZERO(bitmap);
+
+       /* Set bit 1 */
+       __BITMAP_SET(1, bitmap);
+
+       for (size_t i = 0; i \*[Lt]= 5000; i++) {
+               if (__BITMAP_ISSET(i, bitmap)) {
+                       /* Should just print 1 */
+                       printf("Bit %zu is set\en", i);
+                       __BITMAP_CLR(i, bitmap);
+               }
+               break;
+       }
+       return 0;
+}
+.Ed
+.Sh SEE ALSO
+.Xr select 2 ,
+.Xr bitstring 3
+.Sh HISTORY
+The
+.Fn __BITMAP_*
+macros appeared in
+.Nx 7 .