unifdef.txt

   1 UNIFDEF(1)                    Programmer's Manual                   UNIFDEF(1)
   2
   3 NAME
   4      unifdef, unifdefall -- remove preprocessor conditionals from code
   5
   6 SYNOPSIS
   7      unifdef [-bBcdehKkmnsStV] [-Ipath] [-[i]Dsym[=val]] [-[i]Usym] ...
   8              [-f defile] [-x {012}] [-M backext] [-o outfile] [infile ...]
   9      unifdefall [-Ipath] ... file
  10
  11 DESCRIPTION
  12      The unifdef utility selectively processes conditional cpp(1) directives.
  13      It removes from a file both the directives and any additional text that
  14      they specify should be removed, while otherwise leaving the file alone.
  15
  16      The unifdef utility acts on #if, #ifdef, #ifndef, #elif, #else, and
  17      #endif lines, using macros specified in -D and -U command line options or
  18      in -f definitions files.  A directive is processed if the macro specifi-
  19      cations are sufficient to provide a definite value for its control
  20      expression.  If the result is false, the directive and the following
  21      lines under its control are removed.  If the result is true, only the
  22      directive is removed.  An #ifdef or #ifndef directive is passed through
  23      unchanged if its controlling macro is not specified.  Any #if or #elif
  24      control expression that has an unknown value or that unifdef cannot parse
  25      is passed through unchanged.  By default, unifdef ignores #if and #elif
  26      lines with constant expressions; it can be told to process them by speci-
  27      fying the -k flag on the command line.
  28
  29      It understands a commonly-used subset of the expression syntax for #if
  30      and #elif lines: integer constants, integer values of macros defined on
  31      the command line, the defined() operator, the operators !, <, >, <=, >=,
  32      ==, !=, &&, ||, and parenthesized expressions.  A kind of ``short
  33      circuit'' evaluation is used for the && operator: if either operand is
  34      definitely false then the result is false, even if the value of the other
  35      operand is unknown.  Similarly, if either operand of || is definitely
  36      true then the result is true.
  37
  38      When evaluating an expression, unifdef does not expand macros first.  The
  39      value of a macro must be a simple number, not an expression.  A limited
  40      form of indirection is allowed, where one macro's value is the name of
  41      another.
  42
  43      In most cases, unifdef does not distinguish between object-like macros
  44      (without arguments) and function-like macros (with arguments).  A func-
  45      tion-like macro invocation can appear in #if and #elif control expres-
  46      sions.  If the macro is not explicitly defined, or is defined with the -D
  47      flag on the command-line, or with #define in a -f definitions file, its
  48      arguments are ignored.  If a macro is explicitly undefined on the command
  49      line with the -U flag, or with #undef in a -f definitions file, it may
  50      not have any arguments since this leads to a syntax error.
  51
  52      The unifdef utility understands just enough about C to know when one of
  53      the directives is inactive because it is inside a comment, or affected by
  54      a backslash-continued line.  It spots unusually-formatted preprocessor
  55      directives and knows when the layout is too odd for it to handle.
  56
  57      A script called unifdefall can be used to remove all conditional cpp(1)
  58      directives from a file.  It uses unifdef -s and cpp -dM to get lists of
  59      all the controlling macros and their definitions (or lack thereof), then
  60      invokes unifdef with appropriate arguments to process the file.
  61
  62 OPTIONS
  63      -Dsym=val
  64              Specify that a macro is defined to a given value.
  65
  66      -Dsym   Specify that a macro is defined to the value 1.
  67
  68      -Usym   Specify that a macro is undefined.
  69
  70              If the same macro appears in more than one argument, the last
  71              occurrence dominates.
  72
  73      -iDsym[=val]
  74      -iUsym  C strings, comments, and line continuations are ignored within
  75              #ifdef and #ifndef blocks controlled by macros specified with
  76              these options.
  77
  78      -f defile
  79              The file defile contains #define and #undef preprocessor direc-
  80              tives, which have the same effect as the corresponding -D and -U
  81              command-line arguments.  You can have multiple -f arguments and
  82              mix them with -D and -U arguments; later options override earlier
  83              ones.
  84
  85              Each directive must be on a single line.  Object-like macro defi-
  86              nitions (without arguments) are set to the given value.  Func-
  87              tion-like macro definitions (with arguments) are treated as if
  88              they are set to 1.
  89
  90      -b      Replace removed lines with blank lines instead of deleting them.
  91              Mutually exclusive with the -B option.
  92
  93      -B      Compress blank lines around a deleted section.  Mutually exclu-
  94              sive with the -b option.
  95
  96      -c      Complement, i.e., lines that would have been removed or blanked
  97              are retained and vice versa.
  98
  99      -d      Turn on printing of debugging messages.
 100
 101      -e      By default, unifdef will report an error if it needs to remove a
 102              preprocessor directive that spans more than one line, for exam-
 103              ple, if it has a multi-line comment hanging off its right hand
 104              end.  The -e flag makes it ignore the line instead.
 105
 106      -h      Print help.
 107
 108      -Ipath  Specifies to unifdefall an additional place to look for #include
 109              files.  This option is ignored by unifdef for compatibility with
 110              cpp(1) and to simplify the implementation of unifdefall.
 111
 112      -K      Always treat the result of && and || operators as unknown if
 113              either operand is unknown, instead of short-circuiting when
 114              unknown operands can't affect the result.  This option is for
 115              compatibility with older versions of unifdef.
 116
 117      -k      Process #if and #elif lines with constant expressions.  By
 118              default, sections controlled by such lines are passed through
 119              unchanged because they typically start ``#if 0'' and are used as
 120              a kind of comment to sketch out future or past development.  It
 121              would be rude to strip them out, just as it would be for normal
 122              comments.
 123
 124      -m      Modify one or more input files in place.
 125
 126      -M backext
 127              Modify input files in place, and keep backups of the original
 128              files by appending the backext to the input filenames.
 129
 130      -n      Add #line directives to the output following any deleted lines,
 131              so that errors produced when compiling the output file correspond
 132              to line numbers in the input file.
 133
 134      -o outfile
 135              Write output to the file outfile instead of the standard output
 136              when processing a single file.
 137
 138      -s      Instead of processing an input file as usual, this option causes
 139              unifdef to produce a list of macros that are used in preprocessor
 140              directive controlling expressions.
 141
 142      -S      Like the -s option, but the nesting depth of each macro is also
 143              printed.  This is useful for working out the number of possible
 144              combinations of interdependent defined/undefined macros.
 145
 146      -t      Disables parsing for C strings, comments, and line continuations,
 147              which is useful for plain text.  This is a blanket version of the
 148              -iD and -iU flags.
 149
 150      -V      Print version details.
 151
 152      -x {012}
 153              Set exit status mode to zero, one, or two.  See the EXIT STATUS
 154              section below for details.
 155
 156      The unifdef utility takes its input from stdin if there are no file argu-
 157      ments.  You must use the -m or -M options if there are multiple input
 158      files.  You can specify inut from stdin or output to stdout with `-'.
 159
 160      The unifdef utility works nicely with the -Dsym option of diff(1).
 161
 162 EXIT STATUS
 163      In normal usage the unifdef utility's exit status depends on the mode set
 164      using the -x option.
 165
 166      If the exit mode is zero (the default) then unifdef exits with status 0
 167      if the output is an exact copy of the input, or with status 1 if the out-
 168      put differs.
 169
 170      If the exit mode is one, unifdef exits with status 1 if the output is
 171      unmodified or 0 if it differs.
 172
 173      If the exit mode is two, unifdef exits with status zero in both cases.
 174
 175      In all exit modes, unifdef exits with status 2 if there is an error.
 176
 177      The exit status is 0 if the -h or -V command line options are given.
 178
 179 DIAGNOSTICS
 180      Too many levels of nesting.
 181
 182      Inappropriate #elif, #else or #endif.
 183
 184      Obfuscated preprocessor control line.
 185
 186      Premature EOF (with the line number of the most recent unterminated #if).
 187
 188      EOF in comment.
 189
 190 SEE ALSO
 191      cpp(1), diff(1)
 192
 193      The unifdef home page is http://dotat.at/prog/unifdef
 194
 195 HISTORY
 196      The unifdef command appeared in 2.9BSD.  ANSI C support was added in
 197      FreeBSD 4.7.
 198
 199 AUTHORS
 200      The original implementation was written by Dave Yost <Dave@Yost.com>.
 201      Tony Finch <dot@dotat.at> rewrote it to support ANSI C.
 202
 203 BUGS
 204      Expression evaluation is very limited.
 205
 206      Handling one line at a time means preprocessor directives split across
 207      more than one physical line (because of comments or backslash-newline)
 208      cannot be handled in every situation.
 209
 210      Trigraphs are not recognized.
 211
 212      There is no support for macros with different definitions at different
 213      points in the source file.
 214
 215      The text-mode and ignore functionality does not correspond to modern
 216      cpp(1) behaviour.
 217
 218                                 January 7, 2014