diff options
Diffstat (limited to 'man/man3/pmgetchildrenstatus.3')
-rw-r--r-- | man/man3/pmgetchildrenstatus.3 | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/man/man3/pmgetchildrenstatus.3 b/man/man3/pmgetchildrenstatus.3 new file mode 100644 index 0000000..155d6d0 --- /dev/null +++ b/man/man3/pmgetchildrenstatus.3 @@ -0,0 +1,152 @@ +'\"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 (3C), +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 (3C) +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. |