6.2.23 Displaying a backtrace (where command)

A backtrace consists of information that shows how the executing job definition script reached the current location where execution has stopped. A backtrace is represented by frames. A frame is data related to a single call to a function. When a function is called, one frame is added. When a function terminates, its frame is deleted. A sequential number, beginning with zero, is assigned to each frame starting from the innermost frame. The innermost frame indicates the currently executing function. The where command displays a backtrace. The abbreviation for the where command is whe. The following shows the format of the where command:

where[ frame-number]

When a frame number is specified in the argument, the where command displays information about the innermost frame through the frame with the specified number. If the argument is omitted, the command displays information about all frames in order starting from the innermost frame. The following shows the display format:

Num  Function  File:Line
frame-number  function-name  file-name:line-number
...

frame-number: Number assigned to a frame. The frame numbers are displayed in ascending order starting with 0. Up to three left-justified digits can be displayed.
function-name: Name of the function corresponding to the frame to which the name of the job definition script that called the function is attached. If no function has been called, <main> is displayed as the function name. A maximum of 63 bytes can be displayed.
file-name: Name of the job definition script file corresponding to the frame. If the frame number is zero, this is the name of the current file whose execution is stopped. If the frame number is 1 or greater, this is the file name used when a new function was called.
line-number: Line number corresponding to the frame. If the frame number is zero, this is the current line number at which execution has stopped. If the frame number is 1 or greater, this is the line number used to call a new function.

If execution has stopped at the end of the job definition script, <EOF> is displayed. If execution has stopped while the trap command's action is executing, <Trap action> is displayed.

The following describes the where command's processing.

When the where command argument is omitted

If the where command is executed while execution of the job definition script is stopped, the command displays information about all frames in order starting from the innermost frame.

If the job definition script is not running, the command outputs an error message.

When the where command argument is specified

If the where command is executed while the job definition script is running and a valid frame number is specified, the command displays information about the innermost frame through the frame with the specified frame number.

If a non-numeric value is specified or the job definition script is not running, the command outputs an error message.

Notes:

Specify 0 or a greater integer for a frame number. Do not specify a plus sign (+) at the beginning.
If the specified frame number is outside the permitted value range for the int type, it is rounded to the maximum value permitted for the int type.
A maximum of 255 frames can be displayed (frame numbers 0 through 254). Specifying 255 or a greater value in the argument does not display a frame with the specified number. If there are more than 255 frames, a message is displayed following the frame information.

Example

This example executes the where command when funcA was called on line 12 of sample.ash, funcB was called on line 9, and then execution stopped on line 12 of test.ash.

sample.ash

5: #-adsh_script test.ash
6:
7: funcA(){
8:   num=10
9:   funcB
10: }
11:
12: funcA

test.ash

10: funcB(){
11:   val=5
12:   num=20
13: }
 
Num  Function               File:Line
0    funcB (in sample.ash)  test.ash:12
1    funcA (in sample.ash)  sample.ash:9
2    <main>                 sample.ash:12

To Page Top