27.13.1.1 Tracebacks From an Unhandled Exception

A runtime non-symbolic traceback is a list of addresses of call instructions. To enable this feature you must use the -E gnatbind's option. With this option a stack traceback is stored as part of exception information. You can retrieve this information using the addr2line tool.

Here is a simple example:

     

     procedure STB is
     
        procedure P1 is
        begin
           raise Constraint_Error;
        end P1;
     
        procedure P2 is
        begin
           P1;
        end P2;
     
     begin
        P2;
     end STB;
     

     $ gnatmake stb -bargs -E
     $ stb
     
     Execution terminated by unhandled exception
     Exception name: CONSTRAINT_ERROR
     Message: stb.adb:5
     Call stack traceback locations:
     0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4

As we see the traceback lists a sequence of addresses for the unhandled exception CONSTRAINT_ERROR raised in procedure P1. It is easy to guess that this exception come from procedure P1. To translate these addresses into the source lines where the calls appear, the addr2line tool, described below, is invaluable. The use of this tool requires the program to be compiled with debug information.

     $ gnatmake -g stb -bargs -E
     $ stb
     
     Execution terminated by unhandled exception
     Exception name: CONSTRAINT_ERROR
     Message: stb.adb:5
     Call stack traceback locations:
     0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
     
     $ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4
        0x4011f1 0x77e892a4
     
     00401373 at d:/stb/stb.adb:5
     0040138B at d:/stb/stb.adb:10
     0040139C at d:/stb/stb.adb:14
     00401335 at d:/stb/b~stb.adb:104
     004011C4 at /build/.../crt1.c:200
     004011F1 at /build/.../crt1.c:222
     77E892A4 in ?? at ??:0

The addr2line tool has several other useful options:

--functions

to get the function name corresponding to any location

--demangle=gnat

to use the gnat decoding mode for the function names. Note that for binutils version 2.9.x the option is simply --demangle.

     $ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b
        0x40139c 0x401335 0x4011c4 0x4011f1
     
     00401373 in stb.p1 at d:/stb/stb.adb:5
     0040138B in stb.p2 at d:/stb/stb.adb:10
     0040139C in stb at d:/stb/stb.adb:14
     00401335 in main at d:/stb/b~stb.adb:104
     004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200
     004011F1 in <mainCRTStartup> at /build/.../crt1.c:222

From this traceback we can see that the exception was raised in stb.adb at line 5, which was reached from a procedure call in stb.adb at line 10, and so on. The b~std.adb is the binder file, which contains the call to the main program. See Running gnatbind. The remaining entries are assorted runtime routines, and the output will vary from platform to platform.

It is also possible to use GDB with these traceback addresses to debug the program. For example, we can break at a given code location, as reported in the stack traceback:

     $ gdb -nw stb
     Furthermore, this feature is not implemented inside Windows DLL. Only
     the non-symbolic traceback is reported in this case.
     
     (gdb) break *0x401373
     Breakpoint 1 at 0x401373: file stb.adb, line 5.

It is important to note that the stack traceback addresses do not change when debug information is included. This is particularly useful because it makes it possible to release software without debug information (to minimize object size), get a field report that includes a stack traceback whenever an internal bug occurs, and then be able to retrieve the sequence of calls with the same program compiled with debug information.