Man page - pmtraversepmns_r(3)

Packages contains this manual

Package: libpcp3-dev
apt-get install libpcp3-dev

Manuals in package:

Documentations in package:

libpcp3-dev

Manual

PMTRAVERSEPMNS

NAME
C SYNOPSIS
DESCRIPTION
DIAGNOSTICS
SEE ALSO

NAME

pmTraversePMNS , pmTraversePMNS_r - traverse the performance metrics name space

C SYNOPSIS

#include <pcp/pmapi.h>

int pmTraversePMNS(const char * name , void (* dometric )(const char *));
int pmTraversePMNS_r(const char * name , void (* dometric_r )(const char *, void *), void * closure );

cc ... -lpcp

DESCRIPTION

The routine pmTraversePMNS may be used to perform a depth-first traversal of the Performance Metrics Name Space (PMNS).

The traversal starts at the node identified by name - if name is an empty string (i.e. "" ), the traversal starts at the root of the PMNS. Usually name would be the pathname of a non-leaf node in the PMNS.

For each leaf node (i.e. performance metric) found in the traversal, the user-supplied routine dometric is called with the full pathname of that metric in the PMNS as the single argument. This argument is null-byte terminated, and is constructed from a buffer that is managed internally to pmTraversePMNS . Consequently the value is only valid during the call to dometric - if the pathname needs to be retained, it should be copied using strdup (3) before returning from dometric .

The pmTraversePMNS_r routine performs the same function, except the callback method func_r has an additional parameter that will be closure from the initial call to pmTraversePMNS_r . The additional parameter to pmTraversePMNS_r and the callback method allows the caller to pass context through pmTraversePMNS_r and into the callback method func_r , making the service more useful for multi-threaded applications where thread-private data can be accessed in the callback method via the closure argument.

On success pmTraversePMNS and pmTraversePMNS_r return the number of leaf nodes found in the traversal, which will be one (1) if name is either a leaf node, or a derived metric or a non-leaf node with one child. If name is a non-leaf node, the returned value will be zero or greater (zero is returned in the special case where name is a dynamic root node that currently has no children). In all cases, derived metrics present in the PMNS subtree below name are counted as leaf-nodes. If an an error occurs, pmTraversePMNS and pmTraversePMNS_r will return a negative error code, as described in the DIAGNOSTICS section below.

DIAGNOSTICS

PM_ERR_NOPMNS

Failed to access a PMNS for operation. Note that if the application hasn’t a priori called pmLoadNameSpace(3) and wants to use the distributed PMNS, then a call to pmTraversePMNS must be made inside a current context.

PM_ERR_NAME

The initial pathname name is not valid in the current PMNS.

PM_ERR_*

Other diagnostics are for protocol failures when accessing the distributed PMNS.