.\"	$Id: cpp.1,v 1.17 2013/02/26 19:27:38 plunky Exp $
.\"
.\" Copyright (c) 2007 Jeremy C. Reed <reed@reedmedia.net>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR AND CONTRIBUTORS DISCLAIM
.\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL AUTHOR AND
.\" CONTRIBUTORS BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
.\" THIS SOFTWARE.
.\"
.Dd February 26, 2013
.Dt CPP 1
.Os
.Sh NAME
.Nm cpp
.Nd C preprocessor
.Sh SYNOPSIS
.Nm
.Op Fl ACEMPtVv
.Op Fl D Ar macro Ns Oo = Ns Ar value Oc
.Op Fl d Ar flags
.Op Fl I Ar path
.Op Fl i Ar file
.Op Fl S Ar path
.Op Fl U Ar macro
.Op Ar infile | -
.Op Ar outfile
.Sh DESCRIPTION
The
.Nm
utility is a macro preprocessor used by the
.Xr pcc 1
compiler.
It is mainly used to include header files,
expand macro definitions,
discard comments,
and perform conditional compilation.
.Nm
is written to comply with the
.St -isoC-99
specification.
.Pp
The
.Ar infile
input file is optional.
If not provided or the file name is
.Qq -
(dash),
.Nm
reads its initial file from standard input.
The
.Ar outfile
output file is also optional, with output written to standard
output if not provided.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl A
For assembler-with-cpp input: treat non-directive lines starting
with a # as comments.
.It Fl C
Do not discard comments.
.It Fl D Ar macro Ns Oo = Ns Ar value Oc
Create a macro definition before processing any input, as if a
.Lp
.Dl #define Ar macro Ar value
.Lp
directive had appeared in the source.
If
.Ar value
is not set on the command-line, then a value of 1 is used.
.It Fl d Ar flags
Modify output according to
.Ar flags ,
which can be a list of character flags.
The following flags are currently supported:
.Bl -tag -width ".Sy M"
.It Sy M
Do not process any input, but output a list of
.Dq #define
statements for all defined macros other than builtin macros
.Pq see below .
.El
.Lp
any unknown flags are ignored.
.It Fl E
Modify the exit code, if there were any warnings.
.It Fl I Ar path
Add
.Ar path
to the list of directories searched by the
.Dq #include
directive.
This may be used to override system include directories
.Pq see Fl S No option .
.Fl I
may be specified multiple times and is cumulative.
.It Fl i Ar file
Include a file before processing any input, as if a
.Lp
.Dl #include Qo Ar file Qc
.Lp
directive had appeared in the source.
.Fl i
may be specified multiple times to include several files.
.It Fl M
Instead of producing a processed C code file, output a list
of dependencies for
.Xr make 1 ,
detailing the files that need to be processed when compiling
the input.
.It Fl P
Inhibit generation of line markers.  This is sometimes useful when
running the preprocessor on something other than C code.
.It Fl S Ar path
Add
.Ar path
to the list of system directories searched by the
.Dq #include
directive.
The
.Fl S
option may be specified multiple times and is cumulative.
.It Fl t
Traditional cpp syntax.
Do not define the
.Dv __TIME__ ,
.Dv __DATE__ ,
.Dv __STDC__ ,
and
.Dv __STDC_VERSION__
macros.
.It Fl U Ar macro
Undefine a macro before processing any input, as if a
.Lp
.Dl #undef Ar macro
.Lp
directive had appeared in the source.
.It Fl V
Verbose debugging output.
.Fl V
can be repeated for greater detail.
.Po
This is only available if the
.Nm
program was built with
.Dv PCC_DEBUG
defined, which is the default
.Pc .
.It Fl v
Display version.
.El
.Pp
The
.Fl D ,
.Fl i
and
.Fl U
options are processed in the order that they appear on the command
line, before any input is read but after the command line options
have been scanned.
.Pp
Files referenced by the
.Dq #include
directive as
.Qq ... ,
are first looked for in the current directory, then as per
.Aq ...
files, which are first looked for in the list of
directories provided by any
.Fl I
options, then in the list of system directories provided by any
.Fl S
options.
Note that
.Nm
does not define any include directories by default; if no
.Fl I
or
.Fl S
options are given, then only the current directory will be
searched and no system files will be found.
.Ss Builtin Macros
A few macros are interpreted inside the
.Nm cpp
program:
.Bl -diag
.It __DATE__
Expands to a quoted string literal containing the date in the form
.Qq Mmm dd yyyy ,
where the names of the months are the same as those generated by the
.Xr asctime 3
function, and the first character of dd is a space character if
the value is less than 10.
.It __FILE__
Expands to a quoted string literal containing the presumed name of
the current source file.
When reading source from standard input, it expands to
.Qq Aq stdin .
.It __LINE__
Expands to an integer constant representing the presumed line number
of the source line containing the macro.
.It __STDC__
Expands to the integer constant
.Dq 1 ,
meaning that the compiler conforms to
.St -isoC .
.It __STDC_VERSION__
Expands to the integer constant
.Dq 199901L ,
indicating that
.Nm
conforms to
.St -isoC-99 .
.It __TIME__
Expands to a quoted string literal containing the time in the form
.Qq hh:mm:ss
as generated by the
.Xr asctime 3
function.
.El
.Pp
Also see the
.Fl t
option.
.Sh EXIT STATUS
The
.Nm
utility exits with one of the following values:
.Lp
.Bl -tag -width Ds -offset indent -compact
.It 0
Successfully finished.
.It 1
An error occurred.
.It 2
The
.Fl E
option was given, and warnings were issued.
.El
.Sh SEE ALSO
.Xr as 1 ,
.Xr ccom 1 ,
.Xr make 1 ,
.Xr pcc 1 ,
.Xr asctime 3
.Sh HISTORY
The
.Nm
command comes from the original Portable C Compiler by
.An "S. C. Johnson" ,
written in the late 70's.
The code originates from the V6 preprocessor with some additions
from V7 cpp and ansi/c99 support.
.Pp
A lot of the PCC code was rewritten by
.An "Anders Magnusson" .
.Pp
This product includes software developed or owned by Caldera
International, Inc.