1PMRECORD(3) Library Functions Manual PMRECORD(3)
2
6 pmRecordSetup, pmRecordAddHost, pmRecordControl - record mode support
7 for PMAPI clients
8
10 #include <pcp/pmafm.h>
11 FILE *pmRecordSetup(const char *folio, const char *creator,
13 int replay);
14 int pmRecordAddHost(const char *host, int isdefault,
15 pmRecordHost **rhp);
16 int pmRecordControl(pmRecordHost *rhp, int request,
17 const char *options);
18 cc ... -lpcp_gui
20
22 These routines may be used to create a Performance Co-Pilot (PCP) ar‐
23 chive ``on the fly'' to support ``record mode'' services for PMAPI
24 client applications.
25 Each record mode ``session'' involves one or more PCP archives each
27 created using a dedicated pmlogger(1) process, with an overall Archive
28 Folio format as understood by pmafm(1), to name and collect all of the
29 archives associated with a single recording session.
30 The pmRecordHost structure is used to maintain state information be‐
32 tween the creator of the recording session and the associated pmlogger
33 process(es). The structure is defined as:
34 typedef struct {
35 FILE *f_config; /* caller writes pmlogger configuration here */
36 int fd_ipc; /* IPC channel to pmlogger */
37 char *logfile; /* full pathname for pmlogger error logfile */
38 pid_t pid; /* process id for pmlogger */
39 int status; /* exit status, -1 if unknown */
40 } pmRecordHost;
41 The routines are used in combination to create a recording session as
43 follows.
44 1. Call pmRecordSetup to establish a new recording session. A new Ar‐
46 chive Folio will be created using the name folio; if the file or
47 directory folio already exists, or the file folio cannot be creat‐
48 ed, this is an error. The application that is creating the session
49 is identified by creator (most often this would be the same as the
50 global PMAPI application name, as returned by pmGetProgname(3)).
51 If the application knows how to create its own configuration file
52 to replay the recorded session, then replay should be non-zero.
53 pmRecordSetup returns a stdio stream onto which the application
55 should write the text of the required replay configuration file, if
56 any.
57 2. For each host that is to be included in the recording session, call
59 pmRecordAddHost. A new pmRecordHost structure is returned via rhp.
60 It is assumed that pmcd(1) is running on host as this is how pmlog‐
61 ger(1) will retrieve the required performance metrics.
62 If this host is the default host for this recording session, then
64 isdefault should be non-zero. This will ensure that the corre‐
65 sponding archive appears first in the PCP archive folio, and hence
66 the tools used to replay the archive folio will make the correct
67 determination of the archive associated with the default host. At
68 most one host per recording session may be nominated as the default
69 host.
70 The calling application should write the desired pmlogger configu‐
72 ration onto the stdio stream returned via the f_config field in the
73 pmRecordHost structure.
74 3. Optionally add arguments to the command line that will be used to
76 launch pmlogger(1) by calling pmRecordControl with a request of
77 PM_REC_SETARG. The argument is passed via options and one call to
78 pmRecordControl is required for each distinct argument.
79 An argument may be added for a particular pmlogger instance identi‐
81 fied by rhp, or if the rhp argument is NULL the argument is added
82 for all pmlogger instances that will be launched in the current
83 recording session.
84 Independent of any calls to pmRecordControl with a request of
86 PM_REC_SETARG, each pmlogger instance will automatically be
87 launched with the following arguments: -c, -h, -l, -x and the base‐
88 name for the PCP archive.
89 4. To commence the recording session, call pmRecordControl with a re‐
91 quest of PM_REC_ON, and rhp must be NULL. This will launch one pm‐
92 logger(1) process for each host in the recording session, and ini‐
93 tialize the fd_ipc, logfile, pid and status fields in the associat‐
94 ed pmRecordHost structure(s).
95 5. To terminate a pmlogger instance identified by rhp, call pmRecord‐
97 Control with a request of PM_REC_OFF. If the rhp argument to pm‐
98 RecordControl is NULL, the termination request is broadcast to all
99 pmlogger processes in the current recording session.
100 An informative dialog is generated directly by each pmlogger
102 process and hence note the comments on the disposition of output
103 from pmlogger below.
104 Alternatively, pmlogger can be started with options to limit the
106 duration of logging, e.g. the -T or -s arguments, in which case
107 there is no need to call pmRecordControl with a request of
108 PM_REC_OFF and no dialog is generated.
109 6. To display the current status of the pmlogger instance identified
111 by rhp, call pmRecordControl with a request of PM_REC_STATUS. If
112 the rhp argument to pmRecordControl is NULL, the status request is
113 broadcast to all pmlogger processes in the current recording ses‐
114 sion.
115 The display is generated directly by each pmlogger process and
117 hence note the comments on the disposition of output from pmlogger
118 below.
119 7. To detach a pmlogger instance identified by rhp and allow it to
121 continue independent of the application that launched the recording
122 session, call pmRecordControl with a request of PM_REC_DETACH. If
123 the rhp argument to pmRecordControl is NULL, the detach request is
124 broadcast to all pmlogger processes in the current recording ses‐
125 sion.
126 An informative dialog is generated directly by each pmlogger
128 process and hence note the comments on the disposition of output
129 from pmlogger below.
130 The calling application should not close any of the returned stdio
132 streams; this will be done by pmRecordControl when recording is com‐
133 menced.
134 Once pmlogger has been started for a recording session, then pmlogger
136 will assume responsibility for any dialog with the user in the event
137 that the application that launched the recording session should exit,
138 particularly without terminating the recording session.
139 By default, information and dialogs from pmlogger will be displayed us‐
141 ing pmquery(1) on the assumption that most applications wishing to
142 launch a recording session are GUI-based. In the event that pmquery
143 fails to display the information (for example, because the DISPLAY en‐
144 vironment variable is not set), pmlogger will write on its own stderr
145 stream (not the stderr stream of the launching process); the output
146 will be assigned to the XXXXXX.host.log file described in the FILES
147 section below. For convenience, the full pathname to this file is pro‐
148 vided via the logfile field in the pmRecordHost structure.
149 If the options argument to pmRecordControl is not NULL, this string may
151 be used to pass additional arguments to pmquery(1) in those cases where
152 a dialog is to be displayed. One use of this capability would be to
153 provide a -geometry string to control the placement of the dialog.
154 Premature termination of a launched pmlogger process may be determined
156 using the pmRecordHost structure, by calling select(2) on the fd_ipc
157 field or polling the status field that will contain the termination
158 status from waitpid(2) if known, else -1.
159
161 pmRecordSetup may return NULL in the event of an error. Check errno
162 for the real cause, but the value EINVAL typically means that the order
163 of calls to these routines is not correct (there is obvious state asso‐
164 ciated with the current recording session that is maintained across
165 calls to these routines). For example the following calls would pro‐
166 duce this EINVAL error; calling pmRecordControl before calling pmRecor‐
167 dAddHost at least once, or calling pmRecordAddHost before calling pm‐
168 RecordSetup.
169 pmRecordControl and pmRecordAddHost both return 0 on success, else a
171 value less than 0 suitable for decoding with pmErrStr(3) on failure.
172 The value -EINVAL has the same interpretation as errno being set to
173 EINVAL as described above.
174 pmRecordControl will return PM_ERR_IPC if the associated pmlogger
176 process has already exited.
177
179 These routines create a number of files in the same directory as the
180 folio file named in the call to pmRecordSetup. In all cases, the
181 ``XXXXXX'' component is the result of calling mktemp(3).
182 XXXXXX If replay is non-zero, this is the creator's replay configu‐
184 ration file, else an empty control file, used to guarantee
185 uniqueness.
186 folio The PCP Archive Folio, suitable for use with pmafm(1).
187 XXXXXX.host.config
188 The pmlogger(1) configuration for each host - if the same
189 host is used in different calls to pmRecordAddHost within the
190 same recording session then one of the letters ``a'' through
191 ``z'' will be appended to the ``XXXXXX'' part of all associ‐
192 ated file names to ensure uniqueness.
193 XXXXXX.host.log
194 stdout and stderr for the pmlogger(1) instance for each host.
195 XXXXXX.host.{0,meta,index}
196 The files comprising a single PCP archive for each host.
198 pmafm(1), pmlogger(1), pmquery(1) and PMAPI(3).
199Performance Co-Pilot PCP PMRECORD(3)