1PMAFM(3)                   Library Functions Manual                   PMAFM(3)
2
3
4

NAME

6       pmafm,  pmRecordSetup,  pmRecordAddHost,  pmRecordControl - record mode
7       support for PMAPI clients
8

C SYNOPSIS

10       #include <pcp/pmafm.h>
11
12       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
19       cc ... -lpcp_gui
20

DESCRIPTION

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
26       Each record mode ``session'' involves one or more PCP archive logs 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       archive logs associated with a single recording session.
30
31       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
42       The routines are used in combination to create a recording  session  as
43       follows.
44
45       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
54           pmRecordSetup returns a stdio stream  onto  which  the  application
55           should write the text of the required replay configuration file, if
56           any.
57
58       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
63           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
71           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
75       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
80           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
85           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 log.
89
90       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
96       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
101           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
105           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
110       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
116           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
120       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
127           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
131       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
135       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
140       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
150       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
155       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

SEE ALSO

161       pmafm(1), pmlogger(1), pmquery(1) and PMAPI(3).
162

FILES

164       These routines create a number of files in the same  directory  as  the
165       folio  file  named  in  the  call  to pmRecordSetup.  In all cases, the
166       ``XXXXXX'' component is the result of calling mktemp(3).
167
168       XXXXXX    If replay is non-zero, this is the creator's replay  configu‐
169                 ration  file,  else  an empty control file, used to guarantee
170                 uniqueness.
171       folio     The PCP Archive Folio, suitable for use with pmafm(1).
172       XXXXXX.host.config
173                 The pmlogger(1) configuration for each host  -  if  the  same
174                 host is used in different calls to pmRecordAddHost within the
175                 same recording session then one of the letters ``a''  through
176                 ``z''  will be appended to the ``XXXXXX'' part of all associ‐
177                 ated file names to ensure uniqueness.
178       XXXXXX.host.log
179                 stdout and stderr for the pmlogger(1) instance for each host.
180       XXXXXX.host.{0,meta,index}
181                 The files comprising a single PCP archive for each host.

DIAGNOSTICS

183       pmRecordSetup may return NULL in the event of an  error.   Check  errno
184       for the real cause, but the value EINVAL typically means that the order
185       of calls to these routines is not correct (there is obvious state asso‐
186       ciated  with  the  current  recording session that is maintained across
187       calls to these routines).  For example the following calls  would  pro‐
188       duce this EINVAL error; calling pmRecordControl before calling pmRecor‐
189       dAddHost at least once, or calling pmRecordAddHost before  calling  pm‐
190       RecordSetup.
191
192       pmRecordControl  and  pmRecordAddHost  both return 0 on success, else a
193       value less than 0 suitable for decoding with  pmErrStr(3)  on  failure.
194       The  value  -EINVAL  has  the same interpretation as errno being set to
195       EINVAL as described above.
196
197       pmRecordControl will  return  PM_ERR_IPC  if  the  associated  pmlogger
198       process has already exited.
199
200
201
202Performance Co-Pilot                  PCP                             PMAFM(3)
Impressum