diff options
Diffstat (limited to 'man/man3/pmlookupname.3')
-rw-r--r-- | man/man3/pmlookupname.3 | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/man/man3/pmlookupname.3 b/man/man3/pmlookupname.3 new file mode 100644 index 0000000..342c21e --- /dev/null +++ b/man/man3/pmlookupname.3 @@ -0,0 +1,93 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2000 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 PMLOOKUPNAME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmLookupName\f1 \- translate performance metric names into PMIDs +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.nf +int pmLookupName(int \fInumpmid\fP, char **\fInamelist\fP, pmID *\fIpmidlist\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +.PP +Given a list in +.I namelist +containing +.I numpmid +full pathnames for performance metrics from a Performance Metrics Name +Space (PMNS), +.B pmLookupName +returns the list of associated +Performance Metric Identifiers (PMIDs) via +.IR pmidlist . +.PP +The result from +.B pmLookupName +will be the number of names translated in the absence of errors, else +an error code less than zero. +When errors are encountered, the corresponding value in +.I pmidlist +will be PM_ID_NULL. +.PP +Note that the error protocol guarantees there is a 1:1 relationship +between the elements of +.I namelist +and +.IR pmidlist , +hence both lists contain exactly +.I numpmid +elements. +For this reason, the caller is expected to have pre-allocated a suitably +sized array for +.IR pmidlist . +.SH SEE ALSO +.BR PMAPI (3), +.BR pmGetChildren (3), +.BR pmGetChildrenStatus (3), +.BR pmGetConfig (3), +.BR pmLoadNameSpace (3), +.BR pmNameID (3), +.BR pmNewContext (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). +.SH DIAGNOSTICS +.IP \f3PM_ERR_TOOSMALL\f1 +.I numpmid +must be at least 1 +.IP \f3PM_ERR_NOPMNS\f1 +Failed to access a PMNS for operation. +Note that if the application hasn't a priori called +.BR pmLoadNameSpace (3) +and wants to use the distributed PMNS, then a call to +.B pmLookupName +must be made after the creation of a context (see +.BR pmNewContext (3)). +.IP \f3PM_ERR_NAME\f1 +One or more of the elements of +.I namelist +does not correspond to a valid metric name in the PMNS. +.IP \f3PM_ERR_NONLEAF\f1 +A name referred to a node in the PMNS but it was +not a leaf node. +.IP \f3PM_ERR_*\f1 +Other diagnostics are for protocol failures when +accessing the distributed PMNS. |