[src/trunk]: src Document the questionable ISSET/SET/CLR macros.

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

details:   https://anonhg.NetBSD.org/src/rev/4a50a99baf25
branches:  trunk
changeset: 753280:4a50a99baf25
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Mon Mar 22 10:32:48 2010 +0000

description:
Document the questionable ISSET/SET/CLR macros.

diffstat:

 distrib/sets/lists/comp/mi |  11 ++++++-
 share/man/man9/Makefile    |   6 ++-
 share/man/man9/SET.9       |  71 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 85 insertions(+), 3 deletions(-)

diffs (183 lines):

diff -r e5d32114b44d -r 4a50a99baf25 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Mon Mar 22 10:15:00 2010 +0000
+++ b/distrib/sets/lists/comp/mi        Mon Mar 22 10:32:48 2010 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.1413 2010/03/21 21:23:51 jruoho Exp $
+#      $NetBSD: mi,v 1.1414 2010/03/22 10:32:48 jruoho Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -8437,6 +8437,7 @@
 ./usr/share/man/cat9/CALLOUT_INITIALIZER_SETFUNC.0     comp-obsolete           obsolete
 ./usr/share/man/cat9/CARDBUS_PRODUCT.0         comp-sys-catman         .cat
 ./usr/share/man/cat9/CARDBUS_VENDOR.0          comp-sys-catman         .cat
+./usr/share/man/cat9/CLR.0                     comp-sys-catman         .cat
 ./usr/share/man/cat9/CTASSERT.0                        comp-sys-catman         .cat
 ./usr/share/man/cat9/Cardbus_conf_read.0       comp-sys-catman         .cat
 ./usr/share/man/cat9/Cardbus_conf_write.0      comp-sys-catman         .cat
@@ -8456,6 +8457,7 @@
 ./usr/share/man/cat9/FILE_USE.0                        comp-sys-catman         .cat
 ./usr/share/man/cat9/FREE.0                    comp-sys-catman         .cat
 ./usr/share/man/cat9/HOLDRELE.0                        comp-obsolete           obsolete
+./usr/share/man/cat9/ISSET.0                   comp-sys-catman         .cat
 ./usr/share/man/cat9/KASSERT.0                 comp-sys-catman         .cat
 ./usr/share/man/cat9/KDASSERT.0                        comp-sys-catman         .cat
 ./usr/share/man/cat9/KNOTE.0                   comp-sys-catman         .cat
@@ -8487,6 +8489,7 @@
 ./usr/share/man/cat9/RUN_ONCE.0                        comp-sys-catman         .cat
 ./usr/share/man/cat9/SCHED_LOCK.0              comp-obsolete           obsolete
 ./usr/share/man/cat9/SCHED_UNLOCK.0            comp-obsolete           obsolete
+./usr/share/man/cat9/SET.0                     comp-sys-catman         .cat
 ./usr/share/man/cat9/TC_DENSE_TO_SPARSE.0      comp-sys-catman         .cat
 ./usr/share/man/cat9/TC_PHYS_TO_UNCACHED.0     comp-sys-catman         .cat
 ./usr/share/man/cat9/VATTR_NULL.0              comp-obsolete           obsolete
@@ -14125,6 +14128,7 @@
 ./usr/share/man/html9/BOOT_FLAG.html           comp-sys-htmlman        html
 ./usr/share/man/html9/CARDBUS_PRODUCT.html     comp-sys-htmlman        html
 ./usr/share/man/html9/CARDBUS_VENDOR.html      comp-sys-htmlman        html
+./usr/share/man/html9/CLR.html                 comp-sys-htmlman        html
 ./usr/share/man/html9/CTASSERT.html            comp-sys-htmlman        html
 ./usr/share/man/html9/Cardbus_conf_read.html   comp-sys-htmlman        html
 ./usr/share/man/html9/Cardbus_conf_write.html  comp-sys-htmlman        html
@@ -14144,6 +14148,7 @@
 ./usr/share/man/html9/FILE_USE.html            comp-sys-htmlman        html
 ./usr/share/man/html9/FREE.html                        comp-sys-htmlman        html
 ./usr/share/man/html9/HOLDRELE.html            comp-obsolete   obsolete
+./usr/share/man/html9/ISSET.html               comp-sys-htmlman        html
 ./usr/share/man/html9/KASSERT.html             comp-sys-htmlman        html
 ./usr/share/man/html9/KDASSERT.html            comp-sys-htmlman        html
 ./usr/share/man/html9/KNOTE.html               comp-sys-htmlman        html
@@ -14172,6 +14177,7 @@
 ./usr/share/man/html9/PCI_VENDOR.html          comp-sys-htmlman        html
 ./usr/share/man/html9/PMC_ENABLED.html         comp-sys-htmlman        html
 ./usr/share/man/html9/RUN_ONCE.html            comp-sys-htmlman        html
