pmGetConfig,
pmGetOptionalConfig,
pmGetAPIConfig - return
values for Performance Co-Pilot configuration variables
#include <pcp/pmapi.h>
char *pmGetConfig(const char *
variable);
char *pmGetOptionalConfig(const char *
variable);
char *pmGetAPIConfig(const char *
feature);
cc ... -lpcp
The
pmGetConfig and
pmGetOptionalConfig functions search for
variable first in the environment and then, if not found, in the
Performance Co-Pilot (PCP) configuration file and returns the string result.
If
variable is not already in the environment, it is added with a call
to
setenv(3) before returning.
The
pmGetOptionalConfig function allows for failures - either from
variable not being set at all, or due to the configuration file being
missing.
pmGetConfig is less tolerant to a missing configuration file,
which it treats as a critical PCP installation failure - see the ``RETURN
VALUE'' section below for further details.
The default location of the PCP configuration file is
/etc/pcp.conf but
this may be changed by setting
PCP_CONF in the environment to a new
location, as described in
pcp.conf(5).
The
pmGetAPIConfig function reports on features of the PCP library. It
can be used to query support for multi-threading, security extensions, and
other features.
The
pmconfig(1) utility provides command line access to both of these
interfaces, and also provides a mechanism for listing all available
variables and
features that are valid arguments to these
routines.
If
variable is not found in either the environment or the PCP
configuration file, or if the configuration file is inaccessible, then
pmGetOptionalConfig returns NULL.
If
variable is found in neither the environment nor the PCP configuration
file, then
pmGetConfig returns an empty string. If the PCP
configuration file is not found then a fatal error message is printed and the
process will
exit(2) - although this sounds drastic, it is the only
course of action available because the PCP configuration/installation is
deemed fatally flawed.
The
pmGetAPIConfig routine returns NULL on failure to lookup the
requested
feature. It does not modify the environment, and returns a
pointer to a static read-only string.
The value returned by all of these routines is either a static pointer or
pointer into the environment, and so changing it is a bad idea.
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 function.
PCPIntro(1),
pmconfig(1),
pmGetVersion(3),
exit(2),
PMAPI(3),
getenv(3),
setenv(3),
pcp.conf(5),
pcp.env(5) and
environ(7).