1PMNEWCONTEXT(3) Library Functions Manual PMNEWCONTEXT(3)
2
6 pmNewContext - establish a new PMAPI context
7
9 #include <pcp/pmapi.h>
10 int pmNewContext(int type, const char *name)
12 cc ... -lpcp
14
16 An application using the Performance Metrics Application Programming
17 Interface (PMAPI) may manipulate several concurrent contexts, each
18 associated with a source of performance metrics, e.g. pmcd(1) on some
19 host, or an archive log of performance metrics as created by pmlog‐
20 ger(1), or a standalone connection on the local host that does not
21 involve pmcd(1).
22 pmNewContext may be used to establish a new context. The source of the
24 metrics is identified by name, and may be either a host name (type is
25 PM_CONTEXT_HOST), or the base name for the files of an archive log
26 (typeis PM_CONTEXT_ARCHIVE). In the latter case, name may also be the
27 name of any component file of an archive, e.g. the base name with the
28 suffix .index, .meta, .0, etc.
29 In the case where type is PM_CONTEXT_LOCAL, name is ignored, and the
31 context uses a standalone connection to the PMDA methods used by
32 pmcd(1). When this type of context is used, the range of accessible
33 performance metrics is constrained to those from the operating system,
34 and optionally the ``proc'', ``sample'' and ``ib'' PMDAs.
35 In the case where type is PM_CONTEXT_HOST, additional flags can be
37 added to the type to indicate if the connection to pmcd(1) should be
38 deferred (PM_CTXFLAG_SHALLOW) and if the file descriptor, used to com‐
39 municate with pmcd(1), should not be shared across contexts
40 (PM_CTXFLAG_EXCLUSIVE).
41 The initial instance profile is set up to select all instances in all
43 instance domains. In the case of an archive, the initial collection
44 time is also set to zero, so that an initial pmFetch(3) will result in
45 the earliest set of metrics being returned from the archive.
46 Once established, the association between a context and a source of
48 metrics is fixed for the life of the context, however routines are pro‐
49 vided to independently manipulate both the instance profile (see pmAd‐
50 dProfile(3) and pmDelProfile(3)) and the collection time for archives
51 (see pmSetMode(3)).
52 pmNewContext returns a handle that may be used with subsequent calls to
54 pmUseContext(3).
55 The new context remains the current PMAPI context for all subsequent
57 calls across the PMAPI, until another call to pmNewContext(3) is made,
58 or the context is explicitly changed with a call to pmDupContext(3) or
59 pmUseContext(3), or destroyed using pmDestroyContext(3).
60 When attempting to connect to a remote pmcd(1) on a machine that is
62 booting, pmNewContext could potentially block for a long time until the
63 remote machine finishes its initialization. pmNewContext will abort
64 and return an error if the connection has not been established after
65 some specified interval has elapsed. The default interval is 5 sec‐
66 onds. This may be modified by setting PMCD_CONNECT_TIMEOUT in the
67 environment to a real number of seconds for the desired timeout. This
68 is most useful in cases where the remote host is at the end of a slow
69 network, requiring longer latencies to establish the connection cor‐
70 rectly.
71
73 PMCD_CONNECT_TIMEOUT
74 Timeout period (in seconds) for pmcd(1) connection attempts.
75 PMCD_PORT
77 TCP/IP port(s) for connecting to pmcd(1), historically was 4321
78 and more recently the officially registered port 44321; in the
79 current release, pmcd listens on both these ports as a transi‐
80 tional arrangement. If used, should be set to a comma-separated
81 list of numerical port numbers.
82 PMDA_PATH
84 When searching for PMDAs to be loaded when type is PM_CON‐
85 TEXT_LOCAL, the PMDA_PATH environment variable may be used to
86 define a search path of directories to be used to locate the
87 PMDA executables. The default search path is
88 $PCP_SHARE_DIR/lib:/usr/pcp/lib.
89
91 When using a type of PM_CONTEXT_LOCAL, the operating system PMDA may
92 export data structures directly from the kernel, which means that the
93 pmNewContext caller should be an executable program compiled for the
94 same object code format as the booted IRIX kernel.
95 Applications that use gethostbyname(3N) should exercise caution because
97 the static fields in struct hostent may not be preserved across some
98 PMAPI(4) calls. In particular, pmNewContext(3) and pmReconnectCon‐
99 text(3) both may call gethostbyname(3N) internally.
100
102 pmAddProfile(3), PMAPI(3), pmDelProfile(3), pmDestroyContext(3), pmDup‐
103 Context(3), pmGetConfig(3), pmReconnectContext(3), pmSetMode(3),
104 pmUseContext(3), pmWhichContext(3), pcp.conf(4) and pcp.env(4).
105
107 PM_ERR_PERMISSION
108 No permission to perform requested operation
110 PM_ERR_CONNLIMIT
112 PMCD connection limit for this host exceeded
114 PM_ERR_NOCONTEXT
116 Requested context type was not PM_CONTEXT_LOCAL, PM_CONTEXT_HOST
118 or PM_CONTEXT_ARCHIVE.
119Performance Co-Pilot SGI PMNEWCONTEXT(3)