[src/trunk]: src/share/man/man3 describe the __USE macro

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

details:   https://anonhg.NetBSD.org/src/rev/ae35bc2065b6
branches:  trunk
changeset: 790553:ae35bc2065b6
user:      christos <christos%NetBSD.org@localhost>
date:      Thu Oct 17 16:50:36 2013 +0000

description:
describe the __USE macro

diffstat:

 share/man/man3/Makefile |    4 +-
 share/man/man3/__USE.3  |  122 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 124 insertions(+), 2 deletions(-)

diffs (139 lines):

diff -r 088284749a8e -r ae35bc2065b6 share/man/man3/Makefile
--- a/share/man/man3/Makefile   Thu Oct 17 13:17:50 2013 +0000
+++ b/share/man/man3/Makefile   Thu Oct 17 16:50:36 2013 +0000
@@ -1,7 +1,7 @@
-#      $NetBSD: Makefile,v 1.81 2012/12/07 01:54:41 christos Exp $
+#      $NetBSD: Makefile,v 1.82 2013/10/17 16:50:36 christos Exp $
 #      @(#)Makefile    8.2 (Berkeley) 12/13/93
 
-MAN=   _DIAGASSERT.3 __CONCAT.3 __UNCONST.3 CMSG_DATA.3 \
+MAN=   _DIAGASSERT.3 __CONCAT.3 __UNCONST.3 __USE.3 CMSG_DATA.3 \
        __alignof__.3 __arraycount.3 \
        __builtin_constant_p.3 __builtin_prefetch.3 \
        __builtin_return_address.3 \
diff -r 088284749a8e -r ae35bc2065b6 share/man/man3/__USE.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man3/__USE.3    Thu Oct 17 16:50:36 2013 +0000
@@ -0,0 +1,122 @@
+.\"    $NetBSD: __USE.3,v 1.1 2013/10/17 16:50:36 christos Exp $
+.\"
+.\" Copyright (c) 2013 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" 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 October 17, 2013
+.Dt __USE 3
+.Os
+.Sh NAME
+.Nm __USE
+.Nd compile time macro that marks a variable as being used.
+.Sh SYNOPSIS
+.In sys/cdefs.h
+.Ft void
+.Fn __USE x
+.Sh DESCRIPTION
+The
+.Nm __USE
+macro can be used to omit warnings produced by certain compilers when
+variables are being set, but not used in a function.
+.Pp
+There are cases where it is simpler to mark a variable as used, as opposed
+to ifdef out its use:
+.Bd -literal -offset indent
+#ifdef DEBUG_FOO
+#define DPRINTF(a) printf a
+#else
+#define DPRINTF(a)
+
+void
+foo(void) {
+       int var;
+
+       var = getval();
+
+       DPRINTF(("val is %d\n", val));
+}
+.Ed
+.Pp
+In this case, ifdefing the code would make it:
+.Bd -literal -offset indent
+void
+foo(void) {
+#ifdef DEBUG_FOO
+       int var;
+
+       var = getval();
+
+       DPRINTF(("val is %d\n", val));
+#else
+       (void)getval();
+#endif
+}
+.Ed
+.Pp
+This is not desirable because it duplicates code.
+With the
+.Nm __USE
+macro this can be written as:
+.Bd -literal -offset indent
+void
+foo(void) {
+       int var;
+
+       var = getval();
+
+#ifdef DEBUG_FOO
+       DPRINTF(("val is %d\n", val));
+#else
+       __USE(var);
+#endif
+}
+.Ed
+.Pp
+without producing compiler warnings.
+.Pp
+Although it is simple to write:
+.Bd -literal -offset indent
+       (void)var;
+.Ed
+.Pp
+abstracting this into the macro allows for alternate implementations,
+as well as changing it to an empty implementation so that the liveness
+of the variable can be re-evaluated.
+.Sh IMPLEMENTATION NOTES
+.Nm
+is implemented as:
+.Bd -literal -offset indent
+#define __USE(a)       ((void)(a))
+.Ed
+.Sh SEE ALSO
+.Xr cc 1 ,
+.Xr cdefs 3
+.Sh CAVEATS
+.Nm
+should be used sparingly as it can cause valid warnings to be hidden.
+.Pp
+Use of this macro is non-portable; this is part of the implementation
+namespace and should only be used in 
+.Nx
+code.