===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/unifdef/unifdef.1,v
retrieving revision 1.18
retrieving revision 1.19
diff -c -r1.18 -r1.19
*** src/usr.bin/unifdef/unifdef.1	2013/01/17 21:29:15	1.18
--- src/usr.bin/unifdef/unifdef.1	2014/04/18 21:11:34	1.19
***************
*** 1,9 ****
- .\"	$OpenBSD: unifdef.1,v 1.18 2013/01/17 21:29:15 jmc Exp $
  .\" Copyright (c) 1985, 1991, 1993
  .\"	The Regents of the University of California.  All rights reserved.
  .\"
  .\" This code is derived from software contributed to Berkeley by
! .\" Dave Yost. Support for #if and #elif was added by Tony Finch.
  .\"
  .\" Redistribution and use in source and binary forms, with or without
  .\" modification, are permitted provided that the following conditions
--- 1,9 ----
  .\" Copyright (c) 1985, 1991, 1993
  .\"	The Regents of the University of California.  All rights reserved.
+ .\" Copyright (c) 2002 - 2013 Tony Finch <dot@dotat.at>.  All rights reserved.
  .\"
  .\" This code is derived from software contributed to Berkeley by
! .\" Dave Yost. It was rewritten to support ANSI C by Tony Finch.
  .\"
  .\" Redistribution and use in source and binary forms, with or without
  .\" modification, are permitted provided that the following conditions
***************
*** 29,39 ****
  .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  .\" SUCH DAMAGE.
  .\"
! .\"     @(#)unifdef.1	8.2 (Berkeley) 4/1/94
! .\"	$dotat: things/unifdef.1,v 1.26 2002/09/24 19:44:12 fanf2 Exp $
! .\" $FreeBSD: src/usr.bin/unifdef/unifdef.1,v 1.15 2002/09/24 19:48:39 fanf Exp $
! .\"
! .Dd $Mdocdate: January 17 2013 $
  .Dt UNIFDEF 1
  .Os
  .Sh NAME
--- 29,35 ----
  .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  .\" SUCH DAMAGE.
  .\"
! .Dd $Mdocdate: April 18 2014 $
  .Dt UNIFDEF 1
  .Os
  .Sh NAME
***************
*** 41,61 ****
  .Nd remove preprocessor conditionals from code
  .Sh SYNOPSIS
  .Nm
! .Op Fl ceklst
! .Sm off
! .Oo
! .Fl D Ar sym
! .Op = Ar val
! .Oc
! .Op Fl I Ar path
! .Oo
! .Fl iD Ar sym
! .Op = Ar val
! .Oc
! .Op Fl iU Ar sym
! .Op Fl U Ar sym
! .Sm on
! .Op Ar file
  .Sh DESCRIPTION
  The
  .Nm
--- 37,52 ----
  .Nd remove preprocessor conditionals from code
  .Sh SYNOPSIS
  .Nm
! .Op Fl bBcdehKkmnsStV
! .Op Fl I Ns Ar path
! .Op Fl [i]D Ns Ar sym Ns Op = Ns Ar val
! .Op Fl [i]U Ns Ar sym
! .Ar ...
! .Op Fl f Ar defile
! .Op Fl x Bro Ar 012 Brc
! .Op Fl M Ar backext
! .Op Fl o Ar outfile
! .Op Ar infile ...
  .Sh DESCRIPTION
  The
  .Nm
***************
*** 75,199 ****
  and
  .Ic #endif
  lines,
! and it understands only the commonly-used subset
  of the expression syntax for
  .Ic #if
  and
  .Ic #elif
! lines.
! It handles
! integer values of symbols defined on the command line,
  the
  .Fn defined
! operator applied to symbols defined or undefined on the command line,
  the operators
! .Ic \&! , < , > , <= ,
! .Ic >= , == , != , && ,
! .Ic || ,
  and parenthesized expressions.
! Anything that it does not understand is passed through unharmed.
! It only processes
! .Ic #ifdef
! and
! .Ic #ifndef
! directives if the symbol is specified on the command line,
! otherwise they are also passed through unchanged.
! By default, it ignores
  .Ic #if
  and
  .Ic #elif
! lines with constant expressions,
! or they may be processed by specifying the
! .Fl k
! flag on the command line.
  .Pp
  The
  .Nm
! utility also understands just enough about C
  to know when one of the directives is inactive
  because it is inside
  a comment,
  or affected by a backslash-continued line.
  It spots unusually-formatted preprocessor directives
