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 folowing syntax:
       1.  Lines beginning with optional white space, followied 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).

Performance Co-Pilot                                   PCP                                       PMEQUIVINDOM(3)