---
name: "pmReceiveNamesOfChildren"
section: "3"
platform: "linux"
package: "libpcp3-dev"
version: "3.3.3-squeeze3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/pmGetChildren"
---

# pmReceiveNamesOfChildren(3)

return the descendent nodes of a PMNS node

Part of [pmGetChildren(3)](/pmGetChildren/3.md).

## NAME

**pmGetChildren**, **pmRequestNamesOfChildren**, **pmReceiveNamesOfChildren** - return the descendent nodes of a PMNS node

## C SYNOPSIS

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

```
int pmGetChildren(const char *name, char ***offspring)
int pmRequestNamesOfChildren(int ctx, const char *name, int wantstatus)
int pmReceiveNamesOfChildren(int ctx, 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*, **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 descendents 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**(3C), 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**(3C) is a singularly bad idea).

**pmRequestNamesOfChildren** and **pmReceiveNamesOfChildren** are used by applications which must  communicate with the PMCD asynchronously. These functions take explict context handle *ctx* which must refer to a host context (i.e. created by passing **PM\_CONTEXT\_HOST** to **pmNewContext**). **pmRequestNamesOfChildren** sends request to PMCD to enumerate names of the children of PMNS node and returns without  waiting for the response, **pmReceiveNamesOfChildren** reads reply from PMCD. It is the responsibility of the application to make sure the data are ready before calling **pmReceiveNamesOfChildren** to avoid blocking.

If in the call to **pmRequestNamesOfChildren** *wantstatus* was set to non-zero value then **pmReceiveNamesOfChildren** will 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**), otherwise the *status* is undefined and should not be referenced.

## 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**(4)](/pcp.conf/4.md). Values for these variables may be obtained programatically 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**(4)](/pcp.conf/4.md), [**pcp.env**(4)](/pcp.env/4.md) and [**pmns**(4)](/pmns/4.md).

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

- **PM\_ERR\_CTXBUSY**

  Context is currently in use by another asynchronous call.