+./usr/share/man/html9/SET.html                 comp-sys-htmlman        html
 ./usr/share/man/html9/TC_DENSE_TO_SPARSE.html  comp-sys-htmlman        html
 ./usr/share/man/html9/TC_PHYS_TO_UNCACHED.html comp-sys-htmlman        html
 ./usr/share/man/html9/VATTR_NULL.html          comp-obsolete   obsolete
@@ -19900,6 +19906,7 @@
 ./usr/share/man/man9/CALLOUT_INITIALIZER_SETFUNC.9     comp-obsolete           obsolete
 ./usr/share/man/man9/CARDBUS_PRODUCT.9         comp-sys-man            .man
 ./usr/share/man/man9/CARDBUS_VENDOR.9          comp-sys-man            .man
+./usr/share/man/man9/CLR.9                     comp-sys-man            .man
 ./usr/share/man/man9/CTASSERT.9                        comp-sys-man            .man
 ./usr/share/man/man9/Cardbus_conf_read.9       comp-sys-man            .man
 ./usr/share/man/man9/Cardbus_conf_write.9      comp-sys-man            .man
@@ -19919,6 +19926,7 @@
 ./usr/share/man/man9/FILE_USE.9                        comp-sys-man            .man
 ./usr/share/man/man9/FREE.9                    comp-sys-man            .man
 ./usr/share/man/man9/HOLDRELE.9                        comp-obsolete           obsolete
+./usr/share/man/man9/ISSET.9                   comp-sys-man            .man
 ./usr/share/man/man9/KASSERT.9                 comp-sys-man            .man
 ./usr/share/man/man9/KDASSERT.9                        comp-sys-man            .man
 ./usr/share/man/man9/KNOTE.9                   comp-sys-man            .man
@@ -19950,6 +19958,7 @@
 ./usr/share/man/man9/RUN_ONCE.9                        comp-sys-man            .man
 ./usr/share/man/man9/SCHED_LOCK.9              comp-obsolete           obsolete
 ./usr/share/man/man9/SCHED_UNLOCK.9            comp-obsolete           obsolete
+./usr/share/man/man9/SET.9                     comp-sys-man            .man
 ./usr/share/man/man9/TC_DENSE_TO_SPARSE.9      comp-sys-man            .man
 ./usr/share/man/man9/TC_PHYS_TO_UNCACHED.9     comp-sys-man            .man
 ./usr/share/man/man9/VATTR_NULL.9              comp-obsolete           obsolete
diff -r e5d32114b44d -r 4a50a99baf25 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Mon Mar 22 10:15:00 2010 +0000
+++ b/share/man/man9/Makefile   Mon Mar 22 10:32:48 2010 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.320 2010/03/06 16:42:56 dsieger Exp $
+#       $NetBSD: Makefile,v 1.321 2010/03/22 10:32:48 jruoho Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -45,7 +45,7 @@
        rssadapt.9 rt_timer.9 rwlock.9 RUN_ONCE.9 \
        sched_4bsd.9 sched_m2.9 scsipi.9 \
        secmodel.9 secmodel_bsd44.9 secmodel_overlay.9 secmodel_securelevel.9 \
-       secmodel_suser.9 setbit.9 setjmp.9 shutdownhook_establish.9 \
+       secmodel_suser.9 SET.9 setbit.9 setjmp.9 shutdownhook_establish.9 \
        signal.9 sockopt.9 softintr.9 spl.9 splraiseipl.9 \
        store.9 suspendsched.9 \
        sysctl.9 sysmon_envsys.9 sysmon_pswitch.9 sysmon_taskq.9 tc.9 \
@@ -599,6 +599,8 @@
        select.9 seldestroy.9 \
        select.9 selrecord.9 \
        select.9 selnotify.9
+MLINKS+=SET.9 CLR.9 \
+       SET.9 ISSET.9
 MLINKS+=setbit.9 clrbit.9 \
        setbit.9 isset.9 \
        setbit.9 isclr.9
diff -r e5d32114b44d -r 4a50a99baf25 share/man/man9/SET.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/SET.9      Mon Mar 22 10:32:48 2010 +0000
@@ -0,0 +1,71 @@
+.\" $NetBSD: SET.9,v 1.1 2010/03/22 10:32:48 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 22, 2010
+.Dt SET 9
+.Os
+.Sh NAME
+.Nm SET
+.Nd primitive bit macros
+.Sh SYNOPSIS
+.In sys/types.h
+.Ft void
+.Fn SET "val" "x"
+.Ft void
+.Fn ISSET "val" "x"
+.Ft void
+.Fn CLR "val" "x"
+.Sh DESCRIPTION
+These macros define three standard bit-operations:
+.Bl -enum -offset indent
+.It
+.Fn SET
+sets the bit
+.Fa x
+in
+.Fa val ;
+.It
+.Fn CLR
+clears the bit
+.Fa x
+in
+.Fa val ;
+and
+.It
+.Fn ISSET
+returns 1 if the bit
+.Fa x
+is set in
+.Fa val .
+.El
+.Pp
+The rationale is to provide clarity in the source code,
+but arguably these operations are clear enough without the use of the macros.
+.Sh SEE ALSO
+.Xr bits 3