1PMCPP(1)                    General Commands Manual                   PMCPP(1)
2
3
4

NAME

6       pmcpp - simple preprocessor for the Performance Co-Pilot
7

SYNOPSIS

9       pmcpp  [-Prs?]   [-D  name[=value]  ...]  [-I dir ...]  [[infile] [out‐
10       file]]
11

DESCRIPTION

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
22       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
26       All  C-style comments of the form /* ... */ are stripped from the input
27       stream.
28
29       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
33       pmcpp accepts the  following  directives  in  the  input  stream  (like
34       cpp(1)):
35
36#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
47#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
57#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
69#undef name
70          Removes the macro definition, if any, for name.
71
72#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
82#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
86       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
92       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
97                 # lineno "filename"
98
99       to indicate the following line of output  corresponds  to  line  number
100       lineno of the input file filename.
101

OPTIONS

103       The available command line options are:
104
105       -D name[=value], --define=name[=value]
106            Defines a macro with an optional value, as described earlier.
107
108       -I dir, --include=dir
109            An additional directory to search for include files.
110
111       -P   Suppresses  the  generation  of  the  linemarker  lines, described
112            above.
113
114       -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
122       -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
131       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.
140cpp(1) command line options like -o, -W, -U, and -x.
141
142       -?, --help
143          Display usage message and exit.
144

EXAMPLES

146       ┌─────────────────────────────────────────────┐
147       │Command: pmcpp                               
148       ├───────────────────────┬─────────────────────┤
149Input                  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
162       ┌──────────────────────────────────────────────────────────────────────┐
163       │Command: pmcpp -rs                                                    
164       ├──────────────────────────────────┬───────────────────────────────────┤
165Input                             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       ├──────────────────────────────────┬───────────────────────────────────┤
187Input                             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       └──────────────────────────────────┴───────────────────────────────────┘

PCP ENVIRONMENT

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
213       For environment variables affecting PCP tools, see pmGetOptions(3).
214

SEE ALSO

216       cpp(1),   pmLoadASCIINameSpace(3),   pmLoadNameSpace(3),   pcp.conf(5),
217       pcp.env(5) and PMNS(5).
218
219
220
221Performance Co-Pilot                                                  PMCPP(1)
Impressum