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

# pmGetChildrenStatus(3)

return the descendent nodes of a PMNS node and their respective status

## NAME

**pmGetChildrenStatus** - return the descendent nodes of a PMNS node and their respective status

## C SYNOPSIS

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

**int pmGetChildrenStatus(const char \****name***,** **char \*\*\****offspring***,** **int \*\****status***);**

**cc ... -lpcp**

## DESCRIPTION

Given a fully qualified pathname to a node in the current Performance Metrics Name Space (PMNS), as identified by *name*, **pmGetChildrenStatus** 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.

If *status* is not NULL, then **pmGetChildrenStatus** will also return the status of each child via *status.* The status will refer to either a leaf node (with value **PMNS\_LEAF\_STATUS**) or a non-leaf node (with value **PMNS\_NONLEAF\_STATUS**).

Normally, **pmGetChildrenStatus** 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 **pmGetChildrenStatus** with a single call to [**malloc**(3)](/malloc/3.md), and it is the responsibility of the **pmGetChildrenStatus** caller to **free**( *offspring*) to release the space when it is no longer required. The same holds true for the *status* array.

When an error occurs, or *name* is a leaf node (i.e. the result of **pmGetChildrenStatus** is less than one), both *offspring* and *status* are 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 **pmGetChildrenStatus** 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), [**pmGetChildren**(3)](/pmGetChildren/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).