Section 3: library functions
pmGetChildrenStatus – return the descendent nodes of a PMNS node and their respective status C Synopsis #include <pcp/pmapi.h> int pmGetChildrenStatus(const char *name, char ***offspring, int **status); cc … -lpcp Description Given a fully qualified pathname to a node in the current Performance Metrics Name Space (PMNS), as identified by name, pmGetChildrenStatus returns via offspring a list…
pmGetChildren – return the descendent nodes of a PMNS node C Synopsis #include <pcp/pmapi.h> int pmGetChildren(const char *name, char ***offspring); cc … -lpcp Description Given a fully qualified pathname to a node in the current Performance Metrics Name Space (PMNS), as identified by name, pmGetChildren returns via offspring a list of the relative names of…
pmGetArchiveLabel – fetch the label record from a set of performance metrics archive logs C Synopsis #include <pcp/pmapi.h> int pmGetArchiveLabel(pmLogLabel *lp); cc … -lpcp Description Within the framework of the Performance Co-Pilot (PCP), archive logs of performance metrics values may be accumulated and saved using the program pmlogger(1). The routine pmGetArchiveLabel may be used to…
pmGetArchiveEnd – locate logical end of file for a set of archive logs C Synopsis #include <pcp/pmapi.h> int pmGetArchiveEnd(struct timeval *tvp); cc … -lpcp Description Assuming the current PMAPI context is associated with a set of archive logs, pmGetArchiveEnd will attempt to find the logical end of file (after the last complete record in the…
pmFreeResult – release storage allocated for performance metrics values C Synopsis #include <pcp/pmapi.h> void pmFreeResult(pmResult *result); cc … -lpcp Description The variable sized results returned by pmFetch(3) are allocated below the Performance Metrics Application Programming Interface (PMAPI) using a combination of dynamic (i.e. malloc(3)) and specialized allocation strategies. Applications should call pmFreeResult to release the…
pmgetopt_r, pmGetOptions, pmGetContextOptions, pmFreeOptions, pmUsageMessage – command line handling for PMAPI tools C Synopsis #include <pcp/pmapi.h> int pmgetopt_r(int argc, char *const *argv, pmOptions *opts); int pmGetOptions(int argc, char *const *argv, pmOptions *opts); int pmGetContextOptions(int ctx, pmOptions *opts); void pmUsageMessage(pmOptions *opts); void pmFreeOptions(pmOptions *opts); cc … -lpcp Description The pmGetOptions function provides command line option processing…
pmParseMetricSpec, pmFreeMetricSpec – uniform metric specification parser C Synopsis #include <pcp/pmapi.h> int pmParseMetricSpec(const char *string, int isarch, char *source, pmMetricSpec **rsltp, char **errmsg); void pmFreeMetricSpec(pmMetricSpec *rslt); cc … -lpcp Description pmParseMetricSpec accepts a string specifying the name of a PCP performance metric, and optionally the source (either a hostname or a PCP archive log filename) and instances for…
pmFreeEventResult, pmFreeHighResEventResult – release storage allocated for unpacked event records C Synopsis #include <pcp/pmapi.h> void pmFreeEventResult(pmResult **rset); void pmFreeHighResEventResult(pmHighResResult **hrset); cc … -lpcp Description When processing event records, if pmUnpackEventRecords(3) is used to unpack event records from a metric within a pmResult structure with a value of type PM_TYPE_EVENT then the structure returned from pmUnpackEventRecords(3)…
pmFetchArchive – get performance metrics directly from a set if archive logs C Synopsis #include <pcp/pmapi.h> int pmFetchArchive(pmResult **result); cc … -lpcp Description pmFetchArchive is a variant of pmFetch(3) that may only be used when the current Performance Metrics Application Programming Interface (PMAPI) context is associated with a set of archive logs. The result is…
pmFetch – get performance metric values C Synopsis #include <pcp/pmapi.h> int pmFetch(int numpmid, pmID *pmidlist, pmResult **result); cc … -lpcp Description Given a list of Performance Metric Identifiers (PMID)s, e.g. as constructed by pmLookupName(3), via pmidlist and numpmid, fetch the values for these performance metrics. The call to pmFetch is executed in the context of…
pmExtractValue – extract a performance metric value from a pmResult structure C Synopsis #include <pcp/pmapi.h> int pmExtractValue(int valfmt, const pmValue *ival, int itype, pmAtomValue *oval, int otype); cc … -lpcp Description The pmValue structure is embedded within the pmResult structure that is used to return one or more performance metrics; see pmFetch(3). All performance metric values may be…
pmEventFlagsStr, pmEventFlagsStr_r – convert an event record flags value into a string C Synopsis #include <pcp/pmapi.h> const char *pmEventFlagsStr(int flags); char *pmEventFlagsStr_r(int flags, char *buf, int buflen); cc … -lpcp Description For use in error and diagnostic messages, pmEventFlagsStr returns a `human readable’ version of the value flags, assuming this to be the er_flags field…
pmErrStr, pmErrStr_r – convert a PMAPI error code into a string C Synopsis #include <pcp/pmapi.h> const char *pmErrStr(int code); char *pmErrStr_r(int code, char *buf, int buflen); cc … -lpcp Description Translate an error code into a text string, suitable for generating a diagnostic message. The pmErrStr_r function does the same, but stores the result in…
pmDupContext – duplicate a PMAPI context C Synopsis #include <pcp/pmapi.h> int pmDupContext(void); cc … -lpcp Description An application using the Performance Metrics Application Programming Interface (PMAPI) may manipulate several concurrent contexts, each associated with a source of performance metrics, e.g. pmcd(1) on some host, or a set of archive logs of performance metrics as created…
pmDiscoverServices – discover PCP services on the network C Synopsis #include <pcp/pmapi.h> int pmDiscoverServices(const char *service, const char *mechanism, char ***urls); #include <pcp/impl.h> int __pmDiscoverServicesWithOptions(const char *service, const char *mechanism, const char *optionsString, const volatile unsigned *flags, char ***urls); cc … -lpcp Description Given a PCP service name, as identified by service, and using the…
pmDestroyContext – destroy a PMAPI context C Synopsis #include <pcp/pmapi.h> int pmDestroyContext(int handle); cc … -lpcp Description An application using the Performance Metrics Application Programming Interface (PMAPI) may manipulate several concurrent contexts, each associated with a source of performance metrics, e.g. pmcd(1) on some host, or an archive log of performance metrics as created by…
pmDerivedErrStr – return error message from failure to parse derived metric definition C Synopsis #include <pcp/pmapi.h> char *pmDerivedErrStr(void); cc … -lpcp Description When pmRegisterDerived(3) is called to add a new derived metric definition and an error occurs, pmDerivedErrStr may be called to return the associated error message. The pmRegisterDerivedMetric interface provides a convenience wrapper around…
pmDelProfile – delete instance(s) from the current PMAPI instance profile C Synopsis #include <pcp/pmapi.h> int pmDelProfile(pmInDom indom, int numinst, int *instlist); cc … -lpcp Description The set of instances for performance metrics returned from a pmFetch(3) call may be filtered or restricted using an instance profile. There is one instance profile for each context the…
pmCtime – format the date and time for a reporting timezone C Synopsis #include <time.h> #include <pcp/pmapi.h> char *pmCtime(const time_t *clock, char *buf); cc … -lpcp Description pmCtime is very similar to ctime(3), except the timezone used is the current “reporting timezone” (rather than the default TZ environment variable scheme), and the result is returned…
pmCreateFetchGroup, pmExtendFetchGroup_item, pmExtendFetchGroup_indom, pmExtendFetchGroup_event, pmExtendFetchGroup_timestamp, pmFetchGroup, pmGetFetchGroupContext, pmDestroyFetchGroup – simplified performance metrics value fetch and conversion C Synopsis #include <pcp/pmapi.h> int pmCreateFetchGroup(pmFG *ptr, int type, const char *name); int pmExtendFetchGroup_item(pmFG pmfg, const char *metric, const char *instance, const char *scale, pmAtomValue *out_value, int out_type, int out_sts); int pmExtendFetchGroup_indom(pmFG pmfg, const char *metric, const char *scale,…