---
name: "newhelp"
section: "1"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/newhelp"
---

# newhelp(1)

generate a performance metrics help database

## NAME

**newhelp** - generate a performance metrics help database

## SYNOPSIS

**$PCP\_BINADM\_DIR/newhelp** \[**-SvV?**\] \[**-D** *debug*\] \[**-n** *pmnsfile*\] \[**-o** *outputfile*\] \[*file* ...\]

## DESCRIPTION

**newhelp** generates the Performance Co-Pilot help text files used by Performance Metric Domain Agents (PMDAs).

Normally **newhelp** operates on the default Performance Metrics Name Space (PMNS), however if the **-n** option is specified an alternative namespace is loaded from the file *pmnsfile*.

When there is only one input file, the base name of the new database is derived from the name of the input *file*, otherwise the **-o** flag must be given to explicitly name the database. If no input files are supplied, **newhelp** reads from the standard input stream, in which case the **-o** flag must be given.

In the normal mode of operation, if the output file name is determined to be **foo**, **newhelp** will create **foo.dir** and **foo.pag**. When the **-S** (**--search**) option is given, no **.dir** or **.pag** files are created; instead the name given with the **-o** option directly names the SQLite FTS5 database file used by [**pmsearch**(1)](/pmsearch/1.md).

The **-V** flag causes verbose messages to be printed while **newhelp** is parsing its input.

The first line of each entry in a help source file consists of an \`\`@'' character beginning the line followed by a space and then the performance metric name and a one line description of the metric. Following lines (up to the next line beginning with \`\`@'' or end of file) may contain a verbose help description. E.g.

```
#
# This is an example of newhelp's input syntax
#
@ kernel.all.cpu.idle CPU idle time
A cumulative count of the number of milliseconds
of CPU idle time, summed over all processors.
```

Three-part numeric metric identifiers (PMIDs) may be used in place of metric names, e.g. `60.0.23` rather than `kernel.all.cpu.idle` in the example above. Other than for dynamic metrics (where the existence of a metric is known to a PMDA, but not visible in the PMNS and hence has no name that could be known to *newhelp*) use of this syntactic variant is not encouraged.

Lines beginning with \`\`#'' are ignored, as are blank lines in the file before the first \`\`@''. The verbose help text is optional.

As a special case, a \`\`metric'' name of the form *NNN.MM* (for numeric *NNN* and *MM*) is interpreted as an instance domain identification, and the text describes the instance domain.

## OPTIONS

The available command line options are:

- **-o** *output*, **--output**=*outout*

  Specify base name for *output* files.

- **-n** *pmnsfile*, **--namespace**=*pmnsfile*

  Load an alternative Performance Metrics Name Space ([**PMNS**(5)](/PMNS/5.md)) from the file *pmnsfile*.

- **-S**, **--search**

  Build a search index rather than the usual help text database. In this mode the output file (which must be named with the **-o** option) is a SQLite FTS5 database used by [**pmsearch**(1)](/pmsearch/1.md).

- **-v** *version*, **--version**=*version*

  Set output version. This options is deprecated, the only supported value is **2**.

- **-V**, **--verbose**

  Print verbose output.

- **-?**, **--help**

  Display usage message and exit.

## FILES

- *$PCP\_VAR\_DIR/pmns/\**

  default PMNS specification files

## 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).

For environment variables affecting PCP tools, see [**pmGetOptions**(3)](/pmGetOptions/3.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

[**chkhelp**(1)](/chkhelp/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmLookupInDomText**(3)](/pmLookupInDomText/3.md), [**pmLookupText**(3)](/pmLookupText/3.md), [**pcp.conf**(5)](/pcp.conf/5.md), [**pcp.env**(5)](/pcp.env/5.md) and [**PMNS**(5)](/PMNS/5.md).