usr.bin/unifdef/unifdef.1

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