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