diff options
Diffstat (limited to 'man/man3/pmgetchildren.3')
-rw-r--r-- | man/man3/pmgetchildren.3 | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/man/man3/pmgetchildren.3 b/man/man3/pmgetchildren.3 new file mode 100644 index 0000000..a2518e4 --- /dev/null +++ b/man/man3/pmgetchildren.3 @@ -0,0 +1,130 @@ +'\"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 PMGETCHILDREN 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetChildren\f1 \- return the descendent nodes of a PMNS node +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmGetChildren(const char *\fIname\fP, char ***\fIoffspring\fP); +.fi +.sp +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 pmGetChildren +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 +Normally, +.B pmGetChildren +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 pmGetChildren +with a single call to +.BR malloc (3C), +and it is the +responsibility of the +.B pmGetChildren +caller to +.BR free (\c +.IR offspring ) +to release the space +when it is no longer required. +.PP +When an error occurs, or +.I name +is a leaf node (i.e. the result of +.B pmGetChildren +is less than one), +.I offspring +is 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 pmGetChildrenStatus (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 pmGetChildren +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. |