diff options
Diffstat (limited to 'man/man3/pmgetcontexthostname.3')
-rw-r--r-- | man/man3/pmgetcontexthostname.3 | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/man/man3/pmgetcontexthostname.3 b/man/man3/pmgetcontexthostname.3 new file mode 100644 index 0000000..5826861 --- /dev/null +++ b/man/man3/pmgetcontexthostname.3 @@ -0,0 +1,114 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013 Red Hat. +.\" Copyright (c) 2000-2004 Silicon Graphics, Inc. All Rights Reserved. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" +.TH PMGETCONTEXTHOSTNAME 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmGetContextHostName\f1, +\f3pmGetContextHostName_r\f1 \- return the hostname associated with a Performance Co-Pilot context +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +const char *pmGetContextHostName(int \fIid\fP); +.br +char *pmGetContextHostName_r(int \fIid\fP, char *\fIbuf\fP, int \fIbuflen\fP); +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +Given a valid PCP context identifier previously created with +.BR pmNewContext (3) +or +.BR pmDupContext (3), +the +.B pmGetContextHostName +function returns the hostname associated with +.IR id . +The +.B pmGetContextHostName_r +function does the same, but stores the result in a user-supplied buffer +.I buf +of length +.IR buflen , +which should have room for at least +.B MAXHOSTNAMELEN +bytes. +.PP +If the context +.I id +is associated with an archive source of data, the +hostname returned is extracted from the archive label using +.BR pmGetArchiveLabel (3). +.PP +For live contexts, an attempt will first be made to retrieve +the hostname from the PCP collector system using +.BR pmFetch (3) +with the +.I 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. +.PP +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 +.BR gethostname (3). +For other contexts, the hostname extracted from the initial +context host specification will be used. +.SH "RETURN VALUE" +If +.I id +is not a valid PCP context identifier, +the returned hostname is a zero length string. +.SH NOTES +.B pmGetContextHostName +returns a pointer to a static buffer, +so the returned value is only valid until the next call to +.B pmGetContextHostName +and hence is not thread-safe. +Multi-threaded applications should use +.B pmGetContextHostName_r +instead. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetConfig (3) +function. +.SH SEE ALSO +.BR PCPIntro (1), +.BR PMAPI (3), +.BR gethostname (3), +.BR pmDupContext (3), +.BR pmFetch (3), +.BR pmGetArchiveLabel (3), +.BR pmNewContext (3), +.BR pcp.conf (5) +and +.BR pcp.env (5). |