Provided by: libpcp3-dev_3.5.11_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 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 common to all of the physical files of an archive log (type  is  PM_CONTEXT_ARCHIVE).
       In  the latter case, 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.

       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.

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

       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.

SEE ALSO

       pmAddProfile(3),    PMAPI(3),   pmDelProfile(3),   pmDestroyContext(3),   pmDupContext(3),
       pmGetConfig(3), pmReconnectContext(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.