Annotation of src/usr.bin/unifdef/unifdef.1, Revision 1.27
1.27 ! mmcc 1: .\" $OpenBSD: unifdef.1,v 1.26 2015/12/05 23:27:35 mmcc 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.27 ! mmcc 33: .Dd $Mdocdate: December 5 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.
1.25 mmcc 315: If a zero length
1.26 mmcc 316: .Ar backext
1.25 mmcc 317: is given, no backup will be saved.
1.19 sthen 318: .Pp
1.21 jmc 319: .It Fl m
320: Modify one or more input files in place.
321: .Pp
1.19 sthen 322: .It Fl n
323: Add
324: .Li #line
325: directives to the output following any deleted lines,
326: so that errors produced when compiling the output file correspond to
327: line numbers in the input file.
328: .Pp
329: .It Fl o Ar outfile
330: Write output to the file
331: .Ar outfile
332: instead of the standard output when processing a single file.
1.9 deraadt 333: .Pp
1.21 jmc 334: .It Fl S
335: Like the
336: .Fl s
337: option, but the nesting depth of each macro is also printed.
338: This is useful for working out the number of possible combinations
339: of interdependent defined/undefined macros.
340: .Pp
1.9 deraadt 341: .It Fl s
1.19 sthen 342: Instead of processing an input file as usual,
1.9 deraadt 343: this option causes
344: .Nm
1.19 sthen 345: to produce a list of macros that are used in
346: preprocessor directive controlling expressions.
347: .Pp
1.1 deraadt 348: .It Fl t
1.19 sthen 349: Disables parsing for C strings, comments,
1.11 deraadt 350: and line continuations,
351: which is useful
1.1 deraadt 352: for plain text.
1.19 sthen 353: This is a blanket version of the
354: .Fl iD
355: and
356: .Fl iU
357: flags.
358: .Pp
359: .It Fl V
360: Print version details.
1.9 deraadt 361: .Pp
1.21 jmc 362: .It Fl x Cm 0 | 1 | 2
1.19 sthen 363: Set exit status mode to zero, one, or two.
364: See the
365: .Sx EXIT STATUS
366: section below for details.
1.1 deraadt 367: .El
368: .Pp
1.9 deraadt 369: The
1.8 aaron 370: .Nm
1.19 sthen 371: utility takes its input from
1.1 deraadt 372: .Em stdin
1.19 sthen 373: if there are no
1.1 deraadt 374: .Ar file
1.19 sthen 375: arguments.
1.21 jmc 376: The
1.19 sthen 377: .Fl m
378: or
379: .Fl M
1.21 jmc 380: options must be used if there are multiple input files.
381: A dash
382: .Pq -
383: specifies input from stdin or output to stdout.
1.1 deraadt 384: .Pp
1.9 deraadt 385: The
1.8 aaron 386: .Nm
1.9 deraadt 387: utility works nicely with the
1.22 jmc 388: .Fl D
1.9 deraadt 389: option of
390: .Xr diff 1 .
1.17 jmc 391: .Sh EXIT STATUS
1.19 sthen 392: In normal usage the
393: .Nm
394: utility's exit status depends on the mode set using the
395: .Fl x
396: option.
397: .Pp
398: If the exit mode is zero (the default) then
399: .Nm
400: exits with status 0 if the output is an exact copy of the input,
401: or with status 1 if the output differs.
402: .Pp
403: If the exit mode is one,
404: .Nm
405: exits with status 1 if the output is unmodified
406: or 0 if it differs.
407: .Pp
408: If the exit mode is two,
409: .Nm
410: exits with status zero in both cases.
411: .Pp
412: In all exit modes,
1.17 jmc 413: .Nm
1.19 sthen 414: exits with status 2 if there is an error.
415: .Pp
416: The exit status is 0 if the
417: .Fl h
418: or
419: .Fl V
420: command line options are given.
1.1 deraadt 421: .Sh DIAGNOSTICS
1.9 deraadt 422: .Bl -item
423: .It
1.27 ! mmcc 424: .Tn EOF
! 425: in comment.
1.11 deraadt 426: .It
427: Inappropriate
428: .Ic #elif ,
429: .Ic #else
430: or
431: .Ic #endif .
432: .It
433: Obfuscated preprocessor control line.
1.9 deraadt 434: .It
1.1 deraadt 435: Premature
436: .Tn EOF
1.11 deraadt 437: (with the line number of the most recent unterminated
438: .Ic #if ) .
439: .It
1.27 ! mmcc 440: Too many levels of nesting.
1.9 deraadt 441: .El
1.13 jmc 442: .Sh SEE ALSO
443: .Xr cpp 1 ,
444: .Xr diff 1
1.19 sthen 445: .Pp
446: The unifdef home page is
447: .Pa http://dotat.at/prog/unifdef
1.13 jmc 448: .Sh HISTORY
449: The
450: .Nm
451: command appeared in
1.19 sthen 452: .Bx 2.9 .
453: .Tn ANSI\~C
454: support was added in
455: .Fx 4.7 .
456: .Sh AUTHORS
457: The original implementation was written by
1.23 bentley 458: .An Dave Yost Aq Mt Dave@Yost.com .
459: .An Tony Finch Aq Mt dot@dotat.at
1.19 sthen 460: rewrote it to support
461: .Tn ANSI\~C .
1.9 deraadt 462: .Sh BUGS
463: Expression evaluation is very limited.
1.1 deraadt 464: .Pp
1.19 sthen 465: Handling one line at a time means
466: preprocessor directives split across more than one physical line
1.11 deraadt 467: (because of comments or backslash-newline)
468: cannot be handled in every situation.
469: .Pp
470: Trigraphs are not recognized.
471: .Pp
1.19 sthen 472: There is no support for macros with different definitions at
1.11 deraadt 473: different points in the source file.
474: .Pp
1.19 sthen 475: The text-mode and ignore functionality does not correspond to modern
1.11 deraadt 476: .Xr cpp 1
477: 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