# pmgetcontexthostname

## 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** func‐
           tion returns the hostname associated with  _id_.   The  **pmGetContex‐**
           **tHostName_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 be‐
           haves  similarly again, but returns a status code to indicate suc‐
           cess 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  inter‐
           face  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  lo‐
           cal  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  **pmGetContex‐**
           **tHostName** and  hence is not thread-safe.  Multi-threaded applica‐
           tions should use **pmGetHostName** or **pmGetContextHostName_r** instead.
    


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to  parameter‐
           ize  the  file and directory names used by PCP.  On each installa‐
           tion, the file _/etc/pcp.conf_ contains the local values  for  these
           variables.   The  **$PCP_CONF** variable may be used to specify an al‐
           ternative configuration file, as described in pcp.conf(5).  Values
           for these variables may be  obtained  programmatically  using  the
           pmGetConfig(3) function.
    


* * *