NAME

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

C SYNOPSIS

       #include <pcp/pmapi.h>

       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.

       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.

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