PMEQUIVINDOM(3)

NAME
__pmEquivInDom - check if two instance domains are equivalent

C SYNOPSIS
#include <pcp/pmapi.h>
#include <pcp/libpcp.h>

int __pmEquivInDom(pmInDom a, pmInDom b)

cc ... -lpcp

CAVEAT
This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and at some point in the future they may not work or may provide different semantics.

DESCRIPTION
Within the Performance Co-Pilot (PCP) each instance domain is assigned a unique Instance Domain Identifier (pmInDom). Internally a pmInDom is constructed from 2 fields: the domain number (of the associated Performance Metrics Domain Agent, or PMDA) and the serial number (assigned by the PMDA).

In some unusual circumstances different PMDAs may support independent Instance Domains that are semantically equivalent, e.g. per CPU or per process identifier. __pmEquivInDom provides a mechanism to determine if Instance Domain a is equivalent to Instance Domain b.

The ``equivalence'' of Instance Domains is defined by an external configuration file, identified by the environment variable $PCP_INDOM_CONFIG or $PCP_ETC_DIR/pcp/indom.config by default. The format for the configuration file is defined in the CONFIGURATION FILE section below.

If $PCP_INDOM_CONFIG is an empty string, no equivalence mapping is loaded.

CONFIGURATION FILE
An Instance Domain equivalence mapping file conforms to the following syntax:
1.  Lines beginning with optional white space, followed by ``#'' are considered comments.
2.  Blank lines are ignored.
3.  Each remaining line defines one `equivalence map'' with a list of white-space separated instance domains, each consisting of a number (the domain number), a period ``.'' and a number (the serial number). As a special case to ``match all serial numbers'', the serial number part can be ``*''.

The format of a pmInDom demands that a domain number is in the range 0 to 511, and a numeric serial number is in the range 0 to 4194303.

DIAGNOSTICS AND RETURN VALUES
The return value is 1 if the Instance Domains are equivalent, else 0 if they are not. In rare cases a return value of -1 is used to indicate some problem (reported on standard error) in opening or parsing the configuration file.

SEE ALSO
pmLookupInDom(3) and PMAPI(3).