pmparsemetricspec(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | SEE ALSO | COLOPHON

PMPARSEMETRICSPEC(3)    Library Functions Manual    PMPARSEMETRICSPEC(3)

NAME         top

       pmParseMetricSpec, pmFreeMetricSpec - uniform metric
       specification parser

C SYNOPSIS         top

       #include <pcp/pmapi.h>

       int pmParseMetricSpec(const char *string, int isarch,
               char *source, pmMetricSpec **rsltp, char **errmsg);
       void pmFreeMetricSpec(pmMetricSpec *rslt);

       cc ... -lpcp

DESCRIPTION         top

       pmParseMetricSpec  accepts  a string specifying the name of a PCP
       performance metric, and optionally the source (either a  hostname
       or  a  PCP  archive filename) and instances for that metric.  The
       syntax is described in PCPIntro(1).

       If neither host nor archive component of the metric specification
       is provided, the isarch and source arguments are used to fill  in
       the returned pmMetricSpec structure.

       The  pmMetricSpec structure that is returned via rsltp represents
       the parsed string and has the following declaration:

           typedef struct {
               int     isarch;      /* source type: 0 -> live host, 1 -> archive, 2 -> local context */
               char    *source;     /* name of source host or archive */
               char    *metric;     /* name of metric */
               int     ninst;       /* number of instances, 0 -> all */
               char    *inst[1];    /* array of instance names */
           } pmMetricSpec;

       pmParseMetricSpec returns 0 if the given string was  successfully
       parsed.  In this case all the storage allocated by pmParseMetric‐
       Spec  can  be  released by a single call to free(3) using the ad‐
       dress returned from  pmMetricSpec  via  rsltp.   The  convenience
       macro pmFreeMetricSpec is a thinly disguised wrapper for free(3).

       pmParseMetricSpec  returns PM_ERR_GENERIC and a dynamically allo‐
       cated error message string in errmsg, if the  given  string  does
       not  parse.   Be sure to free(3) the error message string in this
       situation.

       In the case of an error, rsltp is undefined.  In the case of suc‐
       cess, errmsg is undefined.  If rsltp->ninst is 0, then rsltp->in‐
       st[0] is undefined.

SEE ALSO         top

       PMAPI(3) and pmLookupName(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug  report  for  this  manual  page,  send  it  to
       [email protected].    This  page  was  obtained  from  the  project's
       upstream                      Git                      repository
       ⟨https://github.com/performancecopilot/pcp.git⟩   on  2024-06-14.
       (At that time, the date of the most recent commit that was  found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems  in  this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or  you  have
       corrections  or  improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a  mail  to
       [email protected]

Performance Co-Pilot               PCP              PMPARSEMETRICSPEC(3)