1.\" $NetBSD: __USE.3,v 1.2 2013/10/17 19:37:56 jnemeth Exp $ 2.\" 3.\" Copyright (c) 2013 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd October 17, 2013 28.Dt __USE 3 29.Os 30.Sh NAME 31.Nm __USE 32.Nd compile time macro that marks a variable as being used 33.Sh SYNOPSIS 34.In sys/cdefs.h 35.Ft void 36.Fn __USE x 37.Sh DESCRIPTION 38The 39.Nm __USE 40macro can be used to omit warnings produced by certain compilers when 41variables are being set, but not used in a function. 42.Pp 43There are cases where it is simpler to mark a variable as used, as opposed 44to ifdef out its use: 45.Bd -literal -offset indent 46#ifdef DEBUG_FOO 47#define DPRINTF(a) printf a 48#else 49#define DPRINTF(a) 50 51void 52foo(void) { 53 int var; 54 55 var = getval(); 56 57 DPRINTF(("val is %d\n", var)); 58} 59.Ed 60.Pp 61In this case, ifdefing the code would make it: 62.Bd -literal -offset indent 63void 64foo(void) { 65#ifdef DEBUG_FOO 66 int var; 67 68 var = getval(); 69 70 DPRINTF(("val is %d\n", var)); 71#else 72 (void)getval(); 73#endif 74} 75.Ed 76.Pp 77This is not desirable because it duplicates code. 78With the 79.Nm __USE 80macro this can be written as: 81.Bd -literal -offset indent 82void 83foo(void) { 84 int var; 85 86 var = getval(); 87 88#ifdef DEBUG_FOO 89 DPRINTF(("val is %d\n", var)); 90#else 91 __USE(var); 92#endif 93} 94.Ed 95.Pp 96without producing compiler warnings. 97.Pp 98Although it is simple to write: 99.Bd -literal -offset indent 100 (void)var; 101.Ed 102.Pp 103abstracting this into the macro allows for alternate implementations, 104as well as changing it to an empty implementation so that the liveness 105of the variable can be re-evaluated. 106.Sh IMPLEMENTATION NOTES 107.Nm 108is implemented as: 109.Bd -literal -offset indent 110#define __USE(a) ((void)(a)) 111.Ed 112.Sh SEE ALSO 113.Xr cc 1 , 114.Xr cdefs 3 115.Sh CAVEATS 116.Nm 117should be used sparingly as it can cause valid warnings to be hidden. 118.Pp 119Use of this macro is non-portable; this is part of the implementation 120namespace and should only be used in 121.Nx 122code. 123