'\"macro stdmacro
.\"
.\" Copyright (c) 2011 Ken McDonell.  All Rights Reserved.
.\" 
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\" 
.\"
.TH PMCPP 1 "" "Performance Co-Pilot"
.SH NAME
\f3pmcpp\f1 \- simple preprocessor for the Performance Co-Pilot
.\" literals use .B or \f3
.\" arguments use .I or \f2
.SH SYNOPSIS
.B pmcpp
[\f3\-D\f1 \f2name\f1[=\f2value\f1] ...]
[\f2infile\f1]
.SH DESCRIPTION
.B pmcpp
provides a very simple pre-processor for manipulating Performance
Metric Name Space (PMNS) files for the
Performance Co-Pilot (PCP).  It is most commonly used internally
to process the PMNS file(s) after
.BR pmLoadNameSpace (3)
or
.BR pmLoadASCIINameSpace (3)
is called.
.PP
Input lines are read from
.I infile
(or standard input if
.I infile
is not specified), processed and written to standard output.
.PP
All C-style comments of the form /* ... */ are stripped from the
input stream.
.PP
There are no predefined macros for
.B pmcpp
although macros may be defined on the command line using the
.B \-D
option, where
.I name
and
.I value
must follow the same rules as described below for the
.B #define
directive.
.PP
.B pmcpp
accepts the following directives in the input stream (like
.BR cpp (1)):
.IP * 3n
\fB#include "\fIfilename\fB"\fR
.br
or
.br
\fB#include <\fIfilename\fB>\fR
.br
In either case the directory search path for
.I filename
tries
.I filename
first, then the directory for the command line
.I infile
(if any),
followed by the
.B $PCP_VAR_DIR/pmns
directory.
.B #include
directives may be nested, up to a maximum depth of 5.
.IP * 3n
\fB#define \fIname value\fR
.br
Defines a value for the macro
.I name
which must be a valid C-style name, so leading alphabetic or ``_'' followed by
zero or more alphanumerics or ``_''.
.I value
is optional (and defaults to an empty value) but when present it may
.B not
contain white space and quoting or escaping is
.B not
supported.
.IP * 3n
\fB#undef \fIname\fR
.br
Removes the macro definition, if any, for
.IR name .
.IP * 3n
\fB#ifdef \fIname\fR
.br
\&...
.br
\fB#endif\fR
.br
or
.br
\fB#ifndef \fIname\fR
.br
\&...
.br
\fB#endif\fR
.br
The enclosing lines will be stripped or included, depending if the
macro
.I name
is defined or not.
.PP
Macro substitution is achieved by breaking the input stream into words
separated by white space or one of the characters ``.'' or ``:''
\- this matches the syntax of the PMNS, see
.BR pmns (5).
Each word is checked and if it matches a macro name, the word is
replaced by the macro value, otherwise the word is unchanged.
.PP
There is generally one output line for each input line, although the line
may be empty if the text has been stripped due to the handling of
comments or conditional directives.  When there is a change in the input
stream, an additional output line is generated of the form:
.PP
.ti +10n
# line "name"
.PP
to indicate the 
.I following
line of output corresponds to line number
.I line
of the input file
.IR name .
.PP
Important
.BR cpp (1)
features that are
.B not
supported by
.B pmcpp
include:
.IP * 3n
\fB#if \fIexpr\fR
.br
\&...
.br
\fB#endif\fR
.IP * 3n
Nested use of
.B #ifdef
or
.BR #ifndef .
.IP * 3n
.B #else
within an
.B #ifdef
or
.BR #ifndef .
.IP * 3n
Stripping C++ style comments, as in // comment
.IP * 3n
Error recovery - the first error encountered by
.B pmcpp
will be fatal.
.IP * 3n
.BR cpp (1)
command line options like
.B \-U ,
.B \-P
and
.BR \-I .
.SH "PCP ENVIRONMENT"
Environment variables with the prefix
.B PCP_
are used to parameterize the file and directory names
used by PCP.
On each installation, the file
.I /etc/pcp.conf
contains the local values for these variables.
The
.B $PCP_CONF
variable may be used to specify an alternative
configuration file,
as described in
.BR pcp.conf (5).
.SH SEE ALSO
.BR cpp (1),
.BR pmLoadASCIINameSpace (3),
.BR pmLoadNameSpace (3),
.BR pmns (5),
.BR pcp.conf (5)
and
.BR pcp.env (5).