'\"macro stdmacro
.\"
.\" Copyright (c) 2017 Ken McDonell.  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 PMSETDEBUG 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmSetDebug\f1,
\f3pmDebug\f1,
\f3pmGetDebug\f1,
\f3pmClearDebug\f1 \- manipulate PCP debugging control options
.SH "C SYNOPSIS"
.ft 3
.ad l
.hy 0
#include <pcp/pmapi.h>
.sp
int pmSetDebug(const char *\fIspec\fP);
.br
int pmDebug(const char *\fIspec\fP);
.br
char *pmGetDebug(void);
.br
int pmClearDebug(const char *\fIspec\fP);
.sp
cc ... \-lpcp
.hy
.ad
.ft 1
.SH DESCRIPTION
Within the libraries and applications of the Performance Co-Pilot
(PCP) there is an extensive set of debugging options that may
be enabled or disabled at run-time.
.PP
.BR pmSetDebug ,
.B pmDebug
and
.B pmClearDebug
all parse
.I spec
assuming it to be a comma separated list of PCP debug option names.
.PP
The names of the available options may be found using the
.B \-l
argument to
.BR pmdbg (1).
.PP
As a special case, the name ``all'' is treated as a synonym
for identifying all option names.
.PP
.B pmSetDebug
will set the corresponding options, while
.B pmClearDebug
will clear the corresponding options.
.PP
.B pmDebug
is used to test if options have been set and
returns 1 if at least one of the options in
.I spec
has been set, else it returns 0.
.PP
Consecutive calls to either
.B pmSetDebug
or
.B pmClearDebug
will be additive.
For example the
following code fragments are equivalent in terms of the final state
of the debug options.
.sp
.ft CR
.nf
.in +0.5i
sts = pmClearDebug("all");
sts = pmSetDebug("appl0");
sts = pmSetDebug("pdu,fetch");
sts = pmSetDebug("fetch,profile,context");
sts = pmClearDebug("appl0");
.sp
sts = pmClearDebug("all");
sts = pmSetDebug("pdu,fetch,profile,context");
.in
.fi
.ft
.PP
For applications that use
.BR pmGetOptions (3)
to process command line options and arguments,
setting the environment variable
.B $PCP_DEBUG
provides an alternative mechanism to set debug flags, as
described in
.BR PCPIntro (1).
.PP
.B pmGetDebug
returns the current set of enabled debug options as a
a comma separated list.
If no options are set then the result is an empty string.
If every option is set then the result is ``all''.
The result is allocated by
.BR malloc (3)
and the caller is responsible for calling
.BR free (3)
when the result is no longer needed.
.SH DIAGNOSTICS
If successful,
the routines
.BR pmSetDebug ,
.B pmDebug
and
.B pmClearDebug
return 0 or 1,
otherwise the return is
.B PM_ERR_CONV
to indicate an error parsing
.IR spec .
.PP
For
.B pmGetDebug
a return value of NULL indicates a
.BR malloc (3)
failure.
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmdbg (1),
.BR free (3)
and
.BR malloc (3).

.\" control lines for scripts/man-spell
.\" +ok+ appl pdu sts {all from C example code}