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

NAME

6       pmGetInDom,  pmRequestInDom,  pmReceiveIndom - get instance identifiers
7       for a performance metrics instance domain
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmGetInDom(pmInDom indom, int **instlist, char ***namelist)
13       int pmRequestInDom(int ctx, pmInDom indom)
14       int pmReceiveInDom(int ctx, int **instlist, char ***namelist)
15
16       cc ... -lpcp
17

DESCRIPTION

19       In the current Performance Metrics  Application  Programming  Interface
20       (PMAPI)  context,  locate the description of the instance domain indom,
21       and return via instlist  the  internal  instance  identifiers  for  all
22       instances,  and  via  namelist  the  full  external identifiers for all
23       instances.  The number of instances found is returned as  the  function
24       value (else less than zero to indicate an error).
25
26       The  value  for the instance domain indom is typically extracted from a
27       pmDesc structure, following a call to pmLookupDesc(3) for a  particular
28       performance metric.
29
30       The  resulting  lists  of instance identifiers (instlist and namelist),
31       and the names that the elements of namelist point to,  will  have  been
32       allocated  by  pmGetInDom  with  two calls to malloc(3C), and it is the
33       responsibility of the caller to free(instlist)  and  free(namelist)  to
34       release the space when it is no longer required.
35
36       When  the  result  of  pmGetInDom  is  less than one, both instlist and
37       namelist are undefined (no space will have been allocated, and so call‐
38       ing free(3C) is a singularly bad idea).
39
40       pmRequestInDom  and  pmReceiveInDom are used by applications which must
41       communicate with the PMCD asynchronously.  These functions take explict
42       context  handle ctx which must refer to a host context (i.e. created by
43       passing PM_CONTEXT_HOST to pmNewContext). pmRequestInDom sends  request
44       to  enumerate  all  instances in the particular instance domain to PMCD
45       and returns  without waiting for  the  response,  pmReceiveInDom  reads
46       reply  from  PMCD.  It is the responsibility of the application to make
47       sure the data are ready before calling pmReceiveInDom to  avoid  block‐
48       ing.
49

PCP ENVIRONMENT

51       Environment variables with the prefix PCP_ are used to parameterize the
52       file and directory names used by PCP.  On each installation,  the  file
53       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
54       $PCP_CONF variable may be used to specify an alternative  configuration
55       file,  as  described in pcp.conf(4).  Values for these variables may be
56       obtained programatically using the pmGetConfig(3) function.
57

SEE ALSO

59       PMAPI(3), pmGetConfig(3), pmLookupDesc(3), pmLookupInDom(3),  pmNameIn‐
60       Dom(3), pcp.conf(4) and pcp.env(4).
61

DIAGNOSTICS

63       PM_ERR_INDOM
64              indom is not a valid instance domain identifier
65
66       PM_ERR_CTXBUSY
67              Context is currently in use by another asynchronous call.
68
69
70
71Performance Co-Pilot                  SGI                        PMGETINDOM(3)