lazarus/docs/xml/lazutils/laztracer.xml

<?xml version="1.0" encoding="utf-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lazutils">
<!--
============================================================================
LazTracer
============================================================================
-->
<module name="LazTracer">
<short>
Contains types and routines used to implement exceptions and stack traces.
</short>
<descr>
<p>
<file>laztracer.pas</file> contains types and routines used to implement 
exceptions and stack traces in the Lazarus IDE and Debugger. This file is 
part of the <file>LazUtils</file> package.
</p>
</descr>

<!-- unresolved external references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="Laz_AVL_Tree"/>
<element name="LazLoggerBase"/>
<element name="LazUtilities"/>
<element name="LazUtilsStrConsts"/>

<element name="TStackTracePointers">
<short>Array type used for Pointers to code addresses.</short>
<descr>
<p>
<var>TStackTracePointers</var> is an <var>Array</var> type which contains 
Pointers to code addresses. TStackTracePointers is the type passed as an 
argument to the <var>GetStackTracePointers</var> and 
<var>StackTraceAsString</var> routines. It is also the type used to implement 
the <var>CreationStack</var> and <var>DestructionStack</var> members in 
<var>TDebugLCLItemInfo</var>.
</p>
</descr>
<seealso>
<link id="GetStackTracePointers"/>
<link id="StackTraceAsString"/>
<link id="#lcl.lclproc.TDebugLCLItemInfo">TDebugLCLItemInfo</link>
</seealso>
</element>

<element name="TLineInfoCacheItem">
<short>
Record type used to store a pointer to a code address and its additional 
information.
</short>
<descr></descr>
<seealso>
<link id="PLineInfoCacheItem"/>
<link id="GetLineInfo"/>
</seealso>
</element>
<element name="TLineInfoCacheItem.Addr">
<short>Pointer to the address for a source code symbol.</short>
</element>
<element name="TLineInfoCacheItem.Info">
<short>
Contains additional information about the code address and its origin.
</short>
</element>

<element name="PLineInfoCacheItem">
<short>Pointer to a TLineInfoCacheItem type.</short>
<descr>
<p>
Used in the implementation of the <var>GetLineInfo</var> routine.
</p>
</descr>
<seealso>
<link id="GetLineInfo"/>
</seealso>
</element>

<element name="RaiseGDBException">
<short>Raises an exception in the GDB debugger.</short>
<descr>
<p>
<var>RaiseGDBException</var> is a procedure used to raise an exception in the 
GDB debugger. Normally, GDB does not catch FPC <var>Exception</var> objects. 
This procedure raises a standard <b>"Division By Zero"</b> exception, which 
<b>IS</b> caught by GDB. This allows a program to be stopped in the debugger 
without extra GDB configuration.
</p>
<remark>
For the Amiga platform, Division by Zero errors are not catchable. The 
program will simply crash.
</remark>
<p>
<var>Msg</var> contains the value used as the message in the exception.
</p>
</descr>
<seealso></seealso>
</element>
<element name="RaiseGDBException.Msg">
<short>Value for the message in the exception.</short>
</element>

<element name="RaiseAndCatchException">
<short>
Raises an exception that is caught and handled in an application.
</short>
<descr>
<p>
<var>RaiseAndCatchException</var> is a procedure used to generate an 
<var>Exception</var> that is caught and handled by an application.
</p>
<remark>
For the Amiga platform, Division by Zero errors are not catchable. The 
program will simply crash.
</remark>
</descr>
<seealso></seealso>
</element>

<element name="GetStackTrace">
<short>Retrieves backtrace information for code addresses.</short>
<descr>
<p>
<var>GetStackTrace</var> is a <var>String</var> function used to retrieve 
backtrace information for code addresses in a string format.
</p>
<p>
Calls <var>GetLineInfo</var> to get information for the code addresses, using 
the value in <var>UseCache</var> as an argument. UseCache indicates if cached 
line information from an internal AVL tree can be used in the routine. When 
UseCache contains <b>False</b>, the <var>BackTraceStrFunc</var> in 
<file>lclproc.pas</file> initialization section is called to get the line 
information for each of the backtrace addresses.
</p>
</descr>
<seealso>
<link id="GetLineInfo"/>
</seealso>
</element>
<element name="GetStackTrace.Result">
<short>String with information about backtrace addresses.</short>
</element>
<element name="GetStackTrace.UseCache">
<short>
Indicates if cached line information can be used in the routine.
</short>
</element>

<element name="GetStackTracePointers">
<short>
Retrieve the addresses and information for a code address and its callers.
</short>
<descr>
<p>
<var>GetStackTracePointers</var> is a procedure used to retrieve the 
addresses and information for a code address and its callers.
</p>
<p>
<var>AStack</var> is the array where pointers to code addresses for calling 
routines are stored.
</p>
</descr>
<seealso>
<link id="StackTraceAsString"/>
</seealso>
</element>
<element name="GetStackTracePointers.AStack">
<short>Array where pointers to code addresses are stored.</short>
</element>

<element name="StackTraceAsString">
<short>
Gets a string with backtrace information for the specified call stack.
</short>
<descr>
<p>
<var>StackTraceAsString</var> is a <var>String</var> function used to get 
backtrace information for the code addresses specified in <var>AStack</var>. 
The return value contains lines with the values from <var>GetLineInfo</var> 
for each of the code addresses.
</p>
<p>
<var>UseCache</var> indicates if cached line information from an internal AVL 
tree can be used in the routine. It is passed as an argument in calls to the 
<var>GetLineInfo</var> routine.
</p>
</descr>
<seealso>
<link id="GetLineInfo"/>
<link id="TStackTracePointers"/>
</seealso>
</element>
<element name="StackTraceAsString.Result">
<short>String with backtrace information for the call stack.</short>
</element>
<element name="StackTraceAsString.AStack">
<short>Array of pointers to code addresses examined in the routine.</short>
</element>
<element name="StackTraceAsString.UseCache">
<short>
Indicates if cached line information can be used in the routine.
</short>
</element>

<element name="GetLineInfo">
<short>Gets information about the specified code address.</short>
<descr>
<p>
<var>GetLineInfo</var> is a <var>String</var> function used to get 
information about the code address specified in <var>Addr</var>.
</p>
<p>
<var>UseCache</var> indicates if cached line information from an internal AVL 
tree can be used in the routine. When UseCache contains <b>False</b>, the 
<var>BackTraceStrFunc</var> in the <file>lclproc.pas</file> initialization 
section is called to get the line information for each of the backtrace 
addresses.
</p>
</descr>
<seealso/>
</element>
<element name="GetLineInfo.Result">
<short>String with information about the code address.</short>
</element>
<element name="GetLineInfo.Addr">
<short>The code address examined in the routine.</short>
</element>
<element name="GetLineInfo.UseCache">
<short>
Indicates if locally cached line information can be used in the routine.
</short>
</element>

</module>
<!-- LazTracer -->
</package>
</fpdoc-descriptions>