'\"macro stdmacro
.\"
.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
.\" 
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\" 
.\"
.TH PMGETCHILDRENSTATUS 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmGetChildrenStatus\f1 \- return the descendent nodes of a PMNS node and their respective status
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.sp
.ad l
.hy 0
.in +8n
.ti -8n
int pmGetChildrenStatus(const char *\fIname\fP, char ***\fIoffspring\fP, int\ **\fIstatus\fP);
.sp
.in
.hy
.ad
cc ... \-lpcp
.ft 1
.SH DESCRIPTION
.de CW
.ie t \f(CW\\$1\f1\\$2
.el \fI\\$1\f1\\$2
..
Given a fully qualified pathname to a node in the current Performance
Metrics Name Space (PMNS), as identified by
.IR name ,
.B pmGetChildrenStatus
returns via
.I offspring
a list of the relative names of
all of the immediate descendent nodes of
.I name
in the current PMNS.
.PP
As a
special case, if
.I name
is an empty string (i.e.\f3""\f1), the immediate descendants of
the root node in the PMNS will be returned.
.PP
If 
.IR status 
is not NULL, then 
.B pmGetChildrenStatus
will also return the status of each child via
.IR status.
The status will refer to either a leaf node (with value 
.B PMNS_LEAF_STATUS
) or a non-leaf node (with value
.B PMNS_NONLEAF_STATUS
).
.PP 
Normally,
.B pmGetChildrenStatus
will return the number of descendent names discovered, else a value
less than zero for an error.
The value zero indicates that
.I name
is a valid metric name, i.e. is associated with a leaf node in the PMNS.
.PP
The resulting list of pointers
.I offspring
.B and
the values
(the relative names) that the pointers reference will have been
allocated by
.B pmGetChildrenStatus
with a single call to
.BR malloc (3),
and it is the
responsibility of the
.B pmGetChildrenStatus
caller to
.BR free (\c
.IR offspring )
to release the space
when it is no longer required.
The same holds true for the 
.I status
array.
.PP
When an error occurs, or
.I name 
is a leaf node (i.e. the result of
.B pmGetChildrenStatus
is less than one), both
.I offspring
and
.I status
are undefined (no space will have been
allocated, and so calling
.BR free (3)
is a singularly bad idea).
.SH "PCP ENVIRONMENT"
Environment variables with the prefix
.B PCP_
are used to parameterize the file and directory names
used by PCP.
On each installation, the file
.I /etc/pcp.conf
contains the local values for these variables.
The
.B $PCP_CONF
variable may be used to specify an alternative
configuration file,
as described in
.BR pcp.conf (5).
Values for these variables may be obtained programmatically
using the
.BR pmGetConfig (3)
function.
.SH SEE ALSO
.BR PMAPI (3),
.BR pmGetChildren (3),
.BR pmGetConfig (3),
.BR pmLoadASCIINameSpace (3),
.BR pmLoadNameSpace (3),
.BR pmLookupName (3),
.BR pmNameID (3),
.BR pcp.conf (5),
.BR pcp.env (5)
and
.BR pmns (5).
.SH DIAGNOSTICS
.IP \f3PM_ERR_NOPMNS\f1
Failed to access a PMNS for operation.
Note that if the application hasn't a priori called pmLoadNameSpace(3)
and wants to use the distributed PMNS, then a call to
.B pmGetChildrenStatus
must be made inside a current context.
.IP \f3PM_ERR_NAME\f1
The pathname
.I name
is not valid in the current PMNS
.IP \f3PM_ERR_*\f1
Other diagnostics are for protocol failures when
accessing the distributed PMNS.