PCPIntro - introduction to the Performance Co-Pilot (PCP) libraries

       These  errors  may  occur  in the interactions between a PCP client and the library routines that provide
       historical performance data from PCP archives created by pmlogger(1).

       PM_ERR_LOGFILEMissingarchivefile
              Each PCP archive consists of multiple physical files as  described  in  pmlogger(1).   This  error
              occurs when one of the physical files is missing or cannot be opened for reading.

       PM_ERR_EOLEndofPCParchive
              An  attempt is made to read past the end file of the last volume of a set of PCP archives, or past
              the end of the time window (as specified with a -T/--finish option) for a set of PCP archives.

       PM_ERR_NOTHOSTOperationrequirescontextwithhostsourceofmetrics
              Calls to pmStore(3) require a host context and are not supported for PCP archives.

              For  archives  created  with  versions  of   PCP   prior   to   4.0,   the   pmLookupText(3)   and
              pmLookupInDomText(3)  calls  will  return  this code for archive PMAPI contexts (help and one-line
              text was not previously recorded in archives).

       PM_ERR_LOGRECCorruptedrecordinaPCParchive
              PCP archives can become corrupted for a variety of reasons,  but  the  most  common  is  premature
              termination of pmlogger(1) without flushing its output buffers.

       PM_ERR_LABELIllegallabelrecordatstartofaPCParchivefile
              Each  physical  file  in a PCP archive should begin with a common label record.  This is a special
              case of PM_ERR_LOGREC errors.

       PM_ERR_NODATAEmptyarchivefile
              An empty physical file can never be part of a valid PCP archive (at least the label record  should
              be present).  This is a special case of PM_ERR_LOGREC errors.

       PM_ERR_NOTARCHIVEOperationrequirescontextwitharchivesourceofmetrics
              A  call  to  one  of  the  archive variant routines, i.e. pmFetchArchive(3), pmGetInDomArchive(3),
              pmLookupInDomArchive(3) or pmNameInDomArchive(3), when the current context is not associated  with
              a set of PCP archives.

       PM_ERR_PMID_LOGMetricnotdefinedinthePCParchive
              A  PCP  client has requested information about a metric, and there is no corresponding information
              in the set of PCP archives.  This should not happen for well-behaved PCP clients.

       PM_ERR_INDOM_LOGInstancedomainidentifiernotdefinedinthePCParchive
              A PCP client has requested information about an  instance  domain  for  one  or  more  performance
              metrics,  and  there is no corresponding information in the set of PCP archives.  If the client is
              using metric descriptors from the set of archives to identify the instance domain,  this  is  less
              likely to happen.

              Because  instance  domains  may  vary  over  time,  clients  may  need to use the variant routines
              pmGetInDomArchive(3) or pmLookupInDomArchive(3) or pmNameInDomArchive(3) to manipulate  the  union
              of the instances in an instance domain over the life of an archive.

       PM_ERR_INST_LOGInstanceidentifiernotdefinedinthePCParchive
              A  PCP  client  has  requested  information about a specific instance of a performance metric, and
              there is no corresponding information in the set of PCP archives.  If the client is using instance
              names from the instance domain in the set of archives (rather than hard-coded instance names)  and
              instance  identifiers  from  the  results returned by pmFetch(3) or pmFetchArchive(3) this is less
              likely to happen.

              Because instance domains may vary over  time,  clients  may  need  to  use  the  variant  routines
              pmLookupInDomArchive(3)  or  pmNameInDomArchive(3)  to manipulate the union of the instances in an
              instance domain over the life of an archive.

       PM_ERR_LOGOVERLAPArchivesoverlapintime
              When using a context associated with a set of archives, the archives in the set may not overlap in
              time.

       PM_ERR_LOGHOSTArchivesdifferbyhost
              When using a context associated with a set of archives, the archives in the set must all have been
              generated on the same host.

       PM_ERR_LOGCHANGETYPEThetypeofametricdiffersamongarchives
              When using a context associated with a set of archives, the type of each metric must  be  same  in
              all of the archives.

       PM_ERR_LOGCHANGESEMThesemanticsofametricdiffersamongarchives
              When  using a context associated with a set of archives, the semantics of each metric must be same
              in all of the archives.

       PM_ERR_LOGCHANGEINDOMTheinstancedomainofametricdiffersamongarchives
              When using a context associated with a set of archives, the instance domain of each metric must be
              same in all of the archives.

       PM_ERR_LOGCHANGEUNITSTheunitsofametricdiffersamongarchives
              When using a context associated with a set of archives, the units of each metric must be  same  in
              all of the archives.

       These  errors  may  occur  in  the  interactions  between  a  PCP  client and pmcd(1) providing real-time
       performance data.

       PM_ERR_NOAGENTNoPMCDagentfordomainofrequest
              A request sent to pmcd(1) requires information from an agent or PMDA that does not exist.  Usually
              this means the namespace being used by  the  client  application  contains  metric  names  from  a
              previously installed PMDA.

       PM_ERR_CONNLIMITPMCDconnectionlimitforthishostexceeded
              The  client  connection  limit  for  pmcd(1)  is  controlled  by  the  optional access controls in
              $PCP_PMCDCONF_PATH.  By default there is no limit imposed by the PCP code, and  this  error  would
              not be seen.

       PM_ERR_AGAINTryagain.Informationnotcurrentlyavailable
              Used  to  notify  a  PCP  client  that  the  PMDA  responsible  for  delivering the information is
              temporarily unavailable.  See also PM_ERR_PMDANOTREADY.

       PM_ERR_NOPROFILEMissingprofile-protocolbotch
              Internal error in the communication between a client application and pmcd(1) - should not occur.

       PM_ERR_NEEDCLIENTCERTPMCDrequiresaclientcertificate Authentication failure.

       PM_ERR_PMDAFENCEDPMDAiscurrentlyfencedandunabletorespondtorequests
              A privileged user has decided to isolate a PMDA from pmcd(1) using a pmStore(1) operation  on  the
              pmcd.agent.fenced metric, which means all fetch-level requests to that PMDA are being blocked.

       These common errors may occur in various PCP interactions.

       PM_ERR_TIMEOUTTimeoutwaitingforaresponsefromPMCD
           Many interactions between PCP applications involve synchronous message passing, and these are subject
           to  timeout constraints.  These errors are most frequently encountered when using network connections
           with slow data rates or long latencies.

           For client-pmcd timeouts, refer to PCPIntro(1) for environment variables that may be used  to  modify
           the timeout thresholds.  For pmcd-PMDA timeouts refer to the -t and -q options of pmcd(1) and the PCP
           metric pmcd.control.timeout that can be dynamically changed with pmstore(1).

       PM_ERR_APPVERSIONMetricnotsupportedbythisversionofmonitoredapplication
           Some  performance  metrics  are  unavailable from specific versions of the associated PMDA, or may be
           unavailable because the underlying instrumentation has changed or is not installed or is not enabled.
           This error is used in results from pmFetch(3) to indicate these situations.

       PM_ERR_IPCIPCprotocolfailure
           Generic protocol failure on a pipe or socket connecting two PCP applications,  e.g.  client-pmcd,  or
           client-pmtime, or PMDA-pmcd or pmlc-pmlogger.

       PM_ERR_TEXTOne-lineorhelptextisnotavailable
           Set  by  a  PMDA,  and passed back to a PCP client, to indicate that the PMDA is unable to supply the
           requested metric or instance domain help text.

       PM_ERR_VALUEMissingmetricvalue(s)
           This error is used for a number of  conditions  in  which  the  value  of  a  performance  metric  is
           inappropriate for the context in which it is being used, e.g.

           (a) Bad  value  for  the metric pmcd.timezone when trying to set the timezone via pmNewContextZone(3)
               for a remote or archive context.

           (b) Attempting to interpolate values for a metric with non-numeric  data  type  from  a  set  of  PCP
               archives.

           (c) A bad result data structure passed to pmStore(3).

       PM_ERR_NAMEUnknownmetricname
           Just what the message says.

       PM_ERR_PMIDUnknownorillegalmetricidentifier
           Just what the message says.

       PM_ERR_INDOMUnknownorillegalinstancedomainidentifier
           A  request nominates an instance domain that is unknown or PM_INDOM_NULL.  May occur as a consequence
           of the instance domain  identifier  passed  by  a  PCP  client  to  pmGetInDom(3),  pmLookupInDom(3),
           pmNameInDom(3),  pmGetInDomArchive(3),  pmLookupInDomArchive(3),  pmNameInDomArchive(3)  or a request
           passed from pmcd(1) to a PMDA.

       PM_ERR_EOFIPCchannelclosed
           End of file on a pipe or socket connecting two PCP applications, e.g. client-pmcd,  or  client-pmtime
           or PMDA-pmcd.PM_ERR_NOCONTEXTAttempttouseanillegalcontext
           Typically  caused  by  a  PCP client that tries to make calls before calling pmNewContext(3) or after
           calling pmDestroyContext(3).

       PM_ERR_PERMISSIONNopermissiontoperformrequestedoperation
           PCP-specific access controls apply to pmcd(1) and pmlogger(1).  Platform-specific  permission  errors
           are returned as -EPERM.

       PM_ERR_CONVImpossiblevalueorscaleconversion
           Some  value conversion requests are illegal, e.g. bad debug flag symbolic name for -D/--debug option,
           or asking pmExtractValue(3) to translate non-numeric data types to numbers and viceversa.

       PM_ERR_TRUNCTruncationinvalueconversion
           Some conversion requests to pmExtractValue(3) cannot be performed  based  on  the  metric  types  and
           values involved, in this case conversion would result in loss of precision.

       PM_ERR_SIGNNegativevalueinconversiontounsigned
           Some  conversion  requests  to  pmExtractValue(3)  cannot  be performed based on the metric types and
           values involved, in this case converting a negative value to an unsigned value.

       PM_ERR_TYPEUnknownorillegalmetrictype
           The metric type is held in the metric descriptor and sometimes encoded in the metric values  returned
           from  a  call to pmFetch(3).  Legal values for the metric type are defined by the PM_TYPE_* macros in
           <pcp/pmapi.h>.

       PM_ERR_UNITIllegalpmUnitsspecification
           Some conversion requests to pmConvScale(3)  cannot  be  performed  due  to  illegal  or  incompatible
           specifications of the source and destination units.

       PM_ERR_PROFILEExplicitinstanceidentifier(s)required
           Some  PMDAs, especially the proc PMDA, will not return ``all instances'' for a pmFetch(3) request due
           to the cost.  The client must explicitly built  an  instance  profile  using  pmAddProfile(3)  and/or
           pmDelProfile(3) before calling pmFetch(3).  See also the -F/--fetchall option to pminfo(1).

       PM_ERR_INSTUnknownorillegalinstanceidentifier
           A request to a PMDA nominates an instance that is unknown.  May occur as a consequence of the profile
           established   prior   to   a  pmFetch(3)  call,  or  an  explicit  instance  name  or  identifier  to
           pmLookupInDom(3) or pmNameInDom(3).

       PM_ERR_MODEIllegalmodespecification
           Illegal mode argument to pmSetMode(3).

       PM_ERR_PROFILESPECNULLpmInDomwithnon-NULLinstlist
           Bad arguments passed from a PCP client to pmAddProfile(3).

       PM_ERR_TOOSMALLInsufficientelementsinlist
           Parameter passing error by caller specifying a  list  with  less  than  one  element  to  pmFetch(3),
           pmLookupName(3) or pmStore(3).

       PM_ERR_FAULTQAfaultinjected
           For  testing,  there  is a ``fault injection'' version of libpcp and this error indicates a misuse of
           the fault injection infrastructure.

       PM_ERR_THREADOperationnotsupportedformulti-threadedapplications
           As documented in PMAPI(3) and elsewhere, some libpcp  routines  are  intended  solely  for  use  from
           single-threaded applications.

       PM_ERR_NOCONTAINERContainernotfound The user supplied container name does not match any known container.

       PM_ERR_BADSTOREBadinputtopmstore
           The  metric value provided for a pmStore(3) operation is in the wrong format, or of the wrong type or
           has the wrong number of values.

       PM_ERR_TOOBIGResultsizeexceeded
           Indicates a fatal error in the message (or PDU) passing protocol between two PCP applications.   This
           is an internal error, and other than an exotic networking failure, should not occur.

       PM_ERR_RESETPMCDresetorconfigurationchange
           Not used.

           Refer to pmFetch(3) for an alternative mechanism that may be used to notify a PCP client when pmcd(1)
           has  experienced  one  or more configuration changes since the last request from the client.  Usually
           these changes involve a change to the namespace exported via pmcd and/or changes to the  PMDAs  under
           pmcd's control.

       PM_ERR_FAULTQAfaultinjected
           Used only for PCP Quality Assurance (QA) testing.

       PM_ERR_NYIFunctionalitynotyetimplemented
           Self explanatory and rarely used.

       PM_ERR_GENERICGenericerror,alreadyreportedabove
           Rarely  used,  this  error  may  be returned when the error condition is a consequent of some earlier
           returned error and a more precise characterization is not possible.

       PM_ERR_BADDERIVEDerivedmetricdefinitionfailed
           When registering a derived metric, the metric expression  is  either  syntactically  or  semantically
           incorrect.

       PM_ERR_NOLABELSNosupportformetriclabelmetadata
           Operation requires metric labels, but none are available.

       Performance Co-Pilot (PCP) is a toolkit designed for monitoring and managing system-level performance.

       The PCP libraries support the APIs required to create new performance monitoring tools and new agents (or
       PMDAs) to export performance data.  The libpcp library is used in both cases.  The libpcp_pmda library is
       used only for PMDAs.

       Individual library routines are documented in their own manual page entries.

       Most  routines  return an integer value; greater than equal to zero for success and less than zero for an
       error.  The error codes have symbolic names defined in <pcp/pmapi.h>.  Other negative values are used  to
       encode  errors  that  can  be mapped to the traditional errno values defined in <errno.h>, with the value
       negated.  To translate all PCP error codes into useful messages use either pmerr(1) or  pmErrStr(3);  the
       latter may also be used to decode the -errno cases.

