--- name: "pmstore" section: "1" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pmstore" --- # pmstore(1) modify performance metric values ## NAME **pmstore** - modify performance metric values ## SYNOPSIS **pmstore** \[**-fFLV?**\] \[**-D** *debug*\] \[**-h** *host*\] \[**-i** *instances*\] \[**-K** *spec*\] \[**-n** *pmnsfile*\] *metricname* *value* ## DESCRIPTION Under certain circumstances, it is useful to be able to modify the values of performance metrics, for example to re-initialize counters or to assign new values to metrics that act as control variables. **pmstore** changes the current values for the nominated instances of a single performance metric, as identified by *metricname* and the list of instance identifiers following the **-i** argument. *instances* must be a single argument, with elements of the list separated by commas and/or white space. By default all instances of *metricname* will be updated. Normally **pmstore** operates on the default Performance Metrics Name Space (PMNS), see [**PMNS**(5)](/PMNS/5.md), however if the **-n** option is specified an alternative namespace is loaded from the file *pmnsfile*. Unless directed to another host by the **-h** option, **pmstore** will interact with the Performance Metric Collector Daemon (PMCD) on the local host. The **-L** option causes **pmstore** to use a local context to store to metrics from PMDAs on the local host without PMCD. Only some metrics are available in this mode. The **-h** and **-L** options are mutually exclusive. The **-f** option forces the given value to be stored, even if there is no current value set. The interpretation of *value* is dependent on the syntax used in its specification and the underlying data type of *metricname*, as follows. - 1\. If the metric has an **integer** type, then *value* should be an optional leading hyphen, followed either by decimal digits or \`\`0x'' and some hexadecimal digits. \`\`0X'' is also acceptable in lieu of \`\`0x''. See [**strtol**(3)](/strtol/3.md) and the related routines. - 2\. If the metric has a **floating point** type, then *value* should be either in the form of an integer described above, or a fixed point number, or a number in scientific notation. See [**strtod**(3)](/strtod/3.md). - 3\. If the metric has a **string** type, then *value* is interpreted as a literal string of ASCII characters. - 4\. If the metric has any other type (i.e. **PM\_TYPE\_EVENT** or **PM\_TYPE\_AGGREGATE**) then no encoding of *value* from the command line makes sense, and the values of these metrics cannot be modified with **pmstore**. The output reports the old value and the new value for each updated instance of the requested metric. When using the **-L** option to fetch metrics from a local context, the **-K** option may be used to control the DSO PMDAs that should be made accessible. The *spec* argument conforms to the syntax described in [**pmSpecLocalPMDA**(3)](/pmSpecLocalPMDA/3.md). More than one **-K** option may be used. Normally **pmstore** will report the old value (as initially retrieved using [**pmFetch**(3)](/pmFetch/3.md)) and the new value from the command line. The **-F** option forces another [**pmFetch**(3)](/pmFetch/3.md) after the [**pmStore**(3)](/pmStore/3.md) and the returned value is reported as the new value. This is useful in cases where *metricname* is a metric that provides different semantics for the store operation, e.g. to increment the current value or reset a counter (independent of the *value* from the command line). ## OPTIONS The available command line options are: - **-f**, **--force** Store the value even if no current value set. - **-F**, **--fetch** Report the metric value after setting it. - **-i** *insts*, **--insts**=*insts* Restrict store to the comma-separated list of instances. - **-h** *host*, **--host**=*host* Connect to [**pmcd**(1)](/pmcd/1.md) on *host*, rather than on the default localhost. - **-K** *spec*, **--spec-local**=*spec* When fetching metrics from a local context (see **-L**), the **-K** option may be used to control the DSO PMDAs that should be made accessible. The *spec* argument conforms to the syntax described in [**pmSpecLocalPMDA**(3)](/pmSpecLocalPMDA/3.md). More than one **-K** option may be used. - **-L**, **--local-PMDA** Use a local context to collect metrics from DSO PMDAs on the local host without PMCD. See also **-K**. - **-n** *pmnsfile*, **--namespace**=*pmnsfile* Normally **pmcd** loads the default Performance Metrics Name Space (PMNS) from **$PCP\_VAR\_DIR/pmns/root**, however if the **-n** option is specified an alternative namespace is loaded from the file *pmnsfile*. - **-V**, **--version** Display version number and exit. - **-?**, **--help** Display usage message and exit. ## DIAGNOSTICS Two messages indicate a mismatch between the internal data type for *metricname* and the *value* provided. The value "???" is out of range for the data type (PM\_TYPE\_...) The value "???" is incompatible with the data type (PM\_TYPE\_...) ## 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**(5)](/pcp.conf/5.md). ## DEBUGGING OPTIONS The **-D** or **--debug** option enables the output of additional diagnostics on *stderr* to help triage problems, although the information is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users. *debug* is a comma separated list of debugging options; use [**pmdbg**(1)](/pmdbg/1.md) with the **-l** option to obtain a list of the available debugging options and their meaning. ## SEE ALSO [**pmcd**(1)](/pmcd/1.md), [**pminfo**(1)](/pminfo/1.md), [**pmval**(1)](/pmval/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmFetch**(3)](/pmFetch/3.md), [**pmSpecLocalPMDA**(3)](/pmSpecLocalPMDA/3.md), [**pmStore**(3)](/pmStore/3.md), [**strtod**(3)](/strtod/3.md), [**strtol**(3)](/strtol/3.md) and [**PMNS**(5)](/PMNS/5.md).