1PMCPP(1) General Commands Manual PMCPP(1)
2
6 pmcpp - simple preprocessor for the Performance Co-Pilot
7
9 pmcpp [-Prs?] [-D name[=value] ...] [-I dir ...] [[infile] [out‐
10 file]]
11
13 pmcpp provides a very simple pre-processor originally designed for ma‐
14 nipulating Performance Metric Name Space (PMNS) files for the Perfor‐
15 mance Co-Pilot (PCP), but later generalized to provide conditional
16 blocks, include file processing, in-line shell command execution and
17 macro substitution for arbitrary files. It is most commonly used in‐
18 ternally to process the PMNS file(s) after pmLoadNameSpace(3) or pm‐
19 LoadASCIINameSpace(3) is called and to pre-process the configuration
20 files for pmlogger(1).
21 Input lines are read from infile (or standard input if infile is not
23 specified), processed and written to outfile (standard output if out‐
24 file is not specified).
25 All C-style comments of the form /* ... */ are stripped from the input
27 stream.
28 There are no predefined macros for pmcpp although macros may be defined
30 on the command line using the -D option, where name and value must fol‐
31 low the same rules as described below for the #define directive.
32 pmcpp accepts the following directives in the input stream (like
34 cpp(1)):
35 • #include "filename"
37 or
38 #include <filename>
39 In either case the directory search path for filename tries filename
40 first, then the directory for the command line infile (if any), fol‐
41 lowed by any directories named in -I command line arguments, and fi‐
42 nally the $PCP_VAR_DIR/pmns directory (the latter is for backwards
43 compatibility with earlier versions of pmcpp and the implied used
44 from pmLoadASCIINameSpace(3)). #include directives may be nested,
45 up to a maximum depth of 5.
46 • #shell "command"
48 or
49 #shell 'command'
50 The shell command will be executed and the standard output is in‐
51 serted into the stream of data to be processed by pmcpp. Function‐
52 ally this is similar to a #include directive, except input lines are
53 read from a command rather than a file. The #shell directive is
54 most useful for including or excluding #define or #undef directives
55 based on run-time logic in the command.
56 • #define name value
58 or
59 #define name "value"
60 or
61 #define name 'value'
62 Defines a value for the macro name which must be a valid C-style
63 name, so leading alphabetic or underscore followed by zero or more
64 alphanumerics or underscores. value is optional (and defaults to an
65 empty string). There is no character escape mechanism, but either
66 single quotes or double quotes may be used to define a value with
67 special characters or embedded horizontal white space (no newlines).
68 • #undef name
70 Removes the macro definition, if any, for name.
71 • #ifdef name
73 ...
74 #endif
75 or
76 #ifndef name
77 ...
78 #endif
79 The enclosing lines will be stripped or included, depending if the
80 macro name is defined or not.
81 • #else
83 Within a #ifdef or #ifndef block, #else may be used to delimit lines
84 to be included if the preceding ``if'' condition is false.
85 Macro substitution is achieved by breaking the input stream into words
87 separated by white space or characters that are not valid in a macro
88 name, i.e. not alphanumeric and not underscore. Each word is checked
89 and if it matches a macro name, the word is replaced by the macro
90 value, otherwise the word is unchanged.
91 There is generally one output line for each input line, although the
93 line may be empty if the text has been stripped due to the handling of
94 comments or conditional directives. When there is a change in the in‐
95 put stream, an additional output line is generated of the form:
96 # lineno "filename"
98 to indicate the following line of output corresponds to line number
100 lineno of the input file filename.
101
103 The available command line options are:
104 -D name[=value], --define=name[=value]
106 Defines a macro with an optional value, as described earlier.
107 -I dir, --include=dir
109 An additional directory to search for include files.
110 -P Suppresses the generation of the linemarker lines, described
112 above.
113 -s, --shell
115 Changes the expected input style from C-like to shell-like (where
116 # is a comment prefix). This forces the following changes in pm‐
117 cpp behaviour:
118 • The control prefix character changes from # to %, so %include for
119 example.
120 • No comment stripping is performed.
121 -r, --restrict
123 Provide finer control of macro expansion - this option restricts
124 macro substitution to words that match the patterns #name or #{name}
125 or if -s is specified, then %name or %{name}. In this mode, the
126 macro name alone in the input stream will never be expanded, however
127 in control lines (like #ifdef) the macro name should appear alone
128 with out the prefix character or the curly braces (refer to the EX‐
129 AMPLES below).
130 Important cpp(1) features that are not supported by pmcpp include:
132 • Macros with parameters - the pmcpp macros support only parameterless
133 string substitution.
134 • #if expr
135 ...
136 #endif
137 • Nested use of #ifdef or #ifndef.
138 • Stripping C++ style comments, as in // comment.
139 • Error recovery - the first error encountered by pmcpp will be fatal.
140 • cpp(1) command line options like -o, -W, -U, and -x.
141 -?, --help
143 Display usage message and exit.
144
146 ┌─────────────────────────────────────────────┐
147 │Command: pmcpp │
148 ├───────────────────────┬─────────────────────┤
149 │Input │ Output │
150 ├───────────────────────┼─────────────────────┤
151 │ │ # 1 "<stdin>" │
152 │#define MYDOMAIN 27 │ │
153 │ │ │
154 │root { │ root { │
155 │ foo MYDOMAIN:0:0 │ foo 27:0:0 │
156 │} │ } │
157 └───────────────────────┴─────────────────────┘
158 For the following examples, the file frequencies contains the lines:
159 %define dk_freq 1minute
160 %define cpu_freq '15 sec'
161 ┌──────────────────────────────────────────────────────────────────────┐
163 │Command: pmcpp -rs │
164 ├──────────────────────────────────┬───────────────────────────────────┤
165 │Input │ Output │
166 ├──────────────────────────────────┼───────────────────────────────────┤
167 │# get logging frequencies │ # get logging frequencies │
168 │# e.g. dk_freq macro │ # e.g. dk_freq macro │
169 │%include "frequencies" │ │
170 │ │ │
171 │log mandatory on %dk_freq { │ log mandatory on 1minute { │
172 │ disk.dev │ disk.dev │
173 │} │ } │
174 │ │ │
175 │# note no % for want_cpu here │ # note no % for want_cpu here │
176 │%ifdef want_cpu │ │
177 │%define cpu_pfx 'kernel.all.cpu.' │ │
178 │log mandatory on %cpu_freq { │ │
179 │ %{cpu_pfx}user │ │
180 │ %{cpu_pfx}sys │ │
181 │} │ │
182 │%endif │ │
183 └──────────────────────────────────┴───────────────────────────────────┘
184 ┌──────────────────────────────────────────────────────────────────────┐
185 │Command: pmcpp -rs -Dwant_cpu │
186 ├──────────────────────────────────┬───────────────────────────────────┤
187 │Input │ Output │
188 ├──────────────────────────────────┼───────────────────────────────────┤
189 │# get logging frequencies │ # get logging frequencies │
190 │# e.g. dk_freq macro │ # e.g. dk_freq macro │
191 │%include "frequencies" │ │
192 │ │ │
193 │log mandatory on %dk_freq { │ log mandatory on 1minute { │
194 │ disk.dev │ disk.dev │
195 │} │ } │
196 │ │ │
197 │# note no % for want_cpu here │ # note no % for want_cpu here │
198 │%ifdef want_cpu │ │
199 │%define cpu_pfx 'kernel.all.cpu.' │ │
200 │log mandatory on %cpu_freq { │ log mandatory on 15 sec { │
201 │ %{cpu_pfx}user │ kernel.all.cpu.user │
202 │ %{cpu_pfx}sys │ kernel.all.cpu.sys │
203 │} │ } │
204 │%endif │ │
205 └──────────────────────────────────┴───────────────────────────────────┘
207 Environment variables with the prefix PCP_ are used to parameterize the
208 file and directory names used by PCP. On each installation, the file
209 /etc/pcp.conf contains the local values for these variables. The
210 $PCP_CONF variable may be used to specify an alternative configuration
211 file, as described in pcp.conf(5).
212 For environment variables affecting PCP tools, see pmGetOptions(3).
214
216 cpp(1), pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pcp.conf(5),
217 pcp.env(5) and PMNS(5).
218Performance Co-Pilot PMCPP(1)