Provided by: libpcp3-dev_4.0.1-1_amd64 bug

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 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,4321@firewall.example.com:11111" 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 firewall.example.com.

       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  myarchive.0.bz  (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 archives.

       •  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 archives.

       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 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.

ENVIRONMENT

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

       PMCD_PORT
              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.

       PMDA_PATH
              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
              $PCP_SHARE_DIR/lib:/usr/pcp/lib.

CAVEATS

       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

       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

       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.

       PM_ERR_LOGOVERLAP

              Archives overlap in time

       PM_ERR_LOGHOST

              Archives differ by host

       PM_ERR_LOGTIMEZONE

              Archives differ by time zone.

       PM_ERR_LOGCHANGETYPE

              The type of a metric differs among archives

       PM_ERR_LOGCHANGESEM

              The semantics of a metric differs among archives

       PM_ERR_LOGCHANGEINDOM

              The instance domain of a metric differs among archives

       PM_ERR_LOGCHANGEUNITS

              The units of a metric differs among archives