PCPIntro - introduction to the Performance Co-Pilot (PCP) libraries

       These errors may occur in the processing of PCP namespace operations.   A  PCP  namespace,  see  PMNS(5),
       provides the external names and the internal identifiers for the available performance metrics.

       PM_ERR_NONLEAFMetricnameisnotaleafinPMNS
              The metric name passed to pmLookupName(3) names a non-terminal path in the namespace, i.e. a group
              of metrics rather than a single metric.

       PM_ERR_DUPPMNSAttempttoreloadthePMNS
              When  using  an  explicit  local  namespace, it is illegal to call either of pmLoadNameSpace(3) or
              pmLoadASCIINameSpace(3) more than once.

       PM_ERR_PMNSProblemsparsingPMNSdefinitions
              Only occurs when an ASCII namespace is explicitly loaded.

       PM_ERR_NOPMNSPMNSnotaccessible
              Only occurs when an ASCII namespace is explicitly loaded.

       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(5).
       Values for these variables may be obtained programmatically using the pmGetConfig(3) function.

       These error codes are used in the interactions between pmcd(1) and the PMDAs that provide the performance
       data.

       PM_ERR_PMDANOTREADYPMDAisnotyetreadytorespondtorequests
              Some PMDAs have long initialization or reset times, and will respond to pmcd(1) with this error if
              they are busy at the moment.  This error translates to PM_ERR_AGAIN for the PCP  client  who  made
              the  request  to  pmcd  which caused the initial request to the PMDA.  At some later time the PMDA
              will inform pmcd (see PM_ERR_PMDAREADY) that it is now  ready  to  process  requests,  and  client
              requests will begin to succeed.

       PM_ERR_PMDAREADYPMDAisnowresponsivetorequests
              Used  by  PMDAs  to  asynchronously  inform pmcd(1) that they are now willing to resume processing
              requests.  See also PM_ERR_PMDANOTREADY.

PCPIntro(1), pmcd(1), pmerr(1), pminfo(1), pmtime(1), pmstore(1), pmlogger(1), PMAPI(3), pmAddProfile(3),
       pmDelProfile(3), pmConvScale(3), pmNewContext(3),  pmDestroyContext(3),  pmErrStr(3),  pmExtractValue(3),
       pmFetch(3),  pmFetchArchive(3),  pmGetConfig(3), pmGetInDom(3), pmGetInDomArchive(3), pmLoadNameSpace(3),
       pmLookupInDom(3),     pmLookupInDomText(3),     pmLookupName(3),     pmLookupText(3),     pmNameInDom(3),
       pmNameInDomArchive(3), pmSetMode(3), pmStore(3), pmTimeConnect(3), pcp.conf(5), pcp.env(5) and PMNS(5).

Performance Co-Pilot                                   PCP                                           PCPINTRO(3)

       These  errors  may  occur  in  the  interactions  between  a GUI PCP client and the time control services
       provided by pmtime(1).

       PM_ERR_ISCONNAlreadyConnected
              A PCP client application called pmTimeConnect(3) when already connected to a pmtime(1) instance.

       PM_ERR_NOTCONNNotConnected
              A PCP client application called one of the time control routines  pmTime*(3)  when  not  currently
              connected to any pmtime(1) instance.

       PM_ERR_NEEDPORTAnon-nullportnameisrequired
              If  a shared pmtime(1) instance is being created the port argument to pmTimeConnect(3) must not be
              invalid.