PMSETDEBUG(3)

NAME
pmSetDebug, pmDebug, pmGetDebug, pmClearDebug - manipulate PCP debugging control options

C SYNOPSIS
#include <pcp/pmapi.h>

int pmSetDebug(const char *spec);
int pmDebug(const char *spec);
char *pmGetDebug(void);
int pmClearDebug(const char *spec);

cc ... -lpcp

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.

pmSetDebug, pmDebug and pmClearDebug all parse spec assuming it to be a comma separated list of PCP debug option names.

The names of the available options may be found using the -l argument to pmdbg(1).

As a special case, the name ``all'' is treated as a synonym for identifying all option names.

pmSetDebug will set the corresponding options, while pmClearDebug will clear the corresponding options.

pmDebug is used to test if options have been set and returns 1 if at least one of the options in spec has been set, else it returns 0.

Consecutive calls to either pmSetDebug or pmClearDebug will be additive. For example the following code fragments are equivalent in terms of the final state of the debug options.

sts = pmClearDebug("all");
sts = pmSetDebug("appl0");
sts = pmSetDebug("pdu,fetch");
sts = pmSetDebug("fetch,profile,context");
sts = pmClearDebug("appl0");

sts = pmClearDebug("all");
sts = pmSetDebug("pdu,fetch,profile,context");

For applications that use pmGetOptions(3) to process command line options and arguments, setting the environment variable $PCP_DEBUG provides an alternative mechanism to set debug flags, as described in PCPIntro(1).

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 malloc(3) and the caller is responsible for calling free(3) when the result is no longer needed.

DIAGNOSTICS
If successful, the routines pmSetDebug, pmDebug and pmClearDebug return 0 or 1, otherwise the return is PM_ERR_CONV to indicate an error parsing spec.

For pmGetDebug a return value of NULL indicates a malloc(3) failure.

SEE ALSO
PCPIntro(1), pmdbg(1), free(3) and malloc(3).