unifdef.1

   1 .\" Copyright (c) 1985, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\" Copyright (c) 2002 - 2015 Tony Finch <dot@dotat.at>.  All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to Berkeley by
   6 .\" Dave Yost. It was rewritten to support ANSI C by Tony Finch.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd December 3, 2015
  33 .Dt UNIFDEF 1 PRM
  34 .Os " "
  35 .Sh NAME
  36 .Nm unifdef , unifdefall
  37 .Nd remove preprocessor conditionals from code
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl bBcdehKkmnsStV
  41 .Op Fl I Ns Ar path
  42 .Op Fl [i]D Ns Ar sym Ns Op = Ns Ar val
  43 .Op Fl [i]U Ns Ar sym
  44 .Ar ...
  45 .Op Fl f Ar defile
  46 .Op Fl x Bro Ar 012 Brc
  47 .Op Fl M Ar backext
  48 .Op Fl o Ar outfile
  49 .Op Ar infile ...
  50 .Nm unifdefall
  51 .Op Fl I Ns Ar path
  52 .Ar ...
  53 .Ar file
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  57 utility selectively processes conditional
  58 .Xr cpp 1
  59 directives.
  60 It removes from a file
  61 both the directives
  62 and any additional text that they specify should be removed,
  63 while otherwise leaving the file alone.
  64 .Pp
  65 The
  66 .Nm
  67 utility acts on
  68 .Ic #if , #ifdef , #ifndef ,
  69 .Ic #elif , #else ,
  70 and
  71 .Ic #endif
  72 lines,
  73 using macros specified in
  74 .Fl D
  75 and
  76 .Fl U
  77 command line options or in
  78 .Fl f
  79 definitions files.
  80 A directive is processed
  81 if the macro specifications are sufficient to provide
  82 a definite value for its control expression.
  83 If the result is false,
  84 the directive and the following lines under its control are removed.
  85 If the result is true,
  86 only the directive is removed.
  87 An
  88 .Ic #ifdef
  89 or
  90 .Ic #ifndef
  91 directive is passed through unchanged
  92 if its controlling macro is not specified.
  93 Any
  94 .Ic #if
  95 or
  96 .Ic #elif
  97 control expression that has an unknown value or that
  98 .Nm
  99 cannot parse is passed through unchanged.
 100 By default,
 101 .Nm
 102 ignores
 103 .Ic #if
 104 and
 105 .Ic #elif
 106 lines with constant expressions;
 107 it can be told to process them by specifying the
 108 .Fl k
 109 flag on the command line.
 110 .Pp
 111 It understands a commonly-used subset
 112 of the expression syntax for
 113 .Ic #if
 114 and
 115 .Ic #elif
 116 lines:
 117 integer constants,
 118 integer values of macros defined on the command line,
 119 the
 120 .Fn defined
 121 operator,
 122 the operators
 123 .Ic \&! , ~ , -
 124 (unary),
 125 .Ic * , / , % , + , - ,
 126 .Ic < , <= , > , >= , == , != , & , ^ , \&| ,
 127 .Ic && , || ,
 128 and parenthesized expressions.
 129 Division by zero is treated as an unknown value.
 130 A kind of
 131 .Dq "short circuit"
 132 evaluation is used for the
 133 .Ic &&
 134 operator:
 135 if either operand is definitely false then the result is false,
 136 even if the value of the other operand is unknown.
 137 Similarly,
 138 if either operand of
 139 .Ic ||
 140 is definitely true then the result is true.
 141 .Pp
 142 When evaluating an expression,
 143 .Nm
 144 does not expand macros first.
 145 The value of a macro must be a simple number,
 146 not an expression.
 147 A limited form of indirection is allowed,
 148 where one macro's value is the name of another.
 149 .Pp
 150 In most cases,
 151 .Nm
 152 does not distinguish between object-like macros
 153 (without arguments) and function-like macros (with arguments).
 154 A function-like macro invocation can appear in
 155 .Ic #if
 156 and
 157 .Ic #elif
 158 control expressions.
 159 If the macro is not explicitly defined,
 160 or is defined with the
 161 .Fl D
 162 flag on the command-line,
 163 or with
 164 .Ic #define
 165 in a
 166 .Fl f
 167 definitions file,
 168 its arguments are ignored.
 169 If a macro is explicitly undefined on the command line with the
 170 .Fl U
 171 flag,
 172 or with
 173 .Ic #undef
 174 in a
 175 .Fl f
 176 definitions file,
 177 it may not have any arguments since this leads to a syntax error.
 178 .Pp
 179 The
 180 .Nm
 181 utility understands just enough about C
 182 to know when one of the directives is inactive
 183 because it is inside
 184 a comment,
 185 or cannot be evaluated because it is split by a backslash-continued line.
 186 It spots unusually-formatted preprocessor directives
 187 and passes them through unchanged when the layout is too odd for it to handle.
 188 (See the
 189 .Sx BUGS
 190 section below.)
 191 .Pp
 192 A script called
 193 .Nm unifdefall
 194 can be used to remove all conditional
 195 .Xr cpp 1
 196 directives from a file.
 197 It uses
 198 .Nm Fl s
 199 and
 200 .Nm cpp Fl dM
 201 to get lists of all the controlling macros
 202 and their definitions (or lack thereof),
 203 then invokes
 204 .Nm
 205 with appropriate arguments to process the file.
 206 .Sh OPTIONS
 207 .Bl -tag -width indent -compact
 208 .It Fl D Ns Ar sym Ns = Ns Ar val
 209 Specify that a macro is defined to a given value.
 210 .Pp
 211 .It Fl D Ns Ar sym
 212 Specify that a macro is defined to the value 1.
 213 .Pp
 214 .It Fl U Ns Ar sym
 215 Specify that a macro is undefined.
 216 .Pp
 217 If the same macro appears in more than one argument,
 218 the last occurrence dominates.
 219 .Pp
 220 .It Fl iD Ns Ar sym Ns Op = Ns Ar val
 221 .It Fl iU Ns Ar sym
 222 C strings, comments,
 223 and line continuations
 224 are ignored within
 225 .Ic #ifdef
 226 and
 227 .Ic #ifndef
 228 blocks
 229 controlled by macros
 230 specified with these options.
 231 .Pp
 232 .It Fl f Ar defile
 233 The file
 234 .Ar defile
 235 contains
 236 .Ic #define
 237 and
 238 .Ic #undef
 239 preprocessor directives,
 240 which have the same effect as the corresponding
 241 .Fl D
 242 and
 243 .Fl U
 244 command-line arguments.
 245 You can have multiple
 246 .Fl f
 247 arguments and mix them with
 248 .Fl D
 249 and
 250 .Fl U
 251 arguments;
 252 later options override earlier ones.
 253 .Pp
 254 Each directive must be on a single line.
 255 Object-like macro definitions (without arguments)
 256 are set to the given value.
 257 Function-like macro definitions (with arguments)
 258 are treated as if they are set to 1.
 259 .Pp
 260 .Em Warning:
 261 string literals and character constants are not parsed correctly in
 262 .Fl f
 263 files.
 264 .Pp
 265 .It Fl b
 266 Replace removed lines with blank lines
 267 instead of deleting them.
 268 Mutually exclusive with the
 269 .Fl B
 270 option.
 271 .Pp
 272 .It Fl B
 273 Compress blank lines around a deleted section.
 274 Mutually exclusive with the
 275 .Fl b
 276 option.
 277 .Pp
 278 .It Fl c
 279 Complement,
 280 i.e., lines that would have been removed or blanked
 281 are retained and vice versa.
 282 .Pp
 283 .It Fl d
 284 Turn on printing of debugging messages.
 285 .Pp
 286 .It Fl e
 287 By default,
 288 .Nm
 289 will report an error if it needs to remove
 290 a preprocessor directive that spans more than one line,
 291 for example, if it has a multi-line
 292 comment hanging off its right hand end.
 293 The
 294 .Fl e
 295 flag makes it ignore the line instead.
 296 .Pp
 297 .It Fl h
 298 Print help.
 299 .Pp
 300 .It Fl I Ns Ar path
 301 Specifies to
 302 .Nm unifdefall
 303 an additional place to look for
 304 .Ic #include
 305 files.
 306 This option is ignored by
 307 .Nm
 308 for compatibility with
 309 .Xr cpp 1
 310 and to simplify the implementation of
 311 .Nm unifdefall .
 312 .Pp
 313 .It Fl K
 314 Always treat the result of
 315 .Ic &&
 316 and
 317 .Ic ||
 318 operators as unknown if either operand is unknown,
 319 instead of short-circuiting when unknown operands can't affect the result.
 320 This option is for compatibility with older versions of
 321 .Nm .
 322 .Pp
 323 .It Fl k
 324 Process
 325 .Ic #if
 326 and
 327 .Ic #elif
 328 lines with constant expressions.
 329 By default, sections controlled by such lines are passed through unchanged
 330 because they typically start
 331 .Dq Li "#if 0"
 332 and are used as a kind of comment to sketch out future or past development.
 333 It would be rude to strip them out, just as it would be for normal comments.
 334 .Pp
 335 .It Fl m
 336 Modify one or more input files in place.
 337 If an input file is not modified,
 338 the original is preserved instead of being overwritten with an identical copy.
 339 .Pp
 340 .It Fl M Ar backext
 341 Modify input files in place, and keep backups of the original files by
 342 appending the
 343 .Ar backext
 344 to the input filenames.
 345 A zero length
 346 .Ar backext
 347 behaves the same as the
 348 .Fl m
 349 option.
 350 .Pp
 351 .It Fl n
 352 Add
 353 .Li #line
 354 directives to the output following any deleted lines,
 355 so that errors produced when compiling the output file correspond to
 356 line numbers in the input file.
 357 .Pp
 358 .It Fl o Ar outfile
 359 Write output to the file
 360 .Ar outfile
 361 instead of the standard output when processing a single file.
 362 .Pp
 363 .It Fl s
 364 Instead of processing an input file as usual,
 365 this option causes
 366 .Nm
 367 to produce a list of macros that are used in
 368 preprocessor directive controlling expressions.
 369 .Pp
 370 .It Fl S
 371 Like the
 372 .Fl s
 373 option, but the nesting depth of each macro is also printed.
 374 This is useful for working out the number of possible combinations
 375 of interdependent defined/undefined macros.
 376 .Pp
 377 .It Fl t
 378 Disables parsing for C strings, comments,
 379 and line continuations,
 380 which is useful
 381 for plain text.
 382 This is a blanket version of the
 383 .Fl iD
 384 and
 385 .Fl iU
 386 flags.
 387 .Pp
 388 .It Fl V
 389 Print version details.
 390 .Pp
 391 .It Fl x Bro Ar 012 Brc
 392 Set exit status mode to zero, one, or two.
 393 See the
 394 .Sx EXIT STATUS
 395 section below for details.
 396 .El
 397 .Pp
 398 The
 399 .Nm
 400 utility takes its input from
 401 .Em stdin
 402 if there are no
 403 .Ar file
 404 arguments.
 405 You must use the
 406 .Fl m
 407 or
 408 .Fl M
 409 options if there are multiple input files.
 410 You can specify inut from stdin or output to stdout with
 411 .Ql - .
 412 .Pp
 413 The
 414 .Nm
 415 utility works nicely with the
 416 .Fl D Ns Ar sym
 417 option of
 418 .Xr diff 1 .
 419 .Sh EXIT STATUS
 420 In normal usage the
 421 .Nm
 422 utility's exit status depends on the mode set using the
 423 .Fl x
 424 option.
 425 .Pp
 426 If the exit mode is zero (the default) then
 427 .Nm
 428 exits with status 0 if the output is an exact copy of the input,
 429 or with status 1 if the output differs.
 430 .Pp
 431 If the exit mode is one,
 432 .Nm
 433 exits with status 1 if the output is unmodified
 434 or 0 if it differs.
 435 .Pp
 436 If the exit mode is two,
 437 .Nm
 438 exits with status zero in both cases.
 439 .Pp
 440 In all exit modes,
 441 .Nm
 442 exits with status 2 if there is an error.
 443 .Pp
 444 The exit status is 0 if the
 445 .Fl h
 446 or
 447 .Fl V
 448 command line options are given.
 449 .Sh DIAGNOSTICS
 450 .Bl -item
 451 .It
 452 .Tn EOF
 453 in comment
 454 .It
 455 Inappropriate
 456 .Ic #elif ,
 457 .Ic #else
 458 or
 459 .Ic #endif
 460 .It
 461 Missing macro name in #define or #undef
 462 .It
 463 Obfuscated preprocessor control line
 464 .It
 465 Premature
 466 .Tn EOF
 467 (with the line number of the most recent unterminated
 468 .Ic #if )
 469 .It
 470 Too many levels of nesting
 471 .It
 472 Unrecognized preprocessor directive
 473 .It
 474 Unterminated char or string literal
 475 .El
 476 .Sh SEE ALSO
 477 .Xr cpp 1 ,
 478 .Xr diff 1
 479 .Pp
 480 The unifdef home page is
 481 .Pa http://dotat.at/prog/unifdef
 482 .Sh HISTORY
 483 The
 484 .Nm
 485 command appeared in
 486 .Bx 2.9 .
 487 .Tn ANSI\~C
 488 support was added in
 489 .Fx 4.7 .
 490 .Sh AUTHORS
 491 .An -nosplit
 492 The original implementation was written by
 493 .An Dave Yost Aq Mt Dave@Yost.com .
 494 .An Tony Finch Aq Mt dot@dotat.at
 495 rewrote it to support
 496 .Tn ANSI\~C .
 497 .Sh BUGS
 498 .Bl -bullet
 499 .It
 500 Expression evaluation is very limited.
 501 .It
 502 Character constants are not evaluated.
 503 String literals and character constants in
 504 .Fl f
 505 definition files are ignored rather than parsed as
 506 part of a macro's replacement tokens.
 507 .It
 508 Only the basic form of C++ raw string literals is recognized,
 509 like
 510 .Li R"(string)"
 511 without delimiters as in
 512 .Li R"delimiter(string)delimiter" .
 513 .It
 514 Source files are processed one line at a time,
 515 so preprocessor directives split across more than one physical line
 516 (because of comments or backslash-newline)
 517 cannot be handled in every situation.
 518 .It
 519 Trigraphs are not recognized.
 520 .It
 521 There is no support for macros with different definitions at
 522 different points in the source file.
 523 .It
 524 The text-mode and ignore functionality does not correspond to modern
 525 .Xr cpp 1
 526 behaviour.
 527 .El
 528 .Pp
 529 Please send bug reports by email to
 530 .Aq Mt dot@dotat.at .