NAME

       pmLoadNameSpace - load a local PMNS for an application


C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmLoadNameSpace(const char *filename)

       cc ... -lpcp


DESCRIPTION

       If  the  application  wants to force using a local Perfor­
       mance Metrics Name Space (PMNS) instead of  a  distributed
       PMNS  then  it must load the PMNS using pmLoadNameSpace or
       pmLoadASCIINameSpace(3).  If the application is to  use  a
       distributed  PMNS,  then it should NOT make a call to load
       the PMNS explicitly.

       The filename argument designates  the  PMNS  of  interest.
       For  applications  not requiring a tailored PMNS, the spe­
       cial value PM_NS_DEFAULT may  be  used  for  filename,  to
       force the default local PMNS to be loaded.

       The   default   local   PMNS   is   found   in   the  file
       $PCP_VAR_DIR/pmns/root  unless  the  environment  variable
       PMNS_DEFAULT is set, in which case the value is assumed to
       be the pathname to the file containing the  default  local
       PMNS.

       Externally  a PMNS may be stored in either an ASCII format
       or a binary format.  The utility pmnscomp(1)  is  used  to
       create  the  binary format from the ASCII format described
       in pmns(4).

       If the binary format is used, no checking is performed for
       aliasing  in  which multiple names in the PMNS are associ­
       ated with a single Performance Metrics Identifier  (PMID).
       If the ASCII format is to be used, duplicate PMIDs are not
       allowed,  although  pmLoadASCIINameSpace(3)  provides   an
       alternative  interface  with user-defined control over the
       processing of duplicate PMIDs in an ASCII format PMNS.

       pmLoadNameSpace attempts to load the PMNS  by  trying  the
       following combinations in order,

       1. Binary format from the file filename.bin

       2. Binary format from the file filename

       3. ASCII format from the file filename


pmLoadNameSpace returns zero on success.


       $PCP_VAR_DIR/pmns/root   the  default local PMNS, when the
                                environment variable PMNS_DEFAULT
                                is unset


PCP ENVIRONMENT

       Environment  variables  with  the  prefix PCP_ are used to
       parameterize the file and directory names used by PCP.  On
       each  installation,  the  file  /etc/pcp.conf contains the
       local values for these variables.  The $PCP_CONF  variable
       may  be used to specify an alternative configuration file,
       as described in pcp.conf(4).  Values for  these  variables
       may  be  obtained programatically using the pmGetConfig(3)
       function.


SEE ALSO

       pmnscomp(1), PMAPI(3),  pmGetConfig(3),  pmLoadASCIINameS­
       pace(3),  pmTrimNameSpace(3),  pcp.conf(4), pcp.env(4) and
       pmns(4).


DIAGNOSTICS

       Syntax and other errors in the parsing  of  the  PMNS  are
       reported  on  stderr  with  a  message of the form ``Error
       Parsing ASCII PMNS: ...''.

       PM_ERR_DUPPMNS

              It is an error to try and load more than one  PMNS,
              or  to  call  either pmLoadNameSpace and/or pmLoad­
              ASCIINameSpace(3) more than once.

       PM_ERR_PMNS

              Syntax error in an ASCII format PMNS.


Man(1) output converted with man2html