Man Linux: Main Page and Category List


       pmNewContext - establish a new PMAPI context


       #include <pcp/pmapi.h>

       int pmNewContext(int type, const char *name)

       cc ... -lpcp


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

       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

       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


              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


       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.


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



              No permission to perform requested operation


              PMCD connection limit for this host exceeded


              Requested context type was not PM_CONTEXT_LOCAL, PM_CONTEXT_HOST
              or PM_CONTEXT_ARCHIVE.