Provided by: pcp_3.5.11_amd64 bug

NAME

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

INTRODUCTION

       Performance  Co-Pilot (PCP) is an SGI product 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.

GENERAL ERRORS

       These common errors may occur in various PCP interactions.

       PM_ERR_TIMEOUT
           Timeout waiting for a response from PMCD
           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_APPVERSION
           Metric not supported by this version of monitored application
           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_LICENSE
           Current PCP license does not permit this operation
           Some  pmcd(1)  services  require  a  valid  PCP Collector license, and some PCP client
           applications require a valid PCP Monitor license.  The open source version of  pmcd(1)
           does not require any licenses at all.

       PM_ERR_IPC
           IPC protocol failure
           Generic  protocol  failure  on  a  pipe or socket connecting two PCP applications, eg.
           client-pmcd, or client-pmtime, or PMDA-pmcd or pmlc-pmlogger.

       PM_ERR_TEXT
           Oneline or help text is not available
           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_VALUE
           Missing metric value(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, eg.

           (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
               PCP archive.

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

       PM_ERR_FILE
           Cannot locate a file
           Generic error when a named file is expected to already exist.

       PM_ERR_NAME
           Unknown metric name
           Just what the message says.

       PM_ERR_PMID
           Unknown or illegal metric identifier
           Just what the message says.

       PM_ERR_INDOM
           Unknown or illegal instance domain identifier
           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_EOF
           IPC channel closed
           End of file on a pipe or socket connecting two PCP applications, eg.  client-pmcd,  or
           client-pmtime or PMDA-pmcd.

       PM_ERR_NOCONTEXT
           Attempt to use an illegal context
           Typically   caused   by  a  PCP  client  that  tries  to  make  calls  before  calling
           pmNewContext(3) or after calling pmDestroyContext(3).

       PM_ERR_PERMISSION
           No permission to perform requested operation
           PCP-specific access controls apply  to  pmcd(1)  and  pmlogger(1).   Platform-specific
           permission errors are returned as -EPERM.

       PM_ERR_CONV
           Impossible value or scale conversion
           Some  value  conversion  requests are illegal, eg. bad debug flag symbolic name for -D
           option, or asking pmExtractValue(3) to translate non-numeric data types to numbers and
           vice versa.

       PM_ERR_TRUNC
           Truncation in value conversion
           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_SIGN
           Negative value in conversion to unsigned
           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_UNIT
           Illegal pmUnits specification
           Some conversion requests to pmConvScale(3) cannot  be  performed  due  to  illegal  or
           incompatible specifications of the source and destination units.

       PM_ERR_PROFILE
           Explicit instance identifier(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 option to pminfo(1).

       PM_ERR_MODE
           Illegal mode specification
           Illegal mode argument to pmSetMode(3).

       PM_ERR_PROFILESPEC
           NULL pmInDom with non-NULL instlist
           Bad arguments passed from a PCP client to pmAddProfile(3).

       PM_ERR_OBJSTYLE
           Caller does not match object style of running kernel
           In some cases, a PCP application must be build with the same object code style as  the
           booted  kernel because direct access to kernel data structures may be required.  These
           cases are a client using PM_CONTEXT_LOCAL, or pmcd(1), or a DSO-style PMDA to be  used
           by pmcd.

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

       PM_ERR_TOOBIG
           Result size exceeded
           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_RESET
           PMCD reset or configuration change
           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_NOASCII
           ASCII format not supported for this PDU
           The  ASCII  mode  PDU  support  is  intended  for  use  only  between pmcd and a PMDA.
           Consequently not all of the possible PDU types include encode and decode  support  for
           ASCII PDUs.

       PM_ERR_NYI
           Functionality not yet implemented
           Self explanatory and rarely used.

       PM_ERR_GENERIC
           Generic error, already reported above
           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.

CLIENT-PMCD ERRORS

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

       PM_ERR_INST
              Unknown or illegal instance identifier
              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_NOAGENT
              No PMCD agent for domain of request
              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_CONNLIMIT
              PMCD connection limit for this host exceeded
              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_AGAIN
              Try again. Information not currently available
              Used  to  notify  a  PCP  client  that  the  PMDA  responsible  for  delivering the
              information is temporarily unavailable.  See also PM_ERR_PMDANOTREADY.

       PM_ERR_PMCDLICENSE
              PMCD is not licensed to accept client connections
              If pmcd(1) is running without a valid PCP Collector  License,  then  it  will  only
              accept  connections  from ``authorized'' PCP clients like pminfo(1) or pmlogger(1).
              This error occurs when an  unauthorized  PCP  client  attempts  to  connect  to  an
              unlicensed pmcd(1).

       PM_ERR_NOPROFILE
              Missing profile - protocol botch
              Internal  error  in  the  communication  between a client application and pmcd(1) -
              should not occur.

CLIENT-ARCHIVE ERRORS

       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_EOL
              End of PCP archive log
              An  attempt  is made to read past the end file of the last volume of a PCP archive,
              or past the end of the time window (as specified  with  a  -T  option)  for  a  PCP
              archive.

       PM_ERR_NOTHOST
              Operation requires context with host source of metrics
              Operations  involving  help  text (ie. pmLookupText(3) and pmLookupInDomText(3)) or
              calls to pmStore(3) require a host context and are not supported for PCP archives.

       PM_ERR_LOGREC
              Corrupted record in a PCP archive log
              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_LABEL
              Illegal label record at start of a PCP archive log file
              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_NODATA
              Empty archive log file
              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_NOTARCHIVE
              Operation requires context with archive source of metrics
              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 PCP archive.

       PM_ERR_PMID_LOG
              Metric not defined in the PCP archive log
              A   PCP  client  has  requested  information  about  a  metric,  and  there  is  no
              corresponding information in the PCP archive.  This should  not  happen  for  well-
              behaved PCP clients.

       PM_ERR_INDOM_LOG
              Instance domain identifier not defined in the PCP archive log
              A  PCP  client  has  requested information about an instance domain for one or more
              performance metrics, and there is no corresponding information in the PCP  archive.
              If the client is using metric descriptors from the archive 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_LOG
              Instance identifier not defined in the PCP archive log
              A  PCP  client has requested information about a specific instance of a performance
              metric, and there is no corresponding information  in  the  PCP  archive.   If  the
              client is using instance names from the instance domain in the archive (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.

TIME CONTROL ERRORS

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

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

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

       PM_ERR_NEEDPORT
              A non-null port name is required
              If  a  shared  pmtime(1)  instance  is  being  created   the   port   argument   to
              pmTimeConnect(3) must not be invalid.

       PM_ERR_WANTACK
              Cannot send due to pending acknowledgements
              Some  client  of  pmtime(1)  is not acknowledging messages from pmtime, and this is
              causing other clients to be blocked.

NAMESPACE ERRORS

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

       PM_ERR_NONLEAF
              Metric name is not a leaf in PMNS
              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_DUPPMNS
              Attempt to reload the PMNS
              When  using  an  explicit  local  namespace,  it  is  illegal  to  call  either  of
              pmLoadNameSpace(3) or pmLoadASCIINameSpace(3) more than once.

       PM_ERR_PMNS
              Problems parsing PMNS definitions
              Only occurs when an ASCII namespace is loaded.  As of PCP 2.0 this error is  mostly
              confined  to  pmnscomp(1)  and client applications that use an uncompiled namespace
              file with a -n option.

       PM_ERR_NOPMNS
              PMNS not accessible
              Only occurs when an ASCII namespace is loaded.  As of PCP 2.0 this error is  mostly
              confined  to  pmnscomp(1)  and client applications that use an uncompiled namespace
              file with a -n option.

PMCD-PMDA ERRORS

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

       PM_ERR_PMDANOTREADY
              PMDA is not yet ready to respond to requests
              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_PMDAREADY
              PMDA is now responsive to requests
              Used by PMDAs to asynchronously inform pmcd(1) that they are now willing to  resume
              processing requests.  See also PM_ERR_PMDANOTREADY.

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

       pmerr(1), PMAPI(3), pmErrStr(3), pmGetConfig(3), pcp.conf(4) and pcp.env(4).