12.8.1 Foreign debugging functions

The functions in this section are primarily intended for debugging foreign extensions or embedded Prolog. Violating the constraints of the foreign interface often leads to crashes in a subsequent garbage collection. If this happens, the system needs to be recompiled with the cflags -DO_DEBUG. This is normally achieved by editing src/Makefile and changing the definition of COFLAGS to the value below. The -gdwarf-2 -g3 provides detailed debugging information for gcc. If you use another C compiler you may need other flags.

COFLAGS=-DO_DEBUG -gdwarf-2 -g3

After recompiling the Prolog kernel all functions listed above are available to use from the debugger (e.g. gdb) or can be placed at critical location in your code or the system code.

void PL_backtrace(int depth, int flags)

Dump a Prolog backtrace to the user_error stream. Depth is the number of frames to dump. Flags is a bitwise or of the following constants:

PL_BT_SAFE

(0x1) Do not try to print goals. Instead, just print the predicate name and arity. This reduces the likelyhood to crash if PL_backtrace() is called in a damaged environment.

PL_BT_USER

(0x2) Only show `user' frames. Default is to also show frames of hidden built-in predicates.

char * PL_backtrace_string(int depth, int flags)

As PL_backtrace(), but returns the stack as a string. The string uses UTF-8 encoding. The returned string must be freed using PL_free(). This function is was added to get stack traces from running servers where I/O is redirected or discarded. For example, using gdb, a stack trace is printed in the gdb console regardless of Prolog I/O redirection using the following command:

(gdb) printf "%s", PL_backtrace_string(25,0)

The source distribution provides the script scripts/swipl-bt that exploits gdb and PL_backtrace_string() to print stack traces in various formats for a SWI-Prolog process, given its process id.

int PL_check_data(term_t data)

Check the consistency of the term data. Returns TRUE this is actually implemented in the current version and FALSE otherwise. The actual implementation only exists if the system is compiled with the cflag -DO_DEBUG or -DO_MAINTENANCE. This is not the default.

int PL_check_stacks()

Check the consistency of the runtime stacks of the calling thread. Returns TRUE this is actually implemented in the current version and FALSE otherwise. The actual implementation only exists if the system is compiled with the cflag -DO_DEBUG or -DO_MAINTENANCE. This is not the default.

The Prolog kernel sources use the macro DEBUG(Topic, Code). These macros are disabled in the production version and must be enabled by recompiling the system as described above. Specific topics can be enabled and disabled using the predicates prolog_debug/1 and prolog_nodebug/1. In addition, they can be activated from the commandline using commandline option -d topics, where topics is a comma-separated list of debug topics to enable. For example, the code below adds many consistency checks and prints messages if the Prolog signal handler dispatches signals.

$ swipl -d chk_secure,msg_signal

prolog_debug(+Topic)

prolog_nodebug(+Topic)

Enable/disable a debug topic. Topic is an atom that identifies the desired topic. The available topics are defined in src/pl-debug.h. Please search the sources to find out what is actually printed and when. We highlight one topic here:

chk_secure(chk_secure)

dd many expensive consistency checks to the system. This should typically be used when the system crashes, notably in the garbage collector. Garbage collection crashes are in most cases caused by invalid data on the Prolog stacks. This debug topic may help locating how the invalid data was created.