! and knows when the layout is too odd to handle.
  .Pp
! The options are as follows:
  .Pp
! .Bl -tag -width indent -compact
  .It Fl c
! If the
! .Fl c
! flag is specified,
! then the operation of
! .Nm
! is complemented,
! i.e., the lines that would have been removed or blanked
  are retained and vice versa.
  .Pp
! .Sm off
! .It Xo
! .Fl D Ar sym
! .Op = Ar val
! .Xc
! .Sm on
! Specify that a symbol is defined,
! and optionally specify what value to give it
! for the purpose of handling
! .Ic #if
! and
! .Ic #elif
! directives.
  .Pp
  .It Fl e
- Because
- .Nm
- processes its input one line at a time,
- it cannot remove preprocessor directives that span more than one line.
- The most common example of this is a directive with a multi-line
- comment hanging off its right hand end.
  By default,
- if
  .Nm
! has to process such a directive,
! it will complain that the line is too obfuscated.
  The
  .Fl e
! option changes the behavior so that,
! where possible,
! such lines are left unprocessed instead of reporting an error.
  .Pp
! .Sm off
! .It Xo
! .Fl iD Ar sym
! .Op = Ar val
! .Xc
! .Sm on
! .It Fl iU Ns Ar sym
! Ignore
! .Ic #ifdef Ns s .
! If your C code uses
! .Ic #ifdef Ns s
! to delimit non-C lines,
! such as comments
! or code which is under construction,
! then you must tell
! .Nm
! which symbols are used for that purpose so that it will not try to parse
! comments and line continuations
! inside those
! .Ic #ifdef Ns s .
! One specifies ignored symbols with
! .Sm off
! .Fl iD Ar sym Op = Ar val
! .Sm on
  and
! .Fl iU Ns Ar sym ,
! similar to
! .Sm off
! .Fl D Ar sym Op = Ar val
! .Sm on
! and
! .Fl U Ns Ar sym .
  .Pp
  .It Fl k
  Process
--- 66,281 ----
  and
  .Ic #endif
  lines,
! using macros specified in
! .Fl D
! and
! .Fl U
! command line options or in
! .Fl f
! definitions files.
! A directive is processed
! if the macro specifications are sufficient to provide
! a definite value for its control expression.
! If the result is false,
! the directive and the following lines under its control are removed.
! If the result is true,
! only the directive is removed.
! An
! .Ic #ifdef
! or
! .Ic #ifndef
! directive is passed through unchanged
! if its controlling macro is not specified.
! Any
! .Ic #if
! or
! .Ic #elif
! control expression that has an unknown value or that
! .Nm
! cannot parse is passed through unchanged.
! By default,
! .Nm
! ignores
! .Ic #if
! and
! .Ic #elif
! lines with constant expressions;
! it can be told to process them by specifying the
! .Fl k
! flag on the command line.
! .Pp
! It understands a commonly-used subset
  of the expression syntax for
  .Ic #if
  and
  .Ic #elif
! lines:
! integer constants,
! integer values of macros defined on the command line,
  the
  .Fn defined
! operator,
  the operators
! .Ic \&! , < , > ,
! .Ic <= , >= , == , != ,
! .Ic && , || ,
  and parenthesized expressions.
! A kind of
! .Dq "short circuit"
! evaluation is used for the
! .Ic &&
! operator:
! if either operand is definitely false then the result is false,
! even if the value of the other operand is unknown.
! Similarly,
! if either operand of
! .Ic ||
! is definitely true then the result is true.
! .Pp
! When evaluating an expression,
! .Nm
! does not expand macros first.
! The value of a macro must be a simple number,
! not an expression.
! A limited form of indirection is allowed,
! where one macro's value is the name of another.
! .Pp
! In most cases,
! .Nm
! does not distinguish between object-like macros
! (without arguments) and function-like macros (with arguments).
! A function-like macro invocation can appear in
  .Ic #if
  and
  .Ic #elif
! control expressions.
! If the macro is not explicitly defined,
! or is defined with the
! .Fl D
! flag on the command-line,
! or with
! .Ic #define
! in a
! .Fl f
! definitions file,
! its arguments are ignored.
! If a macro is explicitly undefined on the command line with the
! .Fl U
! flag,
! or with
! .Ic #undef
! in a
! .Fl f
! definitions file,
! it may not have any arguments since this leads to a syntax error.
  .Pp
  The
  .Nm
