int pmNewContext(int type, const char *name)
pmNewContext may be used to establish a new context. The source of the metrics is identified by name, and may be either a host name (type is PM_CONTEXT_HOST), or the base name for the files of an archive log (typeis PM_CONTEXT_ARCHIVE). In the latter case, name may also be the name of any component file of an archive, e.g. the base name with the suffix .index, .meta, .0, etc.
In the case where type is PM_CONTEXT_LOCAL, name is ignored, and the context uses a standalone connection to the PMDA methods used by pmcd(1). When this type of context is used, the range of accessible performance metrics is constrained to those from the operating system, and optionally the ``proc'', ``sample'' and ``ib'' PMDAs.
In the case where type is PM_CONTEXT_HOST, additional flags can be added to the type to indicate if the connection to pmcd(1) should be deferred (PM_CTXFLAG_SHALLOW) and if the file descriptor, used to communicate with pmcd(1), should not be shared across contexts (PM_CTXFLAG_EXCLUSIVE).
The initial instance profile is set up to select all instances in all instance domains. In the case of an archive, the initial collection time is also set to zero, so that an initial pmFetch(3) will result in the earliest set of metrics being returned from the archive.
Once established, the association between a context and a source of metrics is fixed for the life of the context, however routines are provided to independently manipulate both the instance profile (see pmAddProfile(3) and pmDelProfile(3)) and the collection time for archives (see pmSetMode(3)).
pmNewContext returns a handle that may be used with subsequent calls to pmUseContext(3).
The new context remains the current PMAPI context for all subsequent calls across the PMAPI, until another call to pmNewContext(3) is made, or the context is explicitly changed with a call to pmDupContext(3) or pmUseContext(3), or destroyed using pmDestroyContext(3).
When attempting to connect to a remote pmcd(1) on a machine that is booting, pmNewContext could potentially block for a long time until the remote machine finishes its initialization. pmNewContext will abort and return an error if the connection has not been established after some specified interval has elapsed. The default interval is 5 seconds. This may be modified by setting PMCD_CONNECT_TIMEOUT in the environment to a real number of seconds for the desired timeout. This is most useful in cases where the remote host is at the end of a slow network, requiring longer latencies to establish the connection correctly.
Applications that use gethostbyname(3N) should exercise caution because the static fields in struct hostent may not be preserved across some PMAPI(4) calls. In particular, pmNewContext(3) and pmReconnectContext(3) both may call gethostbyname(3N) internally.
PM_ERR_PERMISSION
PM_ERR_CONNLIMIT
PM_ERR_NOCONTEXT