Annotation of src/usr.bin/unifdef/unifdef.1, Revision 1.15
1.15 ! jmc 1: .\" $OpenBSD: unifdef.1,v 1.14 2003/10/23 09:09:13 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.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.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.
! 240: .Pp
1.1 deraadt 241: .El
242: .Pp
1.9 deraadt 243: The
1.8 aaron 244: .Nm
1.9 deraadt 245: utility copies its output to
1.1 deraadt 246: .Em stdout
247: and will take its input from
248: .Em stdin
249: if no
250: .Ar file
251: argument is given.
252: .Pp
1.9 deraadt 253: The
1.8 aaron 254: .Nm
1.9 deraadt 255: utility works nicely with the
1.1 deraadt 256: .Fl D Ns Ar sym
1.9 deraadt 257: option of
258: .Xr diff 1 .
1.1 deraadt 259: .Sh DIAGNOSTICS
1.9 deraadt 260: .Bl -item
261: .It
1.11 deraadt 262: Too many levels of nesting.
263: .It
264: Inappropriate
265: .Ic #elif ,
266: .Ic #else
267: or
268: .Ic #endif .
269: .It
270: Obfuscated preprocessor control line.
1.9 deraadt 271: .It
1.1 deraadt 272: Premature
273: .Tn EOF
1.11 deraadt 274: (with the line number of the most recent unterminated
275: .Ic #if ) .
276: .It
277: .Tn EOF
278: in comment.
1.9 deraadt 279: .El
280: .Pp
281: The
282: .Nm
283: utility exits 0 if the output is an exact copy of the input,
284: 1 if not, and 2 if in trouble.
1.13 jmc 285: .Sh SEE ALSO
286: .Xr cpp 1 ,
287: .Xr diff 1
288: .Sh HISTORY
289: The
290: .Nm
291: command appeared in
292: .Bx 4.3 .
1.9 deraadt 293: .Sh BUGS
294: Expression evaluation is very limited.
1.1 deraadt 295: .Pp
1.11 deraadt 296: Preprocessor control lines split across more than one physical line
297: (because of comments or backslash-newline)
298: cannot be handled in every situation.
299: .Pp
300: Trigraphs are not recognized.
301: .Pp
302: There is no support for symbols with different definitions at
303: different points in the source file.
304: .Pp
305: The text-mode and ignore functionality doesn't correspond to modern
306: .Xr cpp 1
307: 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