Annotation of src/usr.bin/unifdef/unifdef.1, Revision 1.24
1.24 ! schwarze 1: .\" $OpenBSD: unifdef.1,v 1.23 2015/02/17 16:29:16 bentley Exp $
1.1 deraadt 2: .\" Copyright (c) 1985, 1991, 1993
3: .\" The Regents of the University of California. All rights reserved.
1.19 sthen 4: .\" Copyright (c) 2002 - 2013 Tony Finch <dot@dotat.at>. All rights reserved.
1.1 deraadt 5: .\"
6: .\" This code is derived from software contributed to Berkeley by
1.19 sthen 7: .\" Dave Yost. It was rewritten to support ANSI C by Tony Finch.
1.1 deraadt 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.
1.12 millert 17: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 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: .\"
1.24 ! schwarze 33: .Dd $Mdocdate: February 17 2015 $
1.1 deraadt 34: .Dt UNIFDEF 1
1.4 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
1.10 deraadt 37: .Nm unifdef
1.9 deraadt 38: .Nd remove preprocessor conditionals from code
1.1 deraadt 39: .Sh SYNOPSIS
1.9 deraadt 40: .Nm
1.21 jmc 41: .Op Fl BbcdehKkmnSstV
1.24 ! schwarze 42: .Op Fl Oo Cm i Oc Ns Cm D Ns Ar sym Ns Op = Ns Ar val
! 43: .Op Fl Oo Cm i Oc Ns Cm U Ns Ar sym
1.19 sthen 44: .Op Fl f Ar defile
45: .Op Fl M Ar backext
46: .Op Fl o Ar outfile
1.21 jmc 47: .Op Fl x Cm 0 | 1 | 2
48: .Ar
1.1 deraadt 49: .Sh DESCRIPTION
1.9 deraadt 50: The
1.8 aaron 51: .Nm
1.9 deraadt 52: utility selectively processes conditional
53: .Xr cpp 1
54: directives.
55: It removes from a file
56: both the directives
57: and any additional text that they specify should be removed,
58: while otherwise leaving the file alone.
59: .Pp
60: The
1.8 aaron 61: .Nm
1.9 deraadt 62: utility acts on
1.14 jmc 63: .Ic #if , #ifdef , #ifndef ,
64: .Ic #elif , #else ,
1.9 deraadt 65: and
66: .Ic #endif
67: lines,
1.19 sthen 68: using macros specified in
69: .Fl D
70: and
71: .Fl U
72: command line options or in
73: .Fl f
1.22 jmc 74: definition files.
1.19 sthen 75: A directive is processed
76: if the macro specifications are sufficient to provide
77: a definite value for its control expression.
78: If the result is false,
79: the directive and the following lines under its control are removed.
80: If the result is true,
81: only the directive is removed.
82: An
83: .Ic #ifdef
84: or
85: .Ic #ifndef
86: directive is passed through unchanged
87: if its controlling macro is not specified.
88: Any
89: .Ic #if
90: or
91: .Ic #elif
92: control expression that has an unknown value or that
93: .Nm
94: cannot parse is passed through unchanged.
95: By default,
96: .Nm
97: ignores
98: .Ic #if
99: and
100: .Ic #elif
101: lines with constant expressions;
102: it can be told to process them by specifying the
103: .Fl k
104: flag on the command line.
105: .Pp
106: It understands a commonly-used subset
1.9 deraadt 107: of the expression syntax for
108: .Ic #if
109: and
110: .Ic #elif
1.19 sthen 111: lines:
112: integer constants,
113: integer values of macros defined on the command line,
1.9 deraadt 114: the
115: .Fn defined
1.19 sthen 116: operator,
1.9 deraadt 117: the operators
1.19 sthen 118: .Ic \&! , < , > ,
119: .Ic <= , >= , == , != ,
120: .Ic && , || ,
1.9 deraadt 121: and parenthesized expressions.
1.19 sthen 122: A kind of
123: .Dq "short circuit"
124: evaluation is used for the
125: .Ic &&
126: operator:
127: if either operand is definitely false then the result is false,
128: even if the value of the other operand is unknown.
129: Similarly,
130: if either operand of
131: .Ic ||
132: is definitely true then the result is true.
133: .Pp
134: When evaluating an expression,
135: .Nm
136: does not expand macros first.
137: The value of a macro must be a simple number,
138: not an expression.
139: A limited form of indirection is allowed,
140: where one macro's value is the name of another.
141: .Pp
142: In most cases,
143: .Nm
144: does not distinguish between object-like macros
145: (without arguments) and function-like macros (with arguments).
146: A function-like macro invocation can appear in
1.9 deraadt 147: .Ic #if
148: and
149: .Ic #elif
1.19 sthen 150: control expressions.
151: If the macro is not explicitly defined,
152: or is defined with the
153: .Fl D
154: flag on the command-line,
155: or with
156: .Ic #define
157: in a
158: .Fl f
1.22 jmc 159: definition file,
1.19 sthen 160: its arguments are ignored.
161: If a macro is explicitly undefined on the command line with the
162: .Fl U
163: flag,
164: or with
165: .Ic #undef
166: in a
167: .Fl f
1.22 jmc 168: definition file,
1.19 sthen 169: it may not have any arguments since this leads to a syntax error.
1.9 deraadt 170: .Pp
171: The
172: .Nm
1.19 sthen 173: utility understands just enough about C
1.9 deraadt 174: to know when one of the directives is inactive
1.1 deraadt 175: because it is inside
176: a comment,
1.11 deraadt 177: or affected by a backslash-continued line.
178: It spots unusually-formatted preprocessor directives
1.19 sthen 179: and knows when the layout is too odd for it to handle.
1.21 jmc 180: .Pp
181: The options are as follows:
182: .Pp
1.19 sthen 183: .Bl -tag -width indent -compact
1.21 jmc 184: .It Fl B
185: Compress blank lines around a deleted section.
186: Mutually exclusive with the
187: .Fl b
188: option.
1.19 sthen 189: .Pp
1.21 jmc 190: .It Fl b
191: Replace removed lines with blank lines
192: instead of deleting them.
193: Mutually exclusive with the
194: .Fl B
195: option.
1.1 deraadt 196: .Pp
1.21 jmc 197: .It Fl c
198: Complement.
199: That is, lines that would have been removed or blanked
200: are retained and vice versa.
1.19 sthen 201: .Pp
1.20 sthen 202: .Sm off
203: .It Xo
1.21 jmc 204: .Fl D Ar sym
1.20 sthen 205: .Op = Ar val
206: .Xc
207: .Sm on
1.21 jmc 208: .It Fl U Ns Ar sym
209: Specify that a macro is defined
210: .Pq Fl D
211: to a given value,
212: to 1 if no value is given,
213: or undefined
214: .Pq Fl U .
215: .Pp
216: If the same macro appears in more than one argument,
217: the last occurrence dominates.
218: .Pp
219: .It Fl d
220: Turn on printing of debugging messages.
221: .Pp
222: .It Fl e
223: By default,
1.20 sthen 224: .Nm
1.21 jmc 225: will report an error if it needs to remove
226: a preprocessor directive that spans more than one line,
227: for example, if it has a multi-line
228: comment hanging off its right hand end.
229: The
230: .Fl e
231: flag makes it ignore the line instead.
1.19 sthen 232: .Pp
233: .It Fl f Ar defile
234: The file
235: .Ar defile
236: contains
237: .Ic #define
238: and
239: .Ic #undef
240: preprocessor directives,
241: which have the same effect as the corresponding
242: .Fl D
243: and
244: .Fl U
1.21 jmc 245: command line arguments.
246: Multiple
1.19 sthen 247: .Fl f
1.21 jmc 248: arguments can be given and mixed with
1.19 sthen 249: .Fl D
250: and
251: .Fl U
252: arguments;
253: later options override earlier ones.
254: .Pp
255: Each directive must be on a single line.
256: Object-like macro definitions (without arguments)
257: are set to the given value.
258: Function-like macro definitions (with arguments)
259: are treated as if they are set to 1.
260: .Pp
1.21 jmc 261: .Sm off
262: .It Xo
263: .Fl iD Ar sym
264: .Op = Ar val
265: .Xc
266: .Sm on
267: .It Fl iU Ns Ar sym
268: Ignore
269: .Ic #ifdef Ns s .
270: If C code uses
271: .Ic #ifdef Ns s
272: to delimit non-C lines,
273: such as comments
274: or code which is under construction,
275: this tells
276: .Nm
277: which symbols are used for that purpose so that it will not try to parse
278: comments and line continuations
279: inside those
280: .Ic #ifdef Ns s .
1.19 sthen 281: .Pp
1.21 jmc 282: If the same macro appears in more than one argument,
283: the last occurrence dominates.
1.19 sthen 284: .Pp
285: .It Fl h
286: Print help.
287: .Pp
288: .It Fl K
289: Always treat the result of
290: .Ic &&
1.15 jmc 291: and
1.19 sthen 292: .Ic ||
293: operators as unknown if either operand is unknown,
294: instead of short-circuiting when unknown operands can't affect the result.
295: This option is for compatibility with older versions of
296: .Nm .
1.15 jmc 297: .Pp
1.9 deraadt 298: .It Fl k
299: Process
300: .Ic #if
301: and
302: .Ic #elif
303: lines with constant expressions.
304: By default, sections controlled by such lines are passed through unchanged
305: because they typically start
1.19 sthen 306: .Dq Li "#if 0"
1.9 deraadt 307: and are used as a kind of comment to sketch out future or past development.
308: It would be rude to strip them out, just as it would be for normal comments.
309: .Pp
1.19 sthen 310: .It Fl M Ar backext
311: Modify input files in place, and keep backups of the original files by
312: appending the
313: .Ar backext
314: to the input filenames.
315: .Pp
1.21 jmc 316: .It Fl m
317: Modify one or more input files in place.
318: .Pp
1.19 sthen 319: .It Fl n
320: Add
321: .Li #line
322: directives to the output following any deleted lines,
323: so that errors produced when compiling the output file correspond to
324: line numbers in the input file.
325: .Pp
326: .It Fl o Ar outfile
327: Write output to the file
328: .Ar outfile
329: instead of the standard output when processing a single file.
1.9 deraadt 330: .Pp
1.21 jmc 331: .It Fl S
332: Like the
333: .Fl s
334: option, but the nesting depth of each macro is also printed.
335: This is useful for working out the number of possible combinations
336: of interdependent defined/undefined macros.
337: .Pp
1.9 deraadt 338: .It Fl s
1.19 sthen 339: Instead of processing an input file as usual,
1.9 deraadt 340: this option causes
341: .Nm
1.19 sthen 342: to produce a list of macros that are used in
343: preprocessor directive controlling expressions.
344: .Pp
1.1 deraadt 345: .It Fl t
1.19 sthen 346: Disables parsing for C strings, comments,
1.11 deraadt 347: and line continuations,
348: which is useful
1.1 deraadt 349: for plain text.
1.19 sthen 350: This is a blanket version of the
351: .Fl iD
352: and
353: .Fl iU
354: flags.
355: .Pp
356: .It Fl V
357: Print version details.
1.9 deraadt 358: .Pp
1.21 jmc 359: .It Fl x Cm 0 | 1 | 2
1.19 sthen 360: Set exit status mode to zero, one, or two.
361: See the
362: .Sx EXIT STATUS
363: section below for details.
1.1 deraadt 364: .El
365: .Pp
1.9 deraadt 366: The
1.8 aaron 367: .Nm
1.19 sthen 368: utility takes its input from
1.1 deraadt 369: .Em stdin
1.19 sthen 370: if there are no
1.1 deraadt 371: .Ar file
1.19 sthen 372: arguments.
1.21 jmc 373: The
1.19 sthen 374: .Fl m
375: or
376: .Fl M
1.21 jmc 377: options must be used if there are multiple input files.
378: A dash
379: .Pq -
380: specifies input from stdin or output to stdout.
1.1 deraadt 381: .Pp
1.9 deraadt 382: The
1.8 aaron 383: .Nm
1.9 deraadt 384: utility works nicely with the
1.22 jmc 385: .Fl D
1.9 deraadt 386: option of
387: .Xr diff 1 .
1.17 jmc 388: .Sh EXIT STATUS
1.19 sthen 389: In normal usage the
390: .Nm
391: utility's exit status depends on the mode set using the
392: .Fl x
393: option.
394: .Pp
395: If the exit mode is zero (the default) then
396: .Nm
397: exits with status 0 if the output is an exact copy of the input,
398: or with status 1 if the output differs.
399: .Pp
400: If the exit mode is one,
401: .Nm
402: exits with status 1 if the output is unmodified
403: or 0 if it differs.
404: .Pp
405: If the exit mode is two,
406: .Nm
407: exits with status zero in both cases.
408: .Pp
409: In all exit modes,
1.17 jmc 410: .Nm
1.19 sthen 411: exits with status 2 if there is an error.
412: .Pp
413: The exit status is 0 if the
414: .Fl h
415: or
416: .Fl V
417: command line options are given.
1.1 deraadt 418: .Sh DIAGNOSTICS
1.9 deraadt 419: .Bl -item
420: .It
1.11 deraadt 421: Too many levels of nesting.
422: .It
423: Inappropriate
424: .Ic #elif ,
425: .Ic #else
426: or
427: .Ic #endif .
428: .It
429: Obfuscated preprocessor control line.
1.9 deraadt 430: .It
1.1 deraadt 431: Premature
432: .Tn EOF
1.11 deraadt 433: (with the line number of the most recent unterminated
434: .Ic #if ) .
435: .It
436: .Tn EOF
437: in comment.
1.9 deraadt 438: .El
1.13 jmc 439: .Sh SEE ALSO
440: .Xr cpp 1 ,
441: .Xr diff 1
1.19 sthen 442: .Pp
443: The unifdef home page is
444: .Pa http://dotat.at/prog/unifdef
1.13 jmc 445: .Sh HISTORY
446: The
447: .Nm
448: command appeared in
1.19 sthen 449: .Bx 2.9 .
450: .Tn ANSI\~C
451: support was added in
452: .Fx 4.7 .
453: .Sh AUTHORS
454: The original implementation was written by
1.23 bentley 455: .An Dave Yost Aq Mt Dave@Yost.com .
456: .An Tony Finch Aq Mt dot@dotat.at
1.19 sthen 457: rewrote it to support
458: .Tn ANSI\~C .
1.9 deraadt 459: .Sh BUGS
460: Expression evaluation is very limited.
1.1 deraadt 461: .Pp
1.19 sthen 462: Handling one line at a time means
463: preprocessor directives split across more than one physical line
1.11 deraadt 464: (because of comments or backslash-newline)
465: cannot be handled in every situation.
466: .Pp
467: Trigraphs are not recognized.
468: .Pp
1.19 sthen 469: There is no support for macros with different definitions at
1.11 deraadt 470: different points in the source file.
471: .Pp
1.19 sthen 472: The text-mode and ignore functionality does not correspond to modern
1.11 deraadt 473: .Xr cpp 1
474: behaviour.
![[BACK]](/icons/back.gif){kind=icon}
Return to unifdef.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / unifdef