'\"macro stdmacro
.\"
.\" Copyright (c) 2012,2015,2018 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,
\f3pmGetOptionalConfig\f1,
\f3pmGetAPIConfig\f1 \- return values for Performance Co-Pilot configuration variables
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.sp
char *pmGetConfig(const char *\fIvariable\fP);
.br
char *pmGetOptionalConfig(const char *\fIvariable\fP);
.br
char *pmGetAPIConfig(const char *\fIfeature\fP);
.sp
cc ... \-lpcp
.ft 1
.SH DESCRIPTION
The
.B pmGetConfig
and
.B pmGetOptionalConfig
functions search 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 setenv (3)
before returning.
.PP
The
.B pmGetOptionalConfig
function allows for failures \- either from
.I variable
not being set at all, or due to the configuration file
being missing.
.B 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.
.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
.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 or the PCP configuration file,
or if the configuration file is inaccessible, then
.B pmGetOptionalConfig
returns NULL.
.PP
If
.I variable
is found in neither the environment nor the PCP configuration file, then
.B pmGetConfig
returns 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 deemed fatally flawed.
.PP
The
.B pmGetAPIConfig
routine 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.
.PP
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.
.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 pmGetVersion (3),
.BR exit (2),
.BR PMAPI (3),
.BR getenv (3),
.BR setenv (3),
.BR pcp.conf (5),
.BR pcp.env (5)
and
.BR environ (7).