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

# pmGetChildren(3)

return the descendent nodes of a PMNS node

## NAME

**pmGetChildren** - return the descendent nodes of a PMNS node

## C SYNOPSIS

**#include \<pcp/pmapi.h\>**

**int pmGetChildren(const char \****name***, char \*\*\****offspring***);**

**cc ... -lpcp**

## DESCRIPTION

Given a fully qualified pathname to a node in the current Performance Metrics Name Space (PMNS), as identified by *name*, **pmGetChildren** returns via *offspring* a list of the relative names of all of the immediate descendent nodes of *name* in the current PMNS.

As a special case, if *name* is an empty string (i.e.**""**), the immediate descendants of the root node in the PMNS will be returned.

Normally, **pmGetChildren** will return the number of descendent names discovered, else a value less than zero for an error. The value zero indicates that *name* is a valid metric name, i.e. is associated with a leaf node in the PMNS.

The resulting list of pointers *offspring* **and** the values (the relative names) that the pointers reference will have been allocated by **pmGetChildren** with a single call to [**malloc**(3)](/malloc/3.md), and it is the responsibility of the **pmGetChildren** caller to **free**( *offspring*) to release the space when it is no longer required.

When an error occurs, or *name* is a leaf node (i.e. the result of **pmGetChildren** is less than one), *offspring* is undefined (no space will have been allocated, and so calling [**free**(3)](/free/3.md) is a singularly bad idea).

## DIAGNOSTICS

- **PM\_ERR\_NOPMNS**

  Failed to access a PMNS for operation. Note that if the application hasn't a priori called [pmLoadNameSpace(3)](/pmLoadNameSpace/3.md) and wants to use the distributed PMNS, then a call to **pmGetChildren** must be made inside a current context.

- **PM\_ERR\_NAME**

  The pathname *name* is not valid in the current PMNS

- **PM\_ERR\_\***

  Other diagnostics are for protocol failures when accessing the distributed PMNS.

## 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). Values for these variables may be obtained programmatically using the [**pmGetConfig**(3)](/pmGetConfig/3.md) function.

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md), [**pmGetChildrenStatus**(3)](/pmGetChildrenStatus/3.md), [**pmGetConfig**(3)](/pmGetConfig/3.md), [**pmLoadASCIINameSpace**(3)](/pmLoadASCIINameSpace/3.md), [**pmLoadNameSpace**(3)](/pmLoadNameSpace/3.md), [**pmLookupName**(3)](/pmLookupName/3.md), [**pmNameID**(3)](/pmNameID/3.md), [**pcp.conf**(5)](/pcp.conf/5.md), [**pcp.env**(5)](/pcp.env/5.md) and [**PMNS**(5)](/PMNS/5.md).