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