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 .\" $DragonFly: src/usr.bin/unifdef/unifdef.1,v 1.2 2003/06/17 04:29:33 dillon Exp $
  39 .\"
  40 .Dd September 24, 2002
  41 .Dt UNIFDEF 1
  42 .Os
  43 .Sh NAME
  44 .Nm unifdef , unifdefall
  45 .Nd remove preprocessor conditionals from code
  46 .Sh SYNOPSIS
  47 .Nm
  48 .Op Fl ceklst
  49 .Oo
  50 .Fl I Ns Ar path
  51 .Fl D Ns Ar sym Ns Op = Ns Ar val
  52 .Fl U Ns Ar sym
  53 .Fl iD Ns Ar sym Ns Op = Ns Ar val
  54 .Fl iU Ns Ar sym
  55 .Oc
  56 .Ar ...
  57 .Op Ar file
  58 .Nm unifdefall
  59 .Op Fl I Ns Ar path
  60 .Ar ...
  61 .Ar file
  62 .Sh DESCRIPTION
  63 The
  64 .Nm
  65 utility selectively processes conditional
  66 .Xr cpp 1
  67 directives.
  68 It removes from a file
  69 both the directives
  70 and any additional text that they specify should be removed,
  71 while otherwise leaving the file alone.
  72 .Pp
  73 The
  74 .Nm
  75 utility acts on
  76 .Ic #if , #ifdef , #ifndef , #elif , #else ,
  77 and
  78 .Ic #endif
  79 lines,
  80 and it understands only the commonly-used subset
  81 of the expression syntax for
  82 .Ic #if
  83 and
  84 .Ic #elif
  85 lines.
  86 It handles
  87 integer values of symbols defined on the command line,
  88 the
  89 .Fn defined
  90 operator applied to symbols defined or undefined on the command line,
  91 the operators
  92 .Ic \&! , < , > , <= , >= , == , != , && , || ,
  93 and parenthesized expressions.
  94 Anything that it does not understand is passed through unharmed.
  95 It only processes
  96 .Ic #ifdef
  97 and
  98 .Ic #ifndef
  99 directives if the symbol is specified on the command line,
 100 otherwise they are also passed through unchanged.
 101 By default, it ignores
 102 .Ic #if
 103 and
 104 .Ic #elif
 105 lines with constant expressions,
 106 or they may be processed by specifying the
 107 .Fl k
 108 flag on the command line.
 109 .Pp
 110 The
 111 .Nm
 112 utility also understands just enough about C
 113 to know when one of the directives is inactive
 114 because it is inside
 115 a comment,
 116 or affected by a backslash-continued line.
 117 It spots unusually-formatted preprocessor directives
 118 and knows when the layout is too odd to handle.
 119 .Pp
 120 A script called
 121 .Nm unifdefall
 122 can be used to remove all conditional
 123 .Xr cpp 1
 124 directives from a file.
 125 It uses
 126 .Nm Fl s
 127 and
 128 .Nm cpp Fl dM
 129 to get lists of all the controlling symbols
 130 and their definitions (or lack thereof),
 131 then invokes
 132 .Nm
 133 with appropriate arguments to process the file.
 134 .Pp
 135 Available options:
 136 .Bl -tag -width indent -compact
 137 .It Fl D Ns Ar sym Ns Op = Ns Ar val
 138 Specify that a symbol is defined,
 139 and optionally specify what value to give it
 140 for the purpose of handling
 141 .Ic #if
 142 and
 143 .Ic #elif
 144 directives.
 145 .Pp
 146 .It Fl U Ns Ar sym
 147 Specify that a symbol is undefined.
 148 If the same symbol appears in more than one argument,
 149 the last occurrence dominates.
 150 .Pp
 151 .It Fl c
 152 If the
 153 .Fl c
 154 flag is specified,
 155 then the operation of
 156 .Nm
 157 is complemented,
 158 i.e., the lines that would have been removed or blanked
 159 are retained and vice versa.
 160 .Pp
 161 .It Fl e
 162 Because
 163 .Nm
 164 processes its input one line at a time,
 165 it cannot remove preprocessor directives that span more than one line.
 166 The most common example of this is a directive with a multi-line
 167 comment hanging off its right hand end.
 168 By default,
 169 if
 170 .Nm
 171 has to process such a directive,
 172 it will complain that the line is too obfuscated.
 173 The
 174 .Fl e
 175 option changes the behaviour so that,
 176 where possible,
 177 such lines are left unprocessed instead of reporting an error.
 178 .Pp
 179 .It Fl k
 180 Process
 181 .Ic #if
 182 and
 183 .Ic #elif
 184 lines with constant expressions.
 185 By default, sections controlled by such lines are passed through unchanged
 186 because they typically start
 187 .Dq Li "#if 0"
 188 and are used as a kind of comment to sketch out future or past development.
 189 It would be rude to strip them out, just as it would be for normal comments.
 190 .Pp
 191 .It Fl l
 192 Replace removed lines with blank lines
 193 instead of deleting them.
 194 .Pp
 195 .It Fl s
 196 Instead of processing the input file as usual,
 197 this option causes
 198 .Nm
 199 to produce a list of symbols that appear in expressions
 200 that
 201 .Nm
 202 understands.
 203 It is useful in conjunction with the
 204 .Fl dM
 205 option of
 206 .Xr cpp 1
 207 for creating
 208 .Nm
 209 command lines.
 210 .Pp
 211 .It Fl t
 212 Disables parsing for C comments
 213 and line continuations,
 214 which is useful
 215 for plain text.
 216 .Pp
 217 .It Fl iD Ns Ar sym Ns Op = Ns Ar val
 218 .It Fl iU Ns Ar sym
 219 Ignore
 220 .Ic #ifdef Ns s .
 221 If your C code uses
 222 .Ic #ifdef Ns s
 223 to delimit non-C lines,
 224 such as comments
 225 or code which is under construction,
 226 then you must tell
 227 .Nm
 228 which symbols are used for that purpose so that it will not try to parse
 229 comments
 230 and line continuations
 231 inside those
 232 .Ic #ifdef Ns s .
 233 One specifies ignored symbols with
 234 .Fl iD Ns Ar sym Ns Oo = Ns Ar val Oc
 235 and
 236 .Fl iU Ns Ar sym
 237 similar to
 238 .Fl D Ns Ar sym Ns Op = Ns Ar val
 239 and
 240 .Fl U Ns Ar sym
 241 above.
 242 .Pp
 243 .It Fl I Ns Ar path
 244 Specifies to
 245 .Nm unifdefall
 246 an additional place to look for
 247 .Ic #include
 248 files.
 249 This option is ignored by
 250 .Nm
 251 for compatibility with
 252 .Xr cpp 1
 253 and to simplify the implementation of
 254 .Nm unifdefall .
 255 .El
 256 .Pp
 257 The
 258 .Nm
 259 utility copies its output to
 260 .Em stdout
 261 and will take its input from
 262 .Em stdin
 263 if no
 264 .Ar file
 265 argument is given.
 266 .Pp
 267 The
 268 .Nm
 269 utility works nicely with the
 270 .Fl D Ns Ar sym
 271 option of
 272 .Xr diff 1 .
 273 .Sh SEE ALSO
 274 .Xr cpp 1 ,
 275 .Xr diff 1
 276 .Sh DIAGNOSTICS
 277 .Bl -item
 278 .It
 279 Too many levels of nesting.
 280 .It
 281 Inappropriate
 282 .Ic #elif ,
 283 .Ic #else
 284 or
 285 .Ic #endif .
 286 .It
 287 Obfuscated preprocessor control line.
 288 .It
 289 Premature
 290 .Tn EOF
 291 (with the line number of the most recent unterminated
 292 .Ic #if ) .
 293 .It
 294 .Tn EOF
 295 in comment.
 296 .El
 297 .Pp
 298 The
 299 .Nm
 300 utility exits 0 if the output is an exact copy of the input,
 301 1 if not, and 2 if in trouble.
 302 .Sh BUGS
 303 Expression evaluation is very limited.
 304 .Pp
 305 Preprocessor control lines split across more than one physical line
 306 (because of comments or backslash-newline)
 307 cannot be handled in every situation.
 308 .Pp
 309 Trigraphs are not recognized.
 310 .Pp
 311 There is no support for symbols with different definitions at
 312 different points in the source file.
 313 .Pp
 314 The text-mode and ignore functionality does not correspond to modern
 315 .Xr cpp 1
 316 behaviour.
 317 .Sh HISTORY
 318 The
 319 .Nm
 320 command appeared in
 321 .Bx 4.3 .
 322 .Tn ANSI\~C
 323 support was added in
 324 .Fx 4.7 .