1PMGETCONTEXTHOSTNAME(3)    Library Functions Manual    PMGETCONTEXTHOSTNAME(3)
2
3
4

NAME

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

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmGetHostName(int id, char *buf, int buflen);
13       const char *pmGetContextHostName(int id);
14       char *pmGetContextHostName_r(int id, char *buf, int buflen);
15
16       cc ... -lpcp
17

DESCRIPTION

19       Given a valid PCP context identifier previously created with  pmNewCon‐
20       text(3)  or  pmDupContext(3), the pmGetContextHostName function returns
21       the hostname associated with id.  The  pmGetContextHostName_r  function
22       does  the  same, but stores the result in a user-supplied buffer buf of
23       length buflen, which should  have  room  for  at  least  MAXHOSTNAMELEN
24       bytes.  The pmGetHostName function behaves similarly again, but returns
25       a status code to indicate success or failure.
26
27       If the context id is associated with an archive  source  of  data,  the
28       hostname   returned   is   extracted   from  the  archive  label  using
29       pmGetArchiveLabel(3).
30
31       For live contexts, an attempt will first be made to retrieve the  host‐
32       name from the PCP collector system using pmFetch(3) with the pmcd.host‐
33       name metric.  This allows client tools using this interface to retrieve
34       an accurate host identifier even in the presence of port forwarding and
35       tunnelled connections.
36
37       Should this not succeed, then a fallback method  is  used.   For  local
38       contexts  - with local meaning any of DSO, ``localhost'' or Unix domain
39       socket connection - a hostname will be sought via gethostname(3).   For
40       other  contexts,  the  hostname extracted from the initial context host
41       specification will be used.
42

RETURN VALUE

44       If id is not a valid PCP context identifier, the returned hostname is a
45       zero length string.
46
47       On  failure, the return code of pmGetHostName is a negative PMAPI error
48       code which can be processed by pmErrStr_r(3) for  diagnostics  relating
49       to the failure to obtain the context hostname.
50

NOTES

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

PCP ENVIRONMENT

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

SEE ALSO

66       PCPIntro(1),  PMAPI(3), gethostname(3), pmDupContext(3), pmErrStr_r(3),
67       pmFetch(3),  pmGetArchiveLabel(3),  pmNewContext(3),  pcp.conf(5)   and
68       pcp.env(5).
69
70
71
72Performance Co-Pilot                  PCP              PMGETCONTEXTHOSTNAME(3)
Impressum