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