NAME
pmNewContext - establish a new PMAPI context
C SYNOPSIS
#include <pcp/pmapi.h>
int pmNewContext(int type, const char *name)
cc ... -lpcp
DESCRIPTION
An application using the Performance Metrics Application
Programming Interface (PMAPI) may manipulate several con
current contexts, each associated with a source of perfor
mance metrics, e.g. pmcd(1) on some host, or an archive
log of performance metrics as created by pmlogger(1), or a
standalone connection on the local host that does not
involve pmcd(1).
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 (type is PM_CON
TEXT_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 con
text is used, the range of accessible performance metrics
is constrained to those from the operating system, and
optionally the ``proc'' and ``sample'' PMDAs.
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 pmDel
Profile(3)) and the collection time for archives (see
pmSetMode(3)).
pmNewContext returns a handle that may be used with subse
quent calls to pmUseContext(3).
The new context remains the current PMAPI context for all
subsequent calls across the PMAPI, until another call to
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_CON
NECT_TIMEOUT in the environment to a real number of sec
onds for the desired timeout. This is most useful in
cases where the remote host is at the end of a slow net
work, requiring longer latencies to establish the connec
tion correctly.
ENVIRONMENT
PMCD_CONNECT_TIMEOUT
Timeout period (in seconds) for pmcd(1) connection
attempts.
PMCD_PORT
TCP/IP port for connecting to pmcd(1), defaults to
4321.
PMDA_LOCAL_PROC
If set, then a context established with the type of
PM_CONTEXT_LOCAL will have access to the ``proc''
PMDA to retrieve performance metrics about individ
ual processes.
PMDA_LOCAL_SAMPLE
If set, then a context established with the type of
PM_CONTEXT_LOCAL will have access to the ``sample''
PMDA if this optional PMDA has been installed
locally.
PMDA_PATH
When searching for PMDAs to be loaded when type is
PM_CONTEXT_LOCAL, the PMDA_PATH environment vari
able may be used to define a search path of direc
tories to be used to locate the PMDA executables.
The default search path is
/var/pcp/lib:/usr/pcp/lib.
CAVEATS
When using a type of PM_CONTEXT_LOCAL, the operating sys
tem PMDA may export data structures directly from the ker
nel, which means that the pmNewContext caller should be an
executable program compiled for the same object code for
mat as the booted IRIX kernel.
Applications that use gethostbyname(3N) should exercise
not be preserved across some PMAPI(4) calls. In particu
lar, pmNewContext(3) and pmReconnectContext(3) both may
call gethostbyname(3N) internally.
SEE ALSO
pmAddProfile(3), PMAPI(3), pmDelProfile(3), pmDestroyCon
text(3), pmDupContext(3), pmGetConfig(3), pmReconnectCon
text(3), pmSetMode(3), pmUseContext(3), pmWhichContext(3),
pcp.conf(4) and pcp.env(4).
DIAGNOSTICS
PM_ERR_PERMISSION
No permission to perform requested operation
PM_ERR_CONNLIMIT
PMCD connection limit for this host exceeded
PM_ERR_NOCONTEXT
Requested context type was not PM_CONTEXT_LOCAL,
PM_CONTEXT_HOST or PM_CONTEXT_ARCHIVE.
Man(1) output converted with
man2html