Module Name: src
Committed By: christos
Date: Thu Oct 17 16:50:36 UTC 2013
Modified Files:
src/share/man/man3: Makefile
Added Files:
src/share/man/man3: __USE.3
Log Message:
describe the __USE macro
To generate a diff of this commit:
cvs rdiff -u -r1.81 -r1.82 src/share/man/man3/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man3/__USE.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.81 src/share/man/man3/Makefile:1.82
--- src/share/man/man3/Makefile:1.81 Thu Dec 6 20:54:41 2012
+++ src/share/man/man3/Makefile Thu Oct 17 12:50:36 2013
@@ -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 \
Added files:
Index: src/share/man/man3/__USE.3
diff -u /dev/null src/share/man/man3/__USE.3:1.1
--- /dev/null Thu Oct 17 12:50:36 2013
+++ src/share/man/man3/__USE.3 Thu Oct 17 12:50:36 2013
@@ -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.
