NAME

       pmGetContextHostName - return the hostname associated with a Performance Co-Pilot context

C SYNOPSIS

       #include <pcp/pmapi.h>

       const char *pmGetContextHostName(int id);

       cc ... -lpcp

DESCRIPTION

       Given   a  valid  PCP  context  identifier  previously  created  with  pmNewContext(3)  or
       pmDupContext(3), the pmGetContextHostName function returns the  hostname  associated  with
       id.

       If  the  context id is associated with an archive source of data, the hostname returned is
       extracted from the archive label using pmGetArchiveLabel(3).

       For live contexts, an attempt will first be made to retrieve the  hostname  from  the  PCP
       collector system using pmFetch(3) with the pmcd.hostname metric.  This allows client tools
       using this interface to retrieve an accurate host identifier even in the presence of  port
       forwarding and tunnelled connections.

       Should  this not succeed, then a fallback method is used.  For local contexts - with local
       meaning any of DSO, ``localhost'' or Unix domain socket connection - a  hostname  will  be
       sought  via  gethostname(3).   For other contexts, the hostname extracted from the initial
       context host specification will be used.

RETURN VALUE

       If id is not a valid PCP context identifier, this function returns a  zero  length  string
       and hence never fails.

PCP ENVIRONMENT

       Environment variables with the prefix PCP_ are used to parameterize the file and directory
       names used by PCP.  On each installation, the file /etc/pcp.conf contains the local values
       for  these  variables.   The  $PCP_CONF  variable  may  be  used to specify an alternative
       configuration file, as described in  pcp.conf(5).   Values  for  these  variables  may  be
       obtained programmatically using the pmGetConfig(3) function.

SEE ALSO

       PCPIntro(1),  PMAPI(3), gethostname(3), pmDupContext(3), pmFetch(3), pmGetArchiveLabel(3),
       pmNewContext(3), pcp.conf(5) and pcp.env(5).