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