pmlookupname(3)
NAME
pmLookupName - translate performance metric names into PMIDs
C SYNOPSIS
#include <pcp/pmapi.h> int pmLookupName(int numpmid, char **namelist, pmID *pmidlist); cc ... -lpcp
DESCRIPTION
Given a list in namelist containing numpmid full pathnames for
performance metrics from a Performance Metrics Name Space (PMNS),
pmLookupName returns the list of associated Performance Metric
Identifiers (PMIDs) via pmidlist.
The result from pmLookupName depends on the presence of any lookup
failures, their severity and the number of metrics being looked up.
1. If there are no lookup failures, the return value will be numpmid.
2. If a fatal error is encountered, the return value will be less than
0. For example PM_ERR_TOOSMALL, PM_ERR_NOPMNS or PM_ERR_IPC.
3. If numpmid is greater than one and non-fatal error(s) are
encountered, the return value is the number of metric names that
have successfully been looked up (greater than or equal to zero and
less than or equal to numpmid).
4. If numpmid is one and a non-fatal error is encountered, the return
value is the error code (less than zero).
When errors are encountered, any metrics that cannot be looked up
result in the corresponding element of pmidlist being set to
PM_ID_NULL.
The slightly convoluted error protocol allows bulk lookups, then
probing for more error details in the case of a specific failure, as
shown in the EXAMPLES section below.
Note that the error protocol guarantees there is a 1:1 relationship
between the elements of namelist and pmidlist, hence both lists contain
exactly numpmid elements. For this reason, the caller is expected to
have pre-allocated a suitably sized array for pmidlist.
EXAMPLE
#include <pcp/pmapi.h>
#define NUMPMID 5
char *names[] = { "sample.bin",
"sample",
"sample.bog",
"sample.secret.bar",
"sample.secret.bar.bad"
};
pmID pmids[NUMPMID];
int
main(int argc, char **argv)
{
int sts;
int numpmid = NUMPMID;
pmNewContext(PM_CONTEXT_HOST, "local:");
sts = pmLookupName(numpmid, names, pmids);
if (sts < 0) {
fprintf(stderr, "pmLookupName failed: %s0, pmErrStr(sts));
exit(1);
}
if (sts != numpmid) {
/*
* some of the lookups failed ... report the reason(s)
*/
int i;
for (i = 0; i < numpmid; i++) {
if (pmids[i] != PM_ID_NULL) continue;
/* this one failed */
sts = pmLookupName(1, &names[i], &pmids[i]);
fprintf(stderr, "%s: lookup failed: %s0, names[i], pmErrStr(sts));
}
exit(1);
}
/* all good ... */
...
}
SEE ALSO
PMAPI(3), pmGetChildren(3), pmGetChildrenStatus(3), pmGetConfig(3), pmLoadNameSpace(3), pmNameID(3), pmNewContext(3), pcp.conf(5) and pcp.env(5).
DIAGNOSTICS
PM_ERR_TOOSMALL
numpmid must be at least 1
PM_ERR_NOPMNS
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 pmLookupName must be
made after the creation of a context (see pmNewContext(3)).
PM_ERR_NAME
namelist[0] does not correspond to a valid metric name in the
PMNS.
PM_ERR_NONLEAF
namelist[0] refers to a node in the PMNS but it was not a leaf
node.
PM_ERR_*
Other diagnostics are for protocol failures when accessing the
distributed PMNS.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
