| blob | fb75d851c1b7585d4d03d60ba81415669660727d |
1 .\" $NetBSD: unifdef.1,v 1.12 2009/06/11 03:16:34 ginsbach Exp $
2 .\"
3 .\" Copyright (c) 1985, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to Berkeley by
7 .\" Dave Yost.
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.
17 .\" 3. Neither the name of the University nor the names of its contributors
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 .\"
33 .\" Portions of this code (support for #if and #elif) are Copyright (c)
34 .\" 2002, 2003 Tony Finch.
35 .\"
36 .\" Redistribution and use in source and binary forms, with or without
37 .\" modification, are permitted provided that the following conditions
38 .\" are met:
39 .\" 1. Redistributions of source code must retain the above copyright
40 .\" notice, this list of conditions and the following disclaimer.
41 .\" 2. Redistributions in binary form must reproduce the above copyright
42 .\" notice, this list of conditions and the following disclaimer in the
43 .\" documentation and/or other materials provided with the distribution.
44 .\" 3. All advertising materials mentioning features or use of this software
45 .\" must display the following acknowledgement:
46 .\" This product includes software developed by the University of
47 .\" California, Berkeley and its contributors.
48 .\" 4. Neither the name of the University nor the names of its contributors
49 .\" may be used to endorse or promote products derived from this software
50 .\" without specific prior written permission.
51 .\"
52 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
53 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
54 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
55 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
56 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
57 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
58 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
59 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
60 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
61 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
62 .\" SUCH DAMAGE.
63 .\"
64 .\" @(#)unifdef.1 8.2 (Berkeley) 4/1/94
65 .\" $dotat: things/unifdef.1,v 1.45 2003/01/20 14:37:08 fanf2 Exp $
66 .\" $FreeBSD: src/usr.bin/unifdef/unifdef.1,v 1.19 2003/01/20 12:41:41 fanf Exp $
67 .\"
68 .Dd June 5, 2009
69 .Dt UNIFDEF 1
70 .Os
71 .Sh NAME
72 .Nm unifdef ,
73 .Nm unifdefall
74 .Nd remove preprocessor conditionals from code
75 .Sh SYNOPSIS
76 .Nm
77 .Op Fl ceklst
78 .Op Fl I Ns Ar path
79 .Op Fl D Ns Ar sym Ns Op = Ns Ar val
80 .Op Fl U Ns Ar sym
81 .Op Fl iD Ns Ar sym Ns Op = Ns Ar val
82 .Op Fl iU Ns Ar sym
83 .Ar ...
84 .Op Fl o Ar output
85 .Op Ar file
86 .Nm unifdefall
87 .Op Fl I Ns Ar path
88 .Ar ...
89 .Ar file
90 .Sh DESCRIPTION
91 The
92 .Nm
93 utility selectively processes conditional
94 .Xr cpp 1
95 directives.
96 It removes from a file both the directives and any additional text
97 that they specify should be removed, while otherwise leaving the
98 file alone.
99 .Pp
100 The
101 .Nm
102 utility acts on
103 .Ic #if , #ifdef , #ifndef , #elif , #else ,
104 and
105 .Ic #endif
106 lines,
107 and it understands only the commonly-used subset
108 of the expression syntax for
109 .Ic #if
110 and
111 .Ic #elif
112 lines.
113 It handles
114 integer values of symbols defined on the command line,
115 the
116 .Fn defined
117 operator applied to symbols defined or undefined on the command line,
118 the operators
119 .Ic \&! , \*[Lt] , \*[Gt] , \*[Lt]= , \*[Gt]= , == , != , \*[Am]\*[Am] , || ,
120 and parenthesized expressions.
121 Anything that it does not understand is passed through unharmed.
122 It only processes
123 .Ic #ifdef
124 and
125 .Ic #ifndef
126 directives if the symbol is specified on the command line,
127 otherwise they are also passed through unchanged.
128 By default, it ignores
129 .Ic #if
130 and
131 .Ic #elif
132 lines with constant expressions,
133 or they may be processed by specifying the
134 .Fl k
135 flag on the command line.
136 .Pp
137 The
138 .Nm
139 utility also understands just enough about C
140 to know when one of the directives is inactive
141 because it is inside
142 a comment,
143 or affected by a backslash-continued line.
144 It spots unusually-formatted preprocessor directives
145 and knows when the layout is too odd to handle.
146 .Pp
147 A script called
148 .Nm unifdefall
149 can be used to remove all conditional
150 .Xr cpp 1
151 directives from a file.
152 It uses
153 .Nm Fl s
154 and
155 .Nm cpp Fl dM
156 to get lists of all the controlling symbols
157 and their definitions (or lack thereof),
158 then invokes
159 .Nm
160 with appropriate arguments to process the file.
161 .Pp
162 Available options:
163 .Bl -tag -width indent -compact
164 .It Fl D Ns Ar sym Ns Op = Ns Ar val
165 Specify that a symbol is defined,
166 and optionally specify what value to give it
167 for the purpose of handling
168 .Ic #if
169 and
170 .Ic #elif
171 directives.
172 .It Fl U Ns Ar sym
173 Specify that a symbol is undefined.
174 If the same symbol appears in more than one argument,
175 the last occurrence dominates.
176 .It Fl c
177 If the
178 .Fl c
179 flag is specified,
180 then the operation of
181 .Nm
182 is complemented,
183 i.e., the lines that would have been removed or blanked
184 are retained and vice versa.
185 .It Fl e
186 Because
187 .Nm
188 processes its input one line at a time,
189 it cannot remove preprocessor directives that span more than one line.
190 The most common example of this is a directive with a multi-line
191 comment hanging off its right hand end.
192 By default,
193 if
194 .Nm
195 has to process such a directive,
196 it will complain that the line is too obfuscated.
197 The
198 .Fl e
199 option changes the behaviour so that,
200 where possible,
201 such lines are left unprocessed instead of reporting an error.
202 .It Fl k
203 Process
204 .Ic #if
205 and
206 .Ic #elif
207 lines with constant expressions.
208 By default, sections controlled by such lines are passed through unchanged
209 because they typically start
210 .Dq Li "#if 0"
211 and are used as a kind of comment to sketch out future or past development.
212 It would be rude to strip them out, just as it would be for normal comments.
213 .It Fl l
214 Replace removed lines with blank lines
215 instead of deleting them.
216 .It Fl o Ar output
217 The argument given is the name of an
218 .Ar output
219 file to be used instead of the standard output.
220 This file can be the same as the input file.
221 .It Fl s
222 Instead of processing the input file as usual,
223 this option causes
224 .Nm
225 to produce a list of symbols that appear in expressions
226 that
227 .Nm
228 understands.
229 It is useful in conjunction with the
230 .Fl dM
231 option of
232 .Xr cpp 1
233 for creating
234 .Nm
235 command lines.
236 .It Fl t
237 Disables parsing for C comments
238 and line continuations,
239 which is useful
240 for plain text.
241 .It Fl iD Ns Ar sym Ns Op = Ns Ar val
242 .It Fl iU Ns Ar sym
243 Ignore
244 .Ic #ifdef Ns s .
245 If your C code uses
246 .Ic #ifdef Ns s
247 to delimit non-C lines,
248 such as comments
249 or code which is under construction,
250 then you must tell
251 .Nm
252 which symbols are used for that purpose so that it will not try to parse
253 comments
254 and line continuations
255 inside those
256 .Ic #ifdef Ns s .
257 One specifies ignored symbols with
258 .Fl iD Ns Ar sym Ns Oo = Ns Ar val Oc
259 and
260 .Fl iU Ns Ar sym
261 similar to
262 .Fl D Ns Ar sym Ns Op = Ns Ar val
263 and
264 .Fl U Ns Ar sym
265 above.
266 .It Fl I Ns Ar path
267 Specifies to
268 .Nm unifdefall
269 an additional place to look for
270 .Ic #include
271 files.
272 This option is ignored by
273 .Nm
274 for compatibility with
275 .Xr cpp 1
276 and to simplify the implementation of
277 .Nm unifdefall .
278 .El
279 .Pp
280 The
281 .Nm
282 utility copies its output to
283 .Em stdout
284 and will take its input from
285 .Em stdin
286 if no
287 .Ar file
288 argument is given.
289 .Pp
290 The
291 .Nm
292 utility works nicely with the
293 .Fl D Ns Ar sym
294 option of
295 .Xr diff 1 .
296 .Sh DIAGNOSTICS
297 .Bl -item
298 .It
299 Too many levels of nesting.
300 .It
301 Inappropriate
302 .Ic #elif ,
303 .Ic #else
304 or
305 .Ic #endif .
306 .It
307 Obfuscated preprocessor control line.
308 .It
309 Premature
310 .Dv EOF
311 (with the line number of the most recent unterminated
312 .Ic #if ) .
313 .It
314 .Dv EOF
315 in comment.
316 .El
317 .Pp
318 The
319 .Nm
320 utility exits 0 if the output is an exact copy of the input,
321 1 if not, and 2 if in trouble.
322 .Sh SEE ALSO
323 .Xr cpp 1 ,
324 .Xr diff 1
325 .Sh HISTORY
326 The
327 .Nm
328 command appeared in
329 .Bx 4.3 .
330 .Tn ANSI\~C
331 support was added in
332 .Fx 4.7 .
333 .Sh BUGS
334 Expression evaluation is very limited.
335 .Pp
336 Preprocessor control lines split across more than one physical line
337 (because of comments or backslash-newline)
338 cannot be handled in every situation.
339 .Pp
340 Trigraphs are not recognized.
341 .Pp
342 There is no support for symbols with different definitions at
343 different points in the source file.
344 .Pp
345 The text-mode and ignore functionality does not correspond to modern
346 .Xr cpp 1
347 behaviour.