NAME

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

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmGetHostName(int id, char *buf, int buflen);
       const char *pmGetContextHostName(int id);
       char *pmGetContextHostName_r(int id, char *buf, int buflen);

       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.  The pmGetContextHostName_r function does the same, but stores the result in  a  user-
       supplied  buffer  buf of length buflen, which should have room for at least MAXHOSTNAMELEN
       bytes.  The pmGetHostName function behaves similarly again, but returns a status  code  to
       indicate success or failure.

       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,  the  returned  hostname  is  a  zero  length
       string.

       On  failure,  the return code of pmGetHostName is a negative PMAPI error code which can be
       processed by pmErrStr_r(3) for diagnostics relating to the failure to obtain  the  context
       hostname.

NOTES

       pmGetContextHostName  returns  a pointer to a static buffer, so the returned value is only
       valid until the next call to pmGetContextHostName and hence is  not  thread-safe.   Multi-
       threaded applications should use pmGetHostName or pmGetContextHostName_r instead.

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),  pmErrStr_r(3),  pmFetch(3),
       pmGetArchiveLabel(3), pmNewContext(3), pcp.conf(5) and pcp.env(5).