1.\" $NetBSD: unifdef.1,v 1.12 2009/06/11 03:16:34 ginsbach Exp $ 2.\" 3.\" Copyright (c) 1985, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Dave Yost. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" Portions of this code (support for #if and #elif) are Copyright (c) 34.\" 2002, 2003 Tony Finch. 35.\" 36.\" Redistribution and use in source and binary forms, with or without 37.\" modification, are permitted provided that the following conditions 38.\" are met: 39.\" 1. Redistributions of source code must retain the above copyright 40.\" notice, this list of conditions and the following disclaimer. 41.\" 2. Redistributions in binary form must reproduce the above copyright 42.\" notice, this list of conditions and the following disclaimer in the 43.\" documentation and/or other materials provided with the distribution. 44.\" 3. All advertising materials mentioning features or use of this software 45.\" must display the following acknowledgement: 46.\" This product includes software developed by the University of 47.\" California, Berkeley and its contributors. 48.\" 4. Neither the name of the University nor the names of its contributors 49.\" may be used to endorse or promote products derived from this software 50.\" without specific prior written permission. 51.\" 52.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 53.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 54.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 55.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 56.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 57.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 58.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 59.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 60.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 61.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 62.\" SUCH DAMAGE. 63.\" 64.\" @(#)unifdef.1 8.2 (Berkeley) 4/1/94 65.\" $dotat: things/unifdef.1,v 1.45 2003/01/20 14:37:08 fanf2 Exp $ 66.\" $FreeBSD: src/usr.bin/unifdef/unifdef.1,v 1.19 2003/01/20 12:41:41 fanf Exp $ 67.\" 68.Dd June 5, 2009 69.Dt UNIFDEF 1 70.Os 71.Sh NAME 72.Nm unifdef , 73.Nm unifdefall 74.Nd remove preprocessor conditionals from code 75.Sh SYNOPSIS 76.Nm 77.Op Fl ceklst 78.Op Fl I Ns Ar path 79.Op Fl D Ns Ar sym Ns Op = Ns Ar val 80.Op Fl U Ns Ar sym 81.Op Fl iD Ns Ar sym Ns Op = Ns Ar val 82.Op Fl iU Ns Ar sym 83.Ar ... 84.Op Fl o Ar output 85.Op Ar file 86.Nm unifdefall 87.Op Fl I Ns Ar path 88.Ar ... 89.Ar file 90.Sh DESCRIPTION 91The 92.Nm 93utility selectively processes conditional 94.Xr cpp 1 95directives. 96It removes from a file both the directives and any additional text 97that they specify should be removed, while otherwise leaving the 98file alone. 99.Pp 100The 101.Nm 102utility acts on 103.Ic #if , #ifdef , #ifndef , #elif , #else , 104and 105.Ic #endif 106lines, 107and it understands only the commonly-used subset 108of the expression syntax for 109.Ic #if 110and 111.Ic #elif 112lines. 113It handles 114integer values of symbols defined on the command line, 115the 116.Fn defined 117operator applied to symbols defined or undefined on the command line, 118the operators 119.Ic \&! , \*[Lt] , \*[Gt] , \*[Lt]= , \*[Gt]= , == , != , \*[Am]\*[Am] , || , 120and parenthesized expressions. 121Anything that it does not understand is passed through unharmed. 122It only processes 123.Ic #ifdef 124and 125.Ic #ifndef 126directives if the symbol is specified on the command line, 127otherwise they are also passed through unchanged. 128By default, it ignores 129.Ic #if 130and 131.Ic #elif 132lines with constant expressions, 133or they may be processed by specifying the 134.Fl k 135flag on the command line. 136.Pp 137The 138.Nm 139utility also understands just enough about C 140to know when one of the directives is inactive 141because it is inside 142a comment, 143or affected by a backslash-continued line. 144It spots unusually-formatted preprocessor directives 145and knows when the layout is too odd to handle. 146.Pp 147A script called 148.Nm unifdefall 149can be used to remove all conditional 150.Xr cpp 1 151directives from a file. 152It uses 153.Nm Fl s 154and 155.Nm cpp Fl dM 156to get lists of all the controlling symbols 157and their definitions (or lack thereof), 158then invokes 159.Nm 160with appropriate arguments to process the file. 161.Pp 162Available options: 163.Bl -tag -width indent -compact 164.It Fl D Ns Ar sym Ns Op = Ns Ar val 165Specify that a symbol is defined, 166and optionally specify what value to give it 167for the purpose of handling 168.Ic #if 169and 170.Ic #elif 171directives. 172.It Fl U Ns Ar sym 173Specify that a symbol is undefined. 174If the same symbol appears in more than one argument, 175the last occurrence dominates. 176.It Fl c 177If the 178.Fl c 179flag is specified, 180then the operation of 181.Nm 182is complemented, 183i.e., the lines that would have been removed or blanked 184are retained and vice versa. 185.It Fl e 186Because 187.Nm 188processes its input one line at a time, 189it cannot remove preprocessor directives that span more than one line. 190The most common example of this is a directive with a multi-line 191comment hanging off its right hand end. 192By default, 193if 194.Nm 195has to process such a directive, 196it will complain that the line is too obfuscated. 197The 198.Fl e 199option changes the behaviour so that, 200where possible, 201such lines are left unprocessed instead of reporting an error. 202.It Fl k 203Process 204.Ic #if 205and 206.Ic #elif 207lines with constant expressions. 208By default, sections controlled by such lines are passed through unchanged 209because they typically start 210.Dq Li "#if 0" 211and are used as a kind of comment to sketch out future or past development. 212It would be rude to strip them out, just as it would be for normal comments. 213.It Fl l 214Replace removed lines with blank lines 215instead of deleting them. 216.It Fl o Ar output 217The argument given is the name of an 218.Ar output 219file to be used instead of the standard output. 220This file can be the same as the input file. 221.It Fl s 222Instead of processing the input file as usual, 223this option causes 224.Nm 225to produce a list of symbols that appear in expressions 226that 227.Nm 228understands. 229It is useful in conjunction with the 230.Fl dM 231option of 232.Xr cpp 1 233for creating 234.Nm 235command lines. 236.It Fl t 237Disables parsing for C comments 238and line continuations, 239which is useful 240for plain text. 241.It Fl iD Ns Ar sym Ns Op = Ns Ar val 242.It Fl iU Ns Ar sym 243Ignore 244.Ic #ifdef Ns s . 245If your C code uses 246.Ic #ifdef Ns s 247to delimit non-C lines, 248such as comments 249or code which is under construction, 250then you must tell 251.Nm 252which symbols are used for that purpose so that it will not try to parse 253comments 254and line continuations 255inside those 256.Ic #ifdef Ns s . 257One specifies ignored symbols with 258.Fl iD Ns Ar sym Ns Oo = Ns Ar val Oc 259and 260.Fl iU Ns Ar sym 261similar to 262.Fl D Ns Ar sym Ns Op = Ns Ar val 263and 264.Fl U Ns Ar sym 265above. 266.It Fl I Ns Ar path 267Specifies to 268.Nm unifdefall 269an additional place to look for 270.Ic #include 271files. 272This option is ignored by 273.Nm 274for compatibility with 275.Xr cpp 1 276and to simplify the implementation of 277.Nm unifdefall . 278.El 279.Pp 280The 281.Nm 282utility copies its output to 283.Em stdout 284and will take its input from 285.Em stdin 286if no 287.Ar file 288argument is given. 289.Pp 290The 291.Nm 292utility works nicely with the 293.Fl D Ns Ar sym 294option of 295.Xr diff 1 . 296.Sh DIAGNOSTICS 297.Bl -item 298.It 299Too many levels of nesting. 300.It 301Inappropriate 302.Ic #elif , 303.Ic #else 304or 305.Ic #endif . 306.It 307Obfuscated preprocessor control line. 308.It 309Premature 310.Dv EOF 311(with the line number of the most recent unterminated 312.Ic #if ) . 313.It 314.Dv EOF 315in comment. 316.El 317.Pp 318The 319.Nm 320utility exits 0 if the output is an exact copy of the input, 3211 if not, and 2 if in trouble. 322.Sh SEE ALSO 323.Xr cpp 1 , 324.Xr diff 1 325.Sh HISTORY 326The 327.Nm 328command appeared in 329.Bx 4.3 . 330.Tn ANSI\~C 331support was added in 332.Fx 4.7 . 333.Sh BUGS 334Expression evaluation is very limited. 335.Pp 336Preprocessor control lines split across more than one physical line 337(because of comments or backslash-newline) 338cannot be handled in every situation. 339.Pp 340Trigraphs are not recognized. 341.Pp 342There is no support for symbols with different definitions at 343different points in the source file. 344.Pp 345The text-mode and ignore functionality does not correspond to modern 346.Xr cpp 1 347behaviour. 348