Module Name: src
Committed By: christos
Date: Sat Dec 1 20:33:02 UTC 2012
Modified Files:
src/share/man/man3: Makefile
Added Files:
src/share/man/man3: bitmap.3
Log Message:
add documentation for the bitmap macros
To generate a diff of this commit:
cvs rdiff -u -r1.79 -r1.80 src/share/man/man3/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man3/bitmap.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/Makefile
diff -u src/share/man/man3/Makefile:1.79 src/share/man/man3/Makefile:1.80
--- src/share/man/man3/Makefile:1.79 Tue Aug 9 13:58:27 2011
+++ src/share/man/man3/Makefile Sat Dec 1 15:33:02 2012
@@ -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 @@ MAN= _DIAGASSERT.3 __CONCAT.3 __UNCONST.
__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 @@ MLINKS+=CMSG_DATA.3 CMSG_FIRSTHDR.3 \
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>
Added files:
Index: src/share/man/man3/bitmap.3
diff -u /dev/null src/share/man/man3/bitmap.3:1.1
--- /dev/null Sat Dec 1 15:33:02 2012
+++ src/share/man/man3/bitmap.3 Sat Dec 1 15:33:02 2012
@@ -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 .
