PMNEWCONTEXT(3)           Library Functions Manual           PMNEWCONTEXT(3)

NAME         top

       pmNewContext - establish a new PMAPI context

C SYNOPSIS         top

       #include <pcp/pmapi.h>

       int pmNewContext(int type, const char *name);

       cc ... -lpcp

DESCRIPTION         top

       An application using the Performance Metrics Application Programming
       Interface (PMAPI) may manipulate several concurrent contexts, each
       associated with a source of performance metrics, e.g. pmcd(1) on some
       host, or a set of archive logs 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 a comma-separated list of names
       referring to a set of archive logs (type is PM_CONTEXT_ARCHIVE).
       Each element of the list may either be the base name common to all of
       the physical files of an archive log or the name of a directory
       containing archive logs.

       For a type of PM_CONTEXT_HOST, in addition to identifying a host the
       name may also be used to encode additional optional information in
       the form of a pmcd(1) port number, a pmproxy(1) hostname and a proxy
       port number. For example the name
       "app23:14321," specifies a connection
       on port 14321 (or port 4321 if 14321 is unavailable) to pmcd(1) on
       the host app23 via port 11111 to pmproxy(1) on the host

       For a type of PM_CONTEXT_ARCHIVE, each element of the list of names
       in name may also be the name of any of the physical files of an
       archive, e.g.  myarchive.meta (the metadata file) or myarchive.index
       (the temporal index) or myarchive.0 (the first data volume of the
       archive) or myarchive.0.bz2 or (the first data volume
       compressed with bzip2(1)) or myarchive.0.gz or myarchive.0.Z or
       myarchive.0.z (the first data volume compressed with gzip(1)),
       myarchive.1 or myarchive.3.bz2 or myarchive.42.gz etc.

       If more than one archive is specified for a type of
       PM_CONTEXT_ARCHIVE, there are some restrictions on the archives
       within the set:

       ·  The archives must all have been generated on the same host.

       ·  The archives must not overlap in time.

       ·  The archives must all have been created using the same time zone.

       ·  The PMID of each metric should be the same in all of the archives.
          Multiple PMIDs are currently tolerated by using the first PMID
          defined for each metric and ignoring subsequent PMIDs.

       ·  The type of each metric must be the same in all of the archives.

       ·  The semantics of each metric must be the same in all of the

       ·  The units of each metric must be the same in all of the archives.

       ·  The instance domain of each metric must be the same in all of the

       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
       encrypted (PM_CTXFLAG_SECURE), deferred (PM_CTXFLAG_SHALLOW) and if
       the file descriptor used to communicate with pmcd(1), should not be
       shared across contexts (PM_CTXFLAG_EXCLUSIVE).  Both the
       PM_CTXFLAG_SHALLOW and PM_CTXFLAG_EXCLUSIVE flags are now deprecated
       and ignored.

       The initial instance profile is set up to select all instances in all
       instance domains.  In the case of a set of archives, 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
       set of archives.

       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

       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

ENVIRONMENT         top

              Timeout period (in seconds) for pmcd(1) connection attempts.

              TCP/IP port(s) for connecting to pmcd(1), historically was
              4321 and more recently the officially registered port 44321;
              in the current release, pmcd listens on both these ports as a
              transitional arrangement.  If used, should be set to a comma-
              separated list of numerical port numbers.

              When searching for PMDAs to be loaded when type is
              PM_CONTEXT_LOCAL, the PMDA_PATH environment variable may be
              used to define a search path of directories to be used to
              locate the PMDA executables.  The default search path is

CAVEATS         top

       When using a type of PM_CONTEXT_LOCAL, the operating system PMDA may
       export data structures directly from the kernel, which means that the
       pmNewContext caller should be an executable program compiled for the
       same object code format as the booted kernel.

       In addition, applications using a PM_CONTEXT_LOCAL context must be
       single-threaded because the various DSO PMDAs may not be thread-safe.
       This restriction is enforced at the PMAPI(3), where routines may
       return the error code PM_ERR_THREAD if the library detects calls from
       more than one thread.

       Applications that use gethostbyname(3) should exercise caution
       because the static fields in struct hostent may not be preserved
       across some PMAPI(3) calls.  In particular, pmNewContext(3) and
       pmReconnectContext(3) both may call gethostbyname(3) internally.

SEE ALSO         top

       pmcd(1), pmproxy(1), pmAddProfile(3), PMAPI(3), pmDelProfile(3),
       pmDestroyContext(3), pmDupContext(3), pmGetConfig(3),
       pmReconnectContext(3), pmSetMode(3), pmUseContext(3),
       pmWhichContext(3), pcp.conf(5) and pcp.env(5).

DIAGNOSTICS         top


              No permission to perform requested operation


              PMCD connection limit for this host exceeded


              Requested context type was not PM_CONTEXT_LOCAL,


              Archives overlap in time


              Archives differ by host


              Archives differ by time zone.


              The type of a metric differs among archives


              The semantics of a metric differs among archives


              The instance domain of a metric differs among archives


              The units of a metric differs among archives

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2017-09-15.  If you discover any rendering problems in this HTML ver‐
       sion of the page, or you believe there is a better or more up-to-date
       source for the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original man‐
       ual page), send a mail to

Performance Co-Pilot                 PCP                     PMNEWCONTEXT(3)

Pages that refer to this page: pcpintro(1)pmdaib(1)pmgenmap(1)pmstat(1)pcpintro(3)pmaddprofile(3)pmapi(3)pmdelprofile(3)pmdestroycontext(3)pmdupcontext(3)pmfetch(3)pmfetcharchive(3)pmfetchgroup(3)pmgetarchivelabel(3)pmgetcontexthostname(3)pmgetoptions(3)pmlocalpmda(3)pmlookupname(3)pmnameall(3)pmnameid(3)pmnewcontext(3)pmnewcontextzone(3)pmparsehostattrsspec(3)pmparsehostspec(3)pmreconnectcontext(3)pmregisterderived(3)pmspeclocalpmda(3)pmtrimnamespace(3)pmusecontext(3)pmwhichcontext(3)QmcSource(3)