! utility understands just enough about C
  to know when one of the directives is inactive
  because it is inside
  a comment,
  or affected by a backslash-continued line.
  It spots unusually-formatted preprocessor directives
! and knows when the layout is too odd for it to handle.
! .Sh OPTIONS
! .Bl -tag -width indent -compact
! .It Fl D Ns Ar sym Ns = Ns Ar val
! Specify that a macro is defined to a given value.
  .Pp
! .It Fl D Ns Ar sym
! Specify that a macro is defined to the value 1.
  .Pp
! .It Fl U Ns Ar sym
! Specify that a macro is undefined.
! .Pp
! If the same macro appears in more than one argument,
! the last occurrence dominates.
! .Pp
! .It Fl iD Ns Ar sym Ns Op = Ns Ar val
! .It Fl iU Ns Ar sym
! C strings, comments,
! and line continuations
! are ignored within
! .Ic #ifdef
! and
! .Ic #ifndef
! blocks
! controlled by macros
! specified with these options.
! .Pp
! .It Fl f Ar defile
! The file
! .Ar defile
! contains
! .Ic #define
! and
! .Ic #undef
! preprocessor directives,
! which have the same effect as the corresponding
! .Fl D
! and
! .Fl U
! command-line arguments.
! You can have multiple
! .Fl f
! arguments and mix them with
! .Fl D
! and
! .Fl U
! arguments;
! later options override earlier ones.
! .Pp
! Each directive must be on a single line.
! Object-like macro definitions (without arguments)
! are set to the given value.
! Function-like macro definitions (with arguments)
! are treated as if they are set to 1.
! .Pp
! .It Fl b
! Replace removed lines with blank lines
! instead of deleting them.
! Mutually exclusive with the
! .Fl B
! option.
! .Pp
! .It Fl B
! Compress blank lines around a deleted section.
! Mutually exclusive with the
! .Fl b
! option.
! .Pp
  .It Fl c
! Complement,
! i.e., lines that would have been removed or blanked
  are retained and vice versa.
  .Pp
! .It Fl d
! Turn on printing of debugging messages.
  .Pp
  .It Fl e
  By default,
  .Nm
! will report an error if it needs to remove
! a preprocessor directive that spans more than one line,
! for example, if it has a multi-line
! comment hanging off its right hand end.
  The
  .Fl e
! flag makes it ignore the line instead.
  .Pp
! .It Fl h
! Print help.
! .Pp
! .It Fl K
! Always treat the result of
! .Ic &&
  and
! .Ic ||
! operators as unknown if either operand is unknown,
! instead of short-circuiting when unknown operands can't affect the result.
! This option is for compatibility with older versions of
! .Nm .
  .Pp
  .It Fl k
  Process
***************
*** 203,253 ****
  lines with constant expressions.
  By default, sections controlled by such lines are passed through unchanged
  because they typically start
! .Li #if 0
  and are used as a kind of comment to sketch out future or past development.
  It would be rude to strip them out, just as it would be for normal comments.
  .Pp
! .It Fl l
! Replace removed lines with blank lines
! instead of deleting them.
  .Pp
  .It Fl s
! Instead of processing the input file as usual,
  this option causes
  .Nm
! to produce a list of symbols that appear in expressions
! that
! .Nm
! understands.
! It is useful in conjunction with the
! .Fl dM
! option of
! .Xr cpp 1
! for creating
! .Nm
! command lines.
  .Pp
  .It Fl t
! Disables parsing for C comments
  and line continuations,
  which is useful
  for plain text.
  .Pp
! .It Fl U Ns Ar sym
! Specify that a symbol is undefined.
! If the same symbol appears in more than one argument,
! the last occurrence dominates.
  .El
  .Pp
  The
  .Nm
! utility copies its output to
! .Em stdout
! and will take its input from
  .Em stdin
! if no
  .Ar file
! argument is given.
  .Pp
  The
  .Nm
--- 285,364 ----
  lines with constant expressions.
  By default, sections controlled by such lines are passed through unchanged
  because they typically start
! .Dq Li "#if 0"
  and are used as a kind of comment to sketch out future or past development.
  It would be rude to strip them out, just as it would be for normal comments.
  .Pp
! .It Fl m
! Modify one or more input files in place.
  .Pp
