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).