'\"macro stdmacro
.\"
.\" Copyright (c) 2012 Red Hat.
.\" Copyright (c) 2000 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 PMGETCONFIG 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmGetConfig\f1 \- return Performance Co-Pilot configuration variable
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.br
char *pmGetConfig(const char *\fIvariable\fP);
.sp
#include <pcp/impl.h>
.br
char *__pmGetAPIConfig(const char *\fIfeature\fP);
.sp
cc ... \-lpcp
.ft 1
.SH DESCRIPTION
The
.B pmGetConfig
function searches for
.I variable
first in the environment and then, if not found, in
the Performance Co-Pilot (PCP) configuration file
and returns the string result.
If
.I variable
is not already in the environment,
it is added with a call to
.BR putenv (3)
before returning.
.PP
The default location of the PCP configuration file is
.B /etc/pcp.conf
but this may be changed by setting
.B PCP_CONF
in the environment to a new location,
as described in
.BR pcp.conf (5).
.PP
The internal
.B __pmGetAPIConfig
function reports on features of the PCP library.
It can be used to query support for multi-threading, security extensions,
and other features.
.PP
The
.BR pmconfig (1)
utility provides command line access to both of these interfaces, and also
provides a mechanism for listing all available
.B variables
and
.B features
that are valid arguments to these routines.
.SH "RETURN VALUE"
If
.I variable
is not found in either the environment nor the PCP configuration file then
the return value is an empty string.
If the
PCP configuration file is not found
then a fatal error message is printed and the process will
.BR exit (2)
\- although this sounds drastic, it is the only course of action available
because the PCP configuration/installation is fatally flawed.
.PP
If the
.B pmGetConfig
function returns a non-empty string,
the returned value points into the environment and so changing
it is a bad idea.
This function returns the same type as the 
.BR getenv (3)
function (which should probably be a
.IR "const char *" ).
.PP
The
.B __pmGetAPIConfig
routine on the other hand returns NULL on failure to lookup the requested
.IR feature .
It does not modify the environment, and returns a pointer to a static
read-only string which also should not be modified or freed by the caller.
.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 pmconfig (1),
.BR exit (2),
.BR PMAPI (3),
.BR getenv (3C),
.BR putenv (3C),
.BR pcp.conf (5),
.BR pcp.env (5)
and
.BR environ (5).