+ .It Fl M Ar backext
+ Modify input files in place, and keep backups of the original files by
+ appending the
+ .Ar backext
+ to the input filenames.
+ .Pp
+ .It Fl n
+ Add
+ .Li #line
+ directives to the output following any deleted lines,
+ so that errors produced when compiling the output file correspond to
+ line numbers in the input file.
+ .Pp
+ .It Fl o Ar outfile
+ Write output to the file
+ .Ar outfile
+ instead of the standard output when processing a single file.
+ .Pp
  .It Fl s
! Instead of processing an input file as usual,
  this option causes
  .Nm
! to produce a list of macros that are used in
! preprocessor directive controlling expressions.
  .Pp
+ .It Fl S
+ Like the
+ .Fl s
+ option, but the nesting depth of each macro is also printed.
+ This is useful for working out the number of possible combinations
+ of interdependent defined/undefined macros.
+ .Pp
  .It Fl t
! Disables parsing for C strings, comments,
  and line continuations,
  which is useful
  for plain text.
+ This is a blanket version of the
+ .Fl iD
+ and
+ .Fl iU
+ flags.
  .Pp
! .It Fl V
! Print version details.
! .Pp
! .It Fl x Bro Ar 012 Brc
! Set exit status mode to zero, one, or two.
! See the
! .Sx EXIT STATUS
! section below for details.
  .El
  .Pp
  The
  .Nm
! utility takes its input from
  .Em stdin
! if there are no
  .Ar file
! arguments.
! You must use the
! .Fl m
! or
! .Fl M
! options if there are multiple input files.
! You can specify inut from stdin or output to stdout with
! .Ql - .
  .Pp
  The
  .Nm
***************
*** 256,265 ****
  option of
  .Xr diff 1 .
  .Sh EXIT STATUS
! The
  .Nm
! utility exits 0 if the output is an exact copy of the input,
! 1 if not, and 2 if in trouble.
  .Sh DIAGNOSTICS
  .Bl -item
  .It
--- 367,401 ----
  option of
  .Xr diff 1 .
  .Sh EXIT STATUS
! In normal usage the
  .Nm
! utility's exit status depends on the mode set using the
! .Fl x
! option.
! .Pp
! If the exit mode is zero (the default) then
! .Nm
! exits with status 0 if the output is an exact copy of the input,
! or with status 1 if the output differs.
! .Pp
! If the exit mode is one,
! .Nm
! exits with status 1 if the output is unmodified
! or 0 if it differs.
! .Pp
! If the exit mode is two,
! .Nm
! exits with status zero in both cases.
! .Pp
! In all exit modes,
! .Nm
! exits with status 2 if there is an error.
! .Pp
! The exit status is 0 if the
! .Fl h
! or
! .Fl V
! command line options are given.
  .Sh DIAGNOSTICS
  .Bl -item
  .It
***************
*** 284,306 ****
  .Sh SEE ALSO
  .Xr cpp 1 ,
  .Xr diff 1
  .Sh HISTORY
  The
  .Nm
  command appeared in
! .Bx 4.3 .
  .Sh BUGS
  Expression evaluation is very limited.
  .Pp
! Preprocessor control lines split across more than one physical line
  (because of comments or backslash-newline)
  cannot be handled in every situation.
  .Pp
  Trigraphs are not recognized.
  .Pp
! There is no support for symbols with different definitions at
  different points in the source file.
  .Pp
! The text-mode and ignore functionality doesn't correspond to modern
  .Xr cpp 1
  behaviour.
--- 420,455 ----
  .Sh SEE ALSO
  .Xr cpp 1 ,
  .Xr diff 1
+ .Pp
+ The unifdef home page is
+ .Pa http://dotat.at/prog/unifdef
  .Sh HISTORY
  The
  .Nm
  command appeared in
! .Bx 2.9 .
! .Tn ANSI\~C
! support was added in
! .Fx 4.7 .
! .Sh AUTHORS
! The original implementation was written by
! .An Dave Yost Aq Dave@Yost.com .
! .An Tony Finch Aq dot@dotat.at
! rewrote it to support
! .Tn ANSI\~C .
  .Sh BUGS
  Expression evaluation is very limited.
  .Pp
! Handling one line at a time means
! preprocessor directives split across more than one physical line
  (because of comments or backslash-newline)
  cannot be handled in every situation.
  .Pp
  Trigraphs are not recognized.
  .Pp
! There is no support for macros with different definitions at
  different points in the source file.
  .Pp
! The text-mode and ignore functionality does not correspond to modern
  .Xr cpp 1
  behaviour.