1PMLOOKUPNAME(3)            Library Functions Manual            PMLOOKUPNAME(3)
2
3
4

NAME

6       pmLookupName,  pmRequestNames,  pmReceiveNames  - translate performance
7       metric names into PMIDs
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmLookupName(int numpmid, char **namelist, pmID *pmidlist)
13       int pmRequestNames(int ctx, int numpmid, char **namelist)
14       int pmReceiveNames(int ctx, pmID *pmidlist)
15
16       cc ... -lpcp
17

DESCRIPTION

19       Given a list in namelist containing numpmid full pathnames for  perfor‐
20       mance  metrics  from a Performance Metrics Name Space (PMNS), pmLookup‐
21       Name returns the list  of  associated  Performance  Metric  Identifiers
22       (PMIDs) via pmidlist.
23
24       The  result from pmLookupName will be the number of names translated in
25       the absence of errors, else an error code less than zero.  When  errors
26       are   encountered,   the   corresponding  value  in  pmidlist  will  be
27       PM_ID_NULL.
28
29       Note that the error protocol guarantees there  is  a  1:1  relationship
30       between the elements of namelist and pmidlist, hence both lists contain
31       exactly numpmid elements.  For this reason, the caller is  expected  to
32       have pre-allocated a suitably sized array for pmidlist.
33
34       pmRequestNames  and  pmReceiveNames are used by applications which must
35       communicate with the PMCD asynchronously.  These functions take explict
36       context  handle ctx which must refer to a host context (i.e. created by
37       passing PM_CONTEXT_HOST to pmNewContext). pmRequestNames sends  request
38       to translate names to PMIDs to PMCD and returns without waiting for the
39       response, pmReceiveNames reads reply from PMCD. It is the  responsibil‐
40       ity  of  the application to make sure the data are ready before calling
41       pmReceiveNames to avoid blocking.
42

SEE ALSO

44       PMAPI(3),  pmGetChildren(3),  pmGetChildrenStatus(3),   pmGetConfig(3),
45       pmLoadNameSpace(3),   pmNameID(3),   pmNewContext(3),  pcp.conf(4)  and
46       pcp.env(4).
47

DIAGNOSTICS

49       PM_ERR_TOOSMALL
50              numpmid must be at least 1
51
52       PM_ERR_NOPMNS
53              Failed to access a PMNS for operation.  Note that if the  appli‐
54              cation  hasn't  a  priori called pmLoadNameSpace(3) and wants to
55              use the distributed PMNS, then a call to  pmLookupName  must  be
56              made after the creation of a context (see pmNewContext(3)).
57
58       PM_ERR_NAME
59              One or more of the elements of namelist does not correspond to a
60              valid metric name in the PMNS.
61
62       PM_ERR_NONLEAF
63              A name referred to a node in the PMNS but  it  was  not  a  leaf
64              node.
65
66       PM_ERR_*
67              Other  diagnostics  are for protocol failures when accessing the
68              distributed PMNS.
69
70       PM_ERR_CTXBUSY
71              Context is currently in use by another asynchronous call.
72
73
74
75Performance Co-Pilot                  SGI                      PMLOOKUPNAME(3)