Provided by: libpcp3-dev_6.2.0-1.1build4_amd64 bug

NAME

       pmRecordSetup, pmRecordAddHost, pmRecordControl - record mode support for PMAPI clients

C SYNOPSIS

       #include <pcp/pmafm.h>

       FILE *pmRecordSetup(const char *folio, const char *creator, int replay);
       int pmRecordAddHost(const char *host, int isdefault, pmRecordHost **rhp);
       int pmRecordControl(pmRecordHost *rhp, int request, const char *options);

       cc ... -lpcp_gui

DESCRIPTION

       These  routines  may  be  used  to  create a Performance Co-Pilot (PCP) archive ``on the fly'' to support
       ``record mode'' services for PMAPI client applications.

       Each record mode ``session'' involves one or more PCP archives each created using a dedicated pmlogger(1)
       process, with an overall Archive Folio format as understood by pmafm(1), to name and collect all  of  the
       archives associated with a single recording session.

       The  pmRecordHost  structure  is  used to maintain state information between the creator of the recording
       session and the associated pmlogger process(es).  The structure is defined as:
         typedef struct {
             FILE   *f_config;    /* caller writes pmlogger configuration here */
             int    fd_ipc;       /* IPC channel to pmlogger */
             char   *logfile;     /* full pathname for pmlogger error logfile */
             pid_t  pid;          /* process id for pmlogger */
             int    status;       /* exit status, -1 if unknown */
         } pmRecordHost;

       The routines are used in combination to create a recording session as follows.

       1.  Call pmRecordSetup to establish a new recording session.  A new Archive Folio will be  created  using
           the  name  folio; if the file or directory folio already exists, or the file folio cannot be created,
           this is an error.  The application that is creating the session is identified by creator (most  often
           this  would  be  the same as the global PMAPI application name, as returned by pmGetProgname(3)).  If
           the application knows how to create its own configuration file to replay the recorded  session,  then
           replay should be non-zero.

           pmRecordSetup returns a stdio stream onto which the application should write the text of the required
           replay configuration file, if any.

       2.  For each host that is to be included in the recording session, call pmRecordAddHost.  A new pmRecord‐
           Host structure is returned via rhp.  It is assumed that pmcd(1) is running on host as this is how pm‐
           logger(1) will retrieve the required performance metrics.

           If this host is the default host for this recording session, then isdefault should be non-zero.  This
           will  ensure  that  the  corresponding  archive appears first in the PCP archive folio, and hence the
           tools used to replay the archive folio will make the correct determination of the archive  associated
           with the default host.  At most one host per recording session may be nominated as the default host.

           The  calling  application  should  write the desired pmlogger configuration onto the stdio stream re‐
           turned via the f_config field in the pmRecordHost structure.

       3.  Optionally add arguments to the command line that will be used to launch pmlogger(1) by  calling  pm‐
           RecordControl  with  a  request of PM_REC_SETARG.  The argument is passed via options and one call to
           pmRecordControl is required for each distinct argument.

           An argument may be added for a particular pmlogger instance identified by rhp, or if the rhp argument
           is NULL the argument is added for all pmlogger instances that will be launched in the current record‐
           ing session.

           Independent of any calls to pmRecordControl with a request of PM_REC_SETARG, each  pmlogger  instance
           will  automatically be launched with the following arguments: -c, -h, -l, -x and the basename for the
           PCP archive.

       4.  To commence the recording session, call pmRecordControl with a request of PM_REC_ON, and rhp must  be
           NULL.   This will launch one pmlogger(1) process for each host in the recording session, and initial‐
           ize the fd_ipc, logfile, pid and status fields in the associated pmRecordHost structure(s).

       5.  To terminate a  pmlogger  instance  identified  by  rhp,  call  pmRecordControl  with  a  request  of
           PM_REC_OFF.   If the rhp argument to pmRecordControl is NULL, the termination request is broadcast to
           all pmlogger processes in the current recording session.

           An informative dialog is generated directly by each pmlogger process and hence note the  comments  on
           the disposition of output from pmlogger below.

           Alternatively,  pmlogger can be started with options to limit the duration of logging, e.g. the -T or
           -s arguments, in which case there is no need to call pmRecordControl with a request of PM_REC_OFF and
           no dialog is generated.

       6.  To display the current status of the pmlogger instance identified by rhp, call pmRecordControl with a
           request of PM_REC_STATUS.  If the rhp argument to pmRecordControl is  NULL,  the  status  request  is
           broadcast to all pmlogger processes in the current recording session.

           The  display is generated directly by each pmlogger process and hence note the comments on the dispo‐
           sition of output from pmlogger below.

       7.  To detach a pmlogger instance identified by rhp and allow it to continue independent of the  applica‐
           tion  that  launched the recording session, call pmRecordControl with a request of PM_REC_DETACH.  If
           the rhp argument to pmRecordControl is NULL, the detach request is broadcast to all pmlogger process‐
           es in the current recording session.

           An informative dialog is generated directly by each pmlogger process and hence note the  comments  on
           the disposition of output from pmlogger below.

       The  calling  application  should  not  close any of the returned stdio streams; this will be done by pm‐
       RecordControl when recording is commenced.

       Once pmlogger has been started for a recording session, then pmlogger will assume responsibility for  any
       dialog  with  the user in the event that the application that launched the recording session should exit,
       particularly without terminating the recording session.

       By default, information and dialogs from pmlogger will be displayed using pmquery(1)  on  the  assumption
       that  most  applications  wishing to launch a recording session are GUI-based.  In the event that pmquery
       fails to display the information (for example, because the DISPLAY environment variable is not set),  pm‐
       logger  will  write on its own stderr stream (not the stderr stream of the launching process); the output
       will be assigned to the XXXXXX.host.log file described in the FILES section below.  For convenience,  the
       full pathname to this file is provided via the logfile field in the pmRecordHost structure.

       If  the options argument to pmRecordControl is not NULL, this string may be used to pass additional argu‐
       ments to pmquery(1) in those cases where a dialog is to be displayed.  One use of this  capability  would
       be to provide a -geometry string to control the placement of the dialog.

       Premature  termination of a launched pmlogger process may be determined using the pmRecordHost structure,
       by calling select(2) on the fd_ipc field or polling the status field that will  contain  the  termination
       status from waitpid(2) if known, else -1.

