Annotation of src/usr.bin/unifdef/unifdef.1, Revision 1.9
1.9 ! deraadt 1: .\" $OpenBSD: unifdef.1,v 1.8 2000/03/11 21:40:06 aaron 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.9 ! deraadt 44: .Nm unifdef , unifdefall
! 45: .Nd remove preprocessor conditionals from code
1.1 deraadt 46: .Sh SYNOPSIS
1.9 ! deraadt 47: .Nm
! 48: .Op Fl cklst
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
1.9 ! deraadt 60: .Nm unifdefall
! 61: .Op Fl I Ns Ar path
! 62: .Ar ...
! 63: .Ar file
1.1 deraadt 64: .Sh DESCRIPTION
1.9 ! deraadt 65: The
1.8 aaron 66: .Nm
1.9 ! deraadt 67: utility selectively processes conditional
! 68: .Xr cpp 1
! 69: directives.
! 70: It removes from a file
! 71: both the directives
! 72: and any additional text that they specify should be removed,
! 73: while otherwise leaving the file alone.
! 74: .Pp
! 75: The
1.8 aaron 76: .Nm
1.9 ! deraadt 77: utility acts on
! 78: .Ic #if , #ifdef , #ifndef , #elif , #else ,
! 79: and
! 80: .Ic #endif
! 81: lines,
! 82: and it understands only the commonly-used subset
! 83: of the expression syntax for
! 84: .Ic #if
! 85: and
! 86: .Ic #elif
! 87: lines.
! 88: It handles
! 89: integer values of symbols defined on the command line,
! 90: the
! 91: .Fn defined
! 92: operator applied to symbols defined or undefined on the command line,
! 93: the operators
! 94: .Ic \&! , < , > , <= , >= , == , != , && , || ,
! 95: and parenthesized expressions.
! 96: Anything that it does not understand is passed through unharmed.
! 97: It only processes
! 98: .Ic #ifdef
! 99: and
! 100: .Ic #ifndef
! 101: directives if the symbol is specified on the command line,
! 102: otherwise they are also passed through unchanged.
! 103: By default, it ignores
! 104: .Ic #if
! 105: and
! 106: .Ic #elif
! 107: lines with constant expressions,
! 108: or they may be processed by specifying the
! 109: .Fl k
! 110: flag on the command line.
! 111: .Pp
! 112: The
! 113: .Nm
! 114: utility also understands just enough about C
! 115: to know when one of the directives is inactive
1.1 deraadt 116: because it is inside
117: a comment,
118: or a single or double quote.
119: Parsing for quotes is very simplistic:
120: when it finds an open quote,
121: it ignores everything (except escaped quotes)
122: until it finds a close quote, and
123: it will not complain if it gets
124: to the end of a line and finds no backslash for continuation.
125: .Pp
1.9 ! deraadt 126: A script called
! 127: .Nm unifdefall
! 128: can be used to remove all conditional
! 129: .Xr cpp 1
! 130: directives from a file.
! 131: It uses
! 132: .Nm Fl s
! 133: and
! 134: .Nm cpp Fl dM
! 135: to get lists of all the controlling symbols
! 136: and their definitions (or lack thereof),
! 137: then invokes
! 138: .Nm
! 139: with appropriate arguments to process the file.
! 140: .Pp
! 141: Available options:
! 142: .Bl -tag -width indent -compact
! 143: .It Fl D Ns Ar sym
! 144: .Ns Op = Ns Ar val
! 145: Specify that a symbol is defined,
! 146: and optionally specify what value to give it
! 147: for the purpose of handling
! 148: .Ic #if
! 149: and
! 150: .Ic #elif
! 151: directives.
! 152: .Pp
! 153: .It Fl U Ns Ar sym
! 154: Specify that a symbol is undefined.
1.1 deraadt 155: If the same symbol appears in more than one argument,
156: the last occurrence dominates.
1.9 ! deraadt 157: .Pp
1.1 deraadt 158: .It Fl c
159: If the
160: .Fl c
161: flag is specified,
162: then the operation of
1.8 aaron 163: .Nm
1.1 deraadt 164: is complemented,
1.8 aaron 165: i.e., the lines that would have been removed or blanked
1.1 deraadt 166: are retained and vice versa.
1.9 ! deraadt 167: .Pp
! 168: .It Fl k
! 169: Process
! 170: .Ic #if
! 171: and
! 172: .Ic #elif
! 173: lines with constant expressions.
! 174: By default, sections controlled by such lines are passed through unchanged
! 175: because they typically start
! 176: .Li #if 0
! 177: and are used as a kind of comment to sketch out future or past development.
! 178: It would be rude to strip them out, just as it would be for normal comments.
! 179: .Pp
1.1 deraadt 180: .It Fl l
181: Replace removed lines with blank lines
182: instead of deleting them.
1.9 ! deraadt 183: .Pp
! 184: .It Fl s
! 185: Instead of processing the input file as usual,
! 186: this option causes
! 187: .Nm
! 188: to produce a list of symbols that appear in expressions
! 189: that
! 190: .Nm
! 191: understands.
! 192: It is useful in conjunction with the
! 193: .Fl dM
! 194: option of
! 195: .Xr cpp 1
! 196: for creating
! 197: .Nm
! 198: command lines.
! 199: .Pp
1.1 deraadt 200: .It Fl t
201: Disables parsing for C comments and quotes, which is useful
202: for plain text.
1.9 ! deraadt 203: .Pp
! 204: .It Fl iD Ns Ar sym
! 205: .Ns Op = Ns Ar val
! 206: .It Fl iU Ns Ar sym
! 207: Ignore
! 208: .Ic #ifdef Ns s .
! 209: If your C code uses
! 210: .Ic #ifdef Ns s
! 211: to delimit non-C lines,
1.1 deraadt 212: such as comments
213: or code which is under construction,
214: then you must tell
1.8 aaron 215: .Nm
1.9 ! deraadt 216: which symbols are used for that purpose so that it will not try to parse
1.1 deraadt 217: for quotes and comments
1.9 ! deraadt 218: inside those
! 219: .Ic #ifdef Ns s .
! 220: One specifies ignored symbols with
1.1 deraadt 221: .Fl iD Ns Ar sym
1.9 ! deraadt 222: .Ns Oo = Ns Ar val Oc
1.1 deraadt 223: and
224: .Fl iU Ns Ar sym
225: similar to
226: .Fl D Ns Ar sym
1.9 ! deraadt 227: .Ns Op = Ns Ar val
1.1 deraadt 228: and
229: .Fl U Ns Ar sym
230: above.
1.9 ! deraadt 231: .Pp
! 232: .It Fl I Ns Ar path
! 233: Specifies to
! 234: .Nm unifdefall
! 235: an additional place to look for
! 236: .Ic #include
! 237: files.
! 238: This option is ignored by
! 239: .Nm
! 240: for compatibility with
! 241: .Xr cpp 1
! 242: and to simplify the implementation of
! 243: .Nm unifdefall .
1.1 deraadt 244: .El
245: .Pp
1.9 ! deraadt 246: The
1.8 aaron 247: .Nm
1.9 ! deraadt 248: utility copies its output to
1.1 deraadt 249: .Em stdout
250: and will take its input from
251: .Em stdin
252: if no
253: .Ar file
254: argument is given.
255: .Pp
1.9 ! deraadt 256: The
1.8 aaron 257: .Nm
1.9 ! deraadt 258: utility works nicely with the
1.1 deraadt 259: .Fl D Ns Ar sym
1.9 ! deraadt 260: option of
! 261: .Xr diff 1 .
! 262: .Sh SEE ALSO
! 263: .Xr cpp 1 ,
1.1 deraadt 264: .Xr diff 1
265: .Sh DIAGNOSTICS
1.9 ! deraadt 266: .Bl -item
! 267: .It
! 268: Inappropriate elif, else or endif.
! 269: .It
1.1 deraadt 270: Premature
271: .Tn EOF
1.9 ! deraadt 272: with line numbers of the unterminated
! 273: .Ic #ifdef Ns s .
! 274: .El
! 275: .Pp
! 276: The
! 277: .Nm
! 278: utility exits 0 if the output is an exact copy of the input,
! 279: 1 if not, and 2 if in trouble.
! 280: .Sh BUGS
! 281: Expression evaluation is very limited.
1.1 deraadt 282: .Pp
1.9 ! deraadt 283: Does not work correctly if input contains nul characters.
1.1 deraadt 284: .Sh HISTORY
285: The
286: .Nm
287: command appeared in
288: .Bx 4.3 .