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]
10

DESCRIPTION

12       pmcpp  provides  a  very  simple  pre-processor originally designed for
13       manipulating Performance Metric Name Space (PMNS) files for the Perfor‐
14       mance  Co-Pilot  (PCP),  but  later  generalized to provide conditional
15       blocks, include file processing, in-line shell  command  execution  and
16       macro  substitution  for  arbitrary  files.   It  is most commonly used
17       internally to process the  PMNS  file(s)  after  pmLoadNameSpace(3)  or
18       pmLoadASCIINameSpace(3)  is called and to pre-process the configuration
19       files for pmlogger(1).
20
21       Input lines are read from infile (or standard input if  infile  is  not
22       specified), processed and written to standard output.
23
24       All  C-style comments of the form /* ... */ are stripped from the input
25       stream.
26
27       There are no predefined macros for pmcpp although macros may be defined
28       on the command line using the -D option, where name and value must fol‐
29       low the same rules as described below for the #define directive.
30
31       pmcpp accepts the  following  directives  in  the  input  stream  (like
32       cpp(1)):
33
34       ·  #include "filename"
35          or
36          #include <filename>
37          In either case the directory search path for filename tries filename
38          first, then the directory for the command line infile (if any), fol‐
39          lowed  by  any  directories  named in -I command line arguments, and
40          finally the $PCP_VAR_DIR/pmns directory (the latter is for backwards
41          compatibility  with  earlier  versions of pmcpp and the implied used
42          from pmLoadASCIINameSpace(3)).  #include directives may  be  nested,
43          up to a maximum depth of 5.
44
45       ·  #shell "command"
46          or
47          #shell 'command'
48          The  shell  command  will  be  executed  and  the standard output is
49          inserted into the stream of data to be processed  by  pmcpp.   Func‐
50          tionally this is similar to a #include directive, except input lines
51          are read from a command rather than a file.  The #shell directive is
52          most  useful for including or excluding #define or #undef directives
53          based on run-time logic in the command.
54
55       ·  #define name value
56          or
57          #define name "value"
58          or
59          #define name 'value'
60          Defines a value for the macro name which must  be  a  valid  C-style
61          name,  so  leading alphabetic or underscore followed by zero or more
62          alphanumerics or underscores.  value is optional (and defaults to an
63          empty  string).   There is no character escape mechanism, but either
64          single quotes or double quotes may be used to define  a  value  with
65          special characters or embedded horizontal white space (no newlines).
66
67       ·  #undef name
68          Removes the macro definition, if any, for name.
69
70       ·  #ifdef name
71          ...
72          #endif
73          or
74          #ifndef name
75          ...
76          #endif
77          The  enclosing  lines will be stripped or included, depending if the
78          macro name is defined or not.
79
80       ·  #else
81          Within a #ifdef or #ifndef block, #else may be used to delimit lines
82          to be included if the preceding ``if'' condition is false.
83
84       Macro  substitution is achieved by breaking the input stream into words
85       separated by white space or characters that are not valid  in  a  macro
86       name,  i.e.  not alphanumeric and not underscore.  Each word is checked
87       and if it matches a macro name, the  word  is  replaced  by  the  macro
88       value, otherwise the word is unchanged.
89
90       There  is  generally  one output line for each input line, although the
91       line may be empty if the text has been stripped due to the handling  of
92       comments  or  conditional  directives.   When  there is a change in the
93       input stream, an additional output line is generated of the form:
94
95                 # lineno "filename"
96
97       to indicate the following line of output  corresponds  to  line  number
98       lineno of the input file filename.
99

OPTIONS

101       The available command line options are:
102
103       -D name[=value], --define=name[=value]
104            Defines a macro with an optional value, as described earlier.
105
106       -I dir, --include=dir
107            An additional directory to search for include files.
108
109       -P   Suppresses  the  generation  of  the  linemarker  lines, described
110            above.
111
112       -s, --shell
113            Changes the expected input style from C-like to shell-like  (where
114            #  is  a  comment  prefix).   This forces the following changes in
115            pmcpp behaviour:
116       ·  The control prefix character changes from # to %,  so  %include  for
117          example.
118       ·  No comment stripping is performed.
119
120       -r, --restrict
121          Provide  finer  control  of  macro expansion - this option restricts
122          macro substitution to words that match the patterns #name or #{name}
123          or  if  -s  is  specified, then %name or %{name}.  In this mode, the
124          macro name alone in the input stream will never be expanded, however
125          in  control  lines  (like #ifdef) the macro name should appear alone
126          with out the prefix character or the  curly  braces  (refer  to  the
127          EXAMPLES below).
128
129       Important cpp(1) features that are not supported by pmcpp include:
130       ·  Macros with parameters - the pmcpp macros support only parameterless
131          string substitution.
132       ·  #if expr
133          ...
134          #endif
135       ·  Nested use of #ifdef or #ifndef.
136       ·  Stripping C++ style comments, as in // comment.
137       ·  Error recovery - the first error encountered by pmcpp will be fatal.
138       ·  cpp(1) command line options like -o, -W, -U, and -x.
139

EXAMPLES

141       ┌─────────────────────────────────────────────┐
142       │Command: pmcpp                               
143       ├───────────────────────┬─────────────────────┤
144Input                  Output              
145       ├───────────────────────┼─────────────────────┤
146       │                       │ # 1 "<stdin>"       │
147       │#define MYDOMAIN 27    │                     │
148       │                       │                     │
149       │root {                 │ root {              │
150       │    foo   MYDOMAIN:0:0 │    foo   27:0:0     │
151       │}                      │ }                   │
152       └───────────────────────┴─────────────────────┘
153       For the following examples, the file frequencies contains the lines:
154               %define dk_freq 1minute
155               %define cpu_freq '15 sec'
156
157       ┌──────────────────────────────────────────────────────────────────────┐
158       │Command: pmcpp -rs                                                    
159       ├──────────────────────────────────┬───────────────────────────────────┤
160Input                             Output                            
161       ├──────────────────────────────────┼───────────────────────────────────┤
162       │# get logging frequencies         │ # get logging frequencies         │
163       │# e.g. dk_freq macro              │ # e.g. dk_freq macro              │
164       │%include "frequencies"            │                                   │
165       │                                  │                                   │
166       │log mandatory on %dk_freq {       │ log mandatory on 1minute {        │
167       │    disk.dev                      │    disk.dev                       │
168       │}                                 │ }                                 │
169       │                                  │                                   │
170       │# note no % for want_cpu here     │ # note no % for want_cpu here     │
171       │%ifdef want_cpu                   │                                   │
172       │%define cpu_pfx 'kernel.all.cpu.' │                                   │
173       │log mandatory on %cpu_freq {      │                                   │
174       │    %{cpu_pfx}user                │                                   │
175       │    %{cpu_pfx}sys                 │                                   │
176       │}                                 │                                   │
177       │%endif                            │                                   │
178       └──────────────────────────────────┴───────────────────────────────────┘
179       ┌──────────────────────────────────────────────────────────────────────┐
180       │Command: pmcpp -rs -Dwant_cpu                                         
181       ├──────────────────────────────────┬───────────────────────────────────┤
182Input                             Output                            
183       ├──────────────────────────────────┼───────────────────────────────────┤
184       │# get logging frequencies         │ # get logging frequencies         │
185       │# e.g. dk_freq macro              │ # e.g. dk_freq macro              │
186       │%include "frequencies"            │                                   │
187       │                                  │                                   │
188       │log mandatory on %dk_freq {       │ log mandatory on 1minute {        │
189       │    disk.dev                      │    disk.dev                       │
190       │}                                 │ }                                 │
191       │                                  │                                   │
192       │# note no % for want_cpu here     │ # note no % for want_cpu here     │
193       │%ifdef want_cpu                   │                                   │
194       │%define cpu_pfx 'kernel.all.cpu.' │                                   │
195       │log mandatory on %cpu_freq {      │ log mandatory on 15 sec {         │
196       │    %{cpu_pfx}user                │    kernel.all.cpu.user            │
197       │    %{cpu_pfx}sys                 │    kernel.all.cpu.sys             │
198       │}                                 │ }                                 │
199       │%endif                            │                                   │
200       └──────────────────────────────────┴───────────────────────────────────┘

PCP ENVIRONMENT

202       Environment variables with the prefix PCP_ are used to parameterize the
203       file  and  directory names used by PCP.  On each installation, the file
204       /etc/pcp.conf contains the  local  values  for  these  variables.   The
205       $PCP_CONF  variable may be used to specify an alternative configuration
206       file, as described in pcp.conf(5).
207
208       For environment variables affecting PCP tools, see pmGetOptions(3).
209

SEE ALSO

211       cpp(1),   pmLoadASCIINameSpace(3),   pmLoadNameSpace(3),   pcp.conf(5),
212       pcp.env(5) and PMNS(5).
213
214
215
216Performance Co-Pilot                                                  PMCPP(1)
Impressum