DIAGNOSTICS

       pmRecordSetup  may  return  NULL in the event of an error.  Check errno for the real cause, but the value
       EINVAL typically means that the order of calls to these routines is not correct (there is  obvious  state
       associated  with  the  current recording session that is maintained across calls to these routines).  For
       example the following calls would produce this EINVAL error; calling pmRecordControl before  calling  pm‐
       RecordAddHost at least once, or calling pmRecordAddHost before calling pmRecordSetup.

       pmRecordControl  and  pmRecordAddHost both return 0 on success, else a value less than 0 suitable for de‐
       coding with pmErrStr(3) on failure.  The value -EINVAL has the same interpretation as errno being set  to
       EINVAL as described above.

       pmRecordControl will return PM_ERR_IPC if the associated pmlogger process has already exited.

FILES

       These  routines create a number of files in the same directory as the folio file named in the call to pm‐
       RecordSetup.  In all cases, the ``XXXXXX'' component is the result of calling mktemp(3).

       XXXXXX    If replay is non-zero, this is the creator's replay configuration file, else an  empty  control
                 file, used to guarantee uniqueness.
       folio     The PCP Archive Folio, suitable for use with pmafm(1).
       XXXXXX.host.config
                 The  pmlogger(1)  configuration  for each host - if the same host is used in different calls to
                 pmRecordAddHost within the same recording session then one of the letters ``a''  through  ``z''
                 will be appended to the ``XXXXXX'' part of all associated file names to ensure uniqueness.
       XXXXXX.host.log
                 stdout and stderr for the pmlogger(1) instance for each host.
       XXXXXX.host.{0,meta,index}
                 The files comprising a single PCP archive for each host.

SEE ALSO

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

Performance Co-Pilot                                   PCP                                           PMRECORD(3)