source: mainline/uspace/app/pcc/cc/cpp/cpp.1@ 48fa501

.\"     $Id: cpp.1,v 1.11 2010/04/05 13:13:57 reed Exp $
.\"     $NetBSD$
.\"     $OpenBSD$
.\"
.\" 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 September 17, 2007
.Dt CPP 1
.Os
.Sh NAME
.Nm cpp
.Nd C preprocessor
.Sh SYNOPSIS
.Nm
.\" TODO also document -Dvar and below without spaces?
.Op Fl CdMtVv
.Op Fl D Ar macro[=value]
.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 used to include header files,
expand macro definitions,
and perform conditional compilation.
.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.
It writes by default to standard output.
.Pp
.\" TODO: document MAXARG  250 args to a macro, limited by char value
.\" TODO: Include order:
.\" For "..." files, first search "current" dir, then as <...> files.
.\" For <...> files, first search -I directories, then system directories.
.\"
The options are as follows:
.Bl -tag -width Ds
.It Fl ?
Show command line usage for
.Nm .
.It Fl C
Do not discard comments.
.It Fl D Ar macro[=value]
Fake a definition at the beginning by using
.Do #define
.Ar macro=value Dc .
If
.Ar value
is not set on command-line, then define it as 1.
.\" TODO: show example
.It Fl dM
Print list of
.Dq #define
statements to standard output for all defined macros other than
builtin macros (see below).
The normal results of preprocessing are not output.
.\" TODO this doesn't show predefined macros
.\" other -d options are ignored
.It Fl I Ar path
Add
.Ar path
to the list of directories containing needed header files.
This may be used to override system include directories
(see
.Fl S
option).
.Fl I
may be specified multiple times.
.It Fl i Ar file
Include a file at the beginning by using
.Do #include
.Ar file Dc .
.\" Note: I did not use the .In macro above
.It Fl M
Generate dependencies for
.Xr make 1 .
.\" TODO: explain and show example?
.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 containing needed header files.
The
.Fl S
option may be specified multiple times.
Note:
.Nm
does not have a default include directory defined.
.\" TODO: explain difference between -I and -S
.\" The directories listed by -I are searched first?
.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 at the beginning by using
.Do #undef
.Ar macro Dc .
.It Fl V
Verbose debugging output.
.Fl V
can be repeated for further details.
.\" -V only available if cpp source built with CPP_DEBUG, which is the default.
.It Fl v
Display version.
.El
.Ss Builtin Macros
A few macros are interpreted inside the
.Nm cpp
program:
.Bl -diag
.It __DATE__
Expands to the date in abbreviated month, day, and year format from
.Xr ctime 3
in quotes.
.\" TODO: is that ctime(3) format output change according to locale?
.It __FILE__
Expands to the name of the current input file in quotes.
When read from standard input, it expands to
.Qq Aq stdin .
.It __LINE__
Expands to the line number of the current line containing the macro.
.It __STDC__
Expands to the constant 1.
This means the compiler conforms to
.St -isoC
.Po also known as
.Do C90 Dc Pc .
.It __STDC_VERSION__
Expands to
.Dq 199901L
which indicates that
.Nm
supports
.St -isoC-99
.Po commonly referred to as
.Do C99 Dc Pc .
.It __TIME__
Expands to the time in hour, minutes, and seconds from
.Xr ctime 3
in quotes.
.El
.Pp
Also see the
.Fl t
option.
.Sh EXIT STATUS
The
.Nm
utility exits with one of the following values:
.Bl -tag -width Ds
.It 0
Successfully finished.
.It 1
An error occurred.
.El
.Sh SEE ALSO
.Xr as 1 ,
.Xr ccom 1 ,
.Xr pcc 1
.\"
.Sh HISTORY
The
.Nm
command comes from the original Portable C Compiler by 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 Anders Magnusson.
.Pp
This product includes software developed or owned by Caldera
International, Inc.