---

   pcpintro    ( 3 )

---

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_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 One-line 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 set of PCP archives.

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

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/--debug 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_TYPE Unknown or illegal metric type 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_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/--fetchall option to pminfo(1).

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_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_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_FAULT QA fault injected For testing, there is a ``fault injection'' version of libpcp and this error indicates a misuse of the fault injection infrastructure.

PM_ERR_THREAD Operation not supported for multi-threaded applications As documented in PMAPI(3) and elsewhere, some libpcp routines are intended solely for use from single-threaded applications.

PM_ERR_NOCONTAINER Container not found The user supplied container name does not match any known container.

PM_ERR_BADSTORE Bad input to pmstore 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_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_FAULT QA fault injected Used only for PCP Quality Assurance (QA) testing.

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.

PM_ERR_BADDERIVE Derived metric definition failed When registering a derived metric, the metric expression is either syntactically or semantically incorrect.

PM_ERR_NOLABELS No support for metric label metadata Operation requires metric labels, but none are available.