![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Navigation Navigation in the debugger takes place in many ways. When the debugger has halted program execution, the debugger automatically displays the location in the source code at which execution has halted. At this point, you can visit an entity or another file, display the program call stack and move to any frame on the call stack.
The following are covered in this chapter:
For all navigation commands, it is important to understand the visibility rules used by the debugger as well as what is meant by the terms home position, current frame, and current position.
Visibility RulesThe debugger visibility rules determine which identifiers are visible at a given point in the program execution. The current frame establishes the current visibility rules using the following model:
If the current frame is an Ada subprogram, package or task, Ada visibility rules are used. However, since debugging is not the same as programming, these rules are extended in two ways.
First, if a name is not found based on the normal Ada visibility rules, a search is made of the Ada library for a library unit with that name. Therefore, all library units are visible regardless of what units are with'ed by the current context.
Second, a program-wide search is made for subprograms when a simple name is given as the argument to the b, v, edit and vb commands. That is, it looks at all the subprograms, tasks, and packages (with elaboration subprograms) in the entire program, for one whose simple name matches the name typed in for the command. The results of this search are merged with the results of searching using Ada visibility rules (including library search extension).
C++ supports four kinds of name scopes: local, function, file and class. The debugger resolves local and function scope names the same as the C++ compiler based on the current debugging context. The debugger also provides access to function or class names that are not directly visible in the current debugging context. This capability allows users to call functions, set breakpoints, change context to functions or classes that are not directly visible.
File scope, or global function names may be referenced even when they are not visible from the current file. This is useful for navigation and setting breakpoints in non local functions. Class member functions may be referenced without their class qualification just like other global function names but class member data must be referenced according to the C++ member name rules.
Additional information on C++ scope can be found in C++ Scope/Name/Operators.
Home Position
The home position is the execution point in the current stack frame, the next instruction to execute. The line containing the home position is marked with an arrow.
When program execution moves to a new execution point, the home position changes as well. For the topmost frame(s), (that is., topmost non-inline frame plus any inline frames above it), the home position is the instruction that executes next. For all other frames, it is the call instruction that called the next higher non-inline frame.
* is recognized as a valid line number meaning "the line containing the home position." In the command-line debugger or the Command Pane you can use an asterisk as a command to move the current position to the home position.
Current Position
The current position is represented by a three-part identifier consisting of file, line number, and instruction address. This identifier represents the present location in the source program. In the debugger GUI, this information is displayed in the log window.
The v or Visit command permits changing the current position into an arbitrary file. The v command, without any parameters, displays the current position (except the instruction address).
The debugger keeps track of the current position to make certain frequently-used commands more convenient. In particular, the breakpoint and list commands use the current position as a default parameter. This section explains how the current position is initialized, how it is changed and how to find out what it is.
When a breakpoint occurs or after a call stack command is executed, the current position is set to the home position of the current frame. For the top frame of the call stack, this corresponds to the breakpoint. For all other frames, the home position is the location of the call to the next higher frame. You can change the current position using the call stack commands, the Visit command, the line number command, the listing commands and the searching commands.
Current Frame
The current frame is the current position on the call stack. When a breakpoint is announced, the current frame is always set to the breakpointed subprogram, package, task (Ada), function or class (C/C++). This frame is the topmost frame of the call stack. In moving up and down the call stack (cd and cu commands), the current frame is the frame moved to most recently. The current frame is always the topmost frame of a cs command listing.
Each frame has a current instruction associated with it. For the topmost non-inline frame, this is the instruction that executes next. For all other non-inline frames it is the call instruction that called the next higher non-inline frame. For inline frames, the current instruction is the same as the current instruction of the next lower non-inline frame. This current instruction address, plus the source line and filename that generated it, constitute the home position for that frame. In showing disassembled instructions, the home position (marked with *) is displayed next to the current instruction for the current frame
Change the current frame only with the Call Stack commands, or by running the program to a new breakpoint.
The current frame plays a central role in establishing what program names are currently visible at any point during a debugging session.
When a breakpoint is reached or a call stack command is executed, the current position is always set equal to the home position of the current frame. Examining the program source or instructions changes the current position. Return to home position in the current frame by typing
*
This command moves the current position to the home position of the current frame.
Display Source CodeIt is often desirable or necessary to display sections of your program different from that current displayed either on the debugger window, the editor window or through the non-GUI debugger.
In the Main debugger window, display the source by using the View > Show Source command to display the Source Pane in this window. Use the scroll bar at the side of the Source Pane to display other sections of your program. Do the same in the Editor window.
There are also a number of commands used in the non-GUI debugger and which can be entered in the Command Pane for displaying different sections of your source program.
These commands are listed in the table below and discussed in detail following the table.
l Display source code
w Display window of source code
li Display instructions
wi Display window
The li and wi commands are discussed in the chapter on machine-level debugging.
l
Syntax
l [line
] [,number
]
Arguments
Description
l lists a specified number of lines of the current source file starting at the specified line. The default value for number is 10 which can be changed with the set lines number command. The default line is the current line, which is marked with < to the left. In screen mode the current line is the line under the cursor.
The possible forms of line are:
After the l command is executed, the current line is the last line displayed. Consequently, typing l without parameters continues listing where the last l command stopped.
If * appears after the line number, that line is the current home position for this file. If = appears after the line number, a breakpoint is set for that line.
If - appears after the line number, a breakpoint is set in the code generated for this line but not on the first instruction. If both = and - apply to the same line, only one is displayed.
If + appears after the line number, this represents an inline frame.
In Screen Mode
Precede this command with : and follow with Return.
w
Syntax
w [line
] [,number]
Arguments
Description
The term "window" means a section of source text. Do not confuse it with the windows of the debugger.
w lists a window of source text around the specified line in the current file. This listing occurs in the Command/Log Window. If line is not specified, the center of the window is the line portion of the current position. If the line specification is *, the line portion of the current home position is used as the center of the window. If line is given, the current position moves to that line and the window surrounding that line is displayed.
The window is the specified number of lines large. (Default: 10.) Change the default with the set lines number command.
In Screen Mode
Precede this command with : and follow with Return.
VisitIn the debugger GUI or editor windows, use the Visit command to move to another language entity, subprogram, or file. There are also a number of commands that can be entered from the Command Pane or the non-GUI debuggerdebugger log to visit program and debugger constructs.
Move to Line Number
Syntax
number
+number
-number
*
Arguments
Description
Some debugger commands accept number as a parameter (b, l, w, li, wi). In line mode, typing number by itself is the debugger command to move to that line.
Specify a line number as a decimal number, representing that line in the current file. Typing +number or -number adds or subtracts the specified number from the current position. For example, typing +5 or -5 as a command changes the debugger current line position by adding or subtracting 5, respectively. For the debugger commands b, l and w, typing a * as a line number means "use the line number corresponding to the current home position". For the debugger commands li and wi, typing * means the home position instruction (not the line number).
When the debugger displays the current home position, * appears to the left of the line that corresponds to the home position.
The v command with no parameters lists the current file, subprogram and line corresponding to the current position.
In Screen Mode
Move to a new line in screen mode by using this command :
[number
]G
The G must be upper case. This command moves the debugger source window so it displays the line in the current file whose number is specified. If number is not specified, the source window moves to the end of the file. Thus, in screen mode both of the following commands move to line 102.
102G :102
By default, the debugger displays source with associated line numbers, (controlled with the set number [on|off] command).
/ ?
Search for a pattern in the current file
Syntax
/pattern
Return repeats ?pattern
Return repeats
Arguments
- pattern
Pattern to search for. If no pattern is given, the most recent pattern for either a / or ? command is used. Press Return to execute the command again.
Description
The / and ? commands search forward and backward, respectively, in the current file, starting at the line following the current line, for the specified pattern. If the pattern is found, the line it is on becomes the current line. The search wraps around; that is, if the pattern is not found between the current line and the end of the file, the file is searched from the beginning to the current line. Control the case sensitivity of the search through the set case [on|off] command.
The searching commands (/) and ?) use regex(3) for pattern matching. This is similar to vi and is described in operating system manuals under ed(1).
The line containing the matching pattern becomes the new current position.
In Screen Mode
Use the searching commands (/ and ?) in either the source or command window. Typing a / or a ? moves the cursor to the last line on the screen and prompts for the search pattern. The prompt is either a / or a ?. Terminate the pattern by pressing Return or ESC. Pressing n repeats the command.
If the pattern is found, the window displays the line containing the pattern.
The n command in screen mode repeats the last / or ? search but the search starts from the current cursor location in the current line.
v
Navigate to a declaration, subprogram or source file (like vi tags)
Syntax
v [language_entity
|language_source_file
]
Arguments
- language_entity
Name of an Ada or C/C++ entity such as a subprogram, package, task (Ada), function, class, (C/C++), type, variable, constant, etc.
- language_source_file
Name of an Ada or C/C++ source file. This file must in a directory on your Adapath (Ada) or source path (C/C++). Note that for C/C++, all filenames must be enclosed in quotation marks.
Description
The v command provides a convenient way to move the current position to a new file or line within a file. If a file is specified, the current position becomes the beginning of the file. If an Ada or C/C++ entity is specified, the current position becomes the first line in the source file of the entity's full definition. For example, for a subprogram (Ada) or function (C/C++), the current position becomes the first line of the subprogram's (Ada) or function's (C/C++) body. For a type, the current position becomes the first line of the type's full declaration.
For purposes of the v and edit, commands, visibility rules for the language_entity name are as follows.
For Ada, iIf the language_entity name given is a simple identifier, all subprograms, tasks, and packages (with an elaboration subprogram) in the program are visible. Other Ada entities (including packages with no elaboration subprogram) must be directly visible from the current context or must be library units.
For C/C++, iIf the language_entity name given is a simple identifier, all functions and classes in the program are visible. Other C/C++ entities must be directly visible from the current context.
If the language_entity name has multiple definitions, it is overloaded. The debugger prints a diagnostic showing the alternatives. Retype the v command attaching a '1, '2, ... suffix (matching an alternative shown in the diagnostic) to the language_entity name to disambiguate it. Alternatively, sometimes it is sufficient to use an expanded name to disambiguate it.
Filenames
Filenames that contain only alphanumeric characters, dots and underscores do not need to be enclosed in quotes but those containing other characters must be enclosed in quotes. Enclosing a filename in quotes ("file.ada") often eliminates errors, if for example, part of the filename collides with a keyword or program variable.
In addition, the debugger interprets csh(1) and ksh(1) tilde notation or shell environment (exported) variables if the filename is enclosed in quotes,
v "$al/foo.ada"
v "~/tst/math.ada"
In Screen Mode
Invoke the v command by positioning the cursor on any character of a simple name and typing Control-]. This has the same effect as typing v language_entity in line mode —— the source window is rewritten with the source code corresponding to the named entity.
If the entity name is overloaded, the debugger prints a diagnostic showing the alternatives. Retype the Control-] command preceding it with a number (matching an alternative shown in the diagnostic) to disambiguate it. That is, typing a number n before Control-] has the same effect as typing v language_entity'n in line mode.
Each v or Control-] command pushes the current position onto a "tag stack". You can pop the tag stack using Control-]. Each Control-] pops one position off the tag stack, and shows you that position in your source window.
Use v in screen mode by preceding it with : and following with Return.
vb
Move source location to breakpoint
Syntax
vbbreakpoint_number
Arguments
- breakpoint_number
Integer identification number of desired breakpoint. These numbers are displayed using the lb command.
Description
The vb command moves the current source location to the source location of the breakpoint indicated by breakpoint_number. The list of breakpoints and their corresponding breakpoint numbers is displayed using the lb (list breakpoints) command. For example,
>lb [1] "/usr1/tut/convert_b.ada":55 in get_date_rep [2] "/usr1/tut/convert_b.ada":33 in month_no >vb 2
moves the current source location to line 33 in convert_b.ada.
Note that both active and inactive breakpoints can be visited.
In Screen Mode
Precede this command with : and follow with Return.
edit
Syntax
edit [language_entity
|language_source_file
]
Arguments
- language_entity
Name of an Ada or C/C++ entity such as a subprogram, package, task (Ada), function, class (C/C++), type, variable, constant, etc.
- language_source_file
Name of an Ada or C/C++ source file. This file must in a directory on your Adapath (Ada) or source path (C/C++). Note that for C/C++, all filenames must be enclosed in quotation marks.
Description
edit invokes the editor with the specified file or the file containing the specified entity. If no parameter is given, the file containing the current position is used.
The debugger consults the environment (exported) variable Editor for the name of the editor. If Editor is not defined, the debugger uses vi as the editor.
The parameters are interpreted exactly as they are for the e command.
In Screen Mode
Precede this command with : and follow with Return.
Call StackTo represent the current state of the program being debugged, the debugger uses a model known as the call stack. The call stack represents all currently active subprograms (Ada) or functions (C/C++) in the program being debugged. These are subprograms (Ada) or functions (C/C++) that have been called but have not returned to their caller. When the program executes, the subprogram (Ada) or function (C/C++) that is currently executing is at the top of the call stack. A subprogram (Ada) or function (C/C++) call `pushes' the called subprogram (Ada) or function (C/C++) on top of the stack. When a subprogram (Ada) or function (C/C++) returns to its caller, the returning subprogram (Ada) or function (C/C++) is `popped' from the top of the stack.
For Ada, the call stack for a task can serve as a record of that task's flow of control. When a subprogram is called or activated in a given task, a frame for that call is pushed onto the appropriate stack. The top frame in a stack always contains a reference to the most recently called subprogram in the task. The debugger can retrieve and display information stored in call stack frames.
When the program stops, the debugger initializes two `positions' —— the home position (execution position) and the current position (viewing position). The home position represents where the program executes next (or where the program is executing) at the current level of the call stack. The current position represents that part of the source code seen on the terminal at this moment. The viewing position changes as debugger commands display different source files or disassemble parts of the program. The execution position only changes when moving up and down the call stack. When the execution position changes, the viewing position changes to match it.
When you want to display or modify the value of an object such as a variable, you must reference a stack frame. When a debugger command makes a reference to a subprogram (Ada) or function (C/C++)-relative object such as a variable, that object must be bound to a particular frame. That is, the value of an object in a given subprogram (Ada) or function (C/C++) must be referenced relative to a particular frame that contains a particular activation for that subprogram (Ada) or function (C/C++). Normally, the focus is used to determine this relationship, but you can also explicitly name a frame.
Displaying the Call Stack
When you are debugging a program with the Apex debugger, you can display the program's call stack using one of the following methods. If necessary, stop the program execution with the Debug > Stop or stop command.
Request the Stack window by any of the following methods:
- Execute Debug > Window > Stack in an editor window.
- Execute Windows > Stack in any debugger window.
- Enter cs in the Command pane or from the non-GUI debugger. If this command is used from the GUI, the call stack is displayed in the Log area of the debugger window.
When a program consists of multiple tasks, each task maintains its own stack and these stacks can be displayed individually. When you display the Stack window, you get the stack associated with the current context. Context is described in Context of Debugger Commands.
When the Stack window is visible, it displays the task selected by the current context. The current context is the frame highlighted in the Stack window.
By default, the current frame is the topmost frame of whatever task has been stopped by the debugger. However, you can change the current context by selecting a different frame in the current task's stack or by selecting a different task in the Tasks window.
The Stack window displays the frames in the execution stack with the current focus being displayed at the top. Each frame row has the following format:
If the full stack is not displayed, use the Extend Down and Extend Up buttons to display the rest of the call stack.
cs
Syntax
cs [reg] [number
] [intask
]
cs [reg] [number
]
Arguments
- number
- reg
Provide hexadecimal dump information.
- task (Ada only)
Task identifier. This identifier is in the Addr column of output from the lt command.
Description
cs displays the call stack, starting with the current frame. number is the topmost number of frames to display (0 means all). The in task clause displays the call stack for the specific task identified with the task identifier.
# line procedure params 1 63 get_date_rep (date="January 1, 1900") 2 20 test_single_date (date="January 1, 1900") 3 44 test_convert ()
The leftmost column of the display contains a number for each frame. Use this number with the cd and cu commands. Frames that correspond to inline expansions are marked with a + character immediately after the frame number.
Listing of the parameters is controlled by the list_params[on|off] option. Parameters are listed by default. If you want a quicker stack listing which does not include the parameters, set this option to off (set list_params off).
You can display either simple or expanded names with the cs command. This is controlled through the expanded_names [on|off] debugger configuration parameter. For example, with the default setting of set expanded_names off the output of cs is as follows:
# line procedure params 1 929 put'4 (file=0f1bc0, item="^[[6;44H ") 2 951 put'5 (item="^[[6;44H ") 3 103 put'1 (item=<NOT ACTIVE>ARRAY, pos=RECORD) 4 132 output TASK BODY 5 280 phl ()
However, with set expanded_names on the output of cs now includes expanded names:
# line procedure params 1 929 text_io.put'4 (file=0f1bc0, item="^[[6;44H ") 2 951 text_io.put'5 (item="^[[6;44H ") 3 103 phl.output.put'1 (item=<NOT ACTIVE>ARRAY, pos=RECORD) 4 132 phl.output TASK BODY 5 280 phl ()
Other stack commands are cb, cd, cu and ct.
If the keyword reg is used, an extra three-line hexadecimal dump is provided per frame. The first line shows the values of the PC, FP and AP registers. (On most machines, the FP and AP registers are the same register). The second line displays a row of 32-bit words, starting with the word pointed to by FP and then moving down to lower addressed words. The third line displays a row of 32-bit words, starting with the word pointed to by the AP and then moving up, to higher addressed words.
For Apex Cross systems, when printing the call stack over an interrupt handler, an ! can appear in the left column of the output. For example, if a breakpoint is set in the interrupt handler and the program is run, the breakpoint is announced:
>b 124 >r [1] stopped at "/vc/wheels/xtst/rtst/nested_isr.a":124 in timer_handler nested_cnt := nested_cnt + 1
Then cs displays the call stack:
>cs # line procedure params 1 124 timer_handler () !2 123 timer_isr () 3 169 trap_handler () !4 123 trap_isr () 5 214 do_trap () 6 218 traps TASK_BODY 7 53 nested_isr_package..BODY PACKAGE
The ! in the left column of the call stack display indicates that the debugger has performed some heuristics to find the routine that caused the interrupt. In the above example, trap_isr executes a trap instruction that trap_handler handles. While the trap_handler executes, a timer interrupt occurs that timer_handler handles.
In Screen Mode
Type cs in screen mode; pressing Return afterward is not necessary. However, in screen mode the number parameter precedes the cs (unlike line mode where the number follows cs). For example, to see the top three frames of the call stack in screen mode, type 3cs.
Navigating the Call Stack
It is possible to navigate to any of the frames listed on the call stack. In the GUI, sSimply select the frame you wish to go to and select Visit. In the Command Pane, or non-Gui debugger the following commands are available for navigating the call stack:
cb Move to bottom frame of call stack
cd Move down on call stack
ct Move to top frame of call stack
cu Move up on call stack
cb
Move to the call stack bottom frame
Syntax
cb
Description
cb moves both the current position and the current frame to the bottom or lowest frame on the call stack. This is the frame corresponding to the main program.
The call stack is represented with the breakpointed subprogram (Ada) or function (C/C++) at the top of the stack. Use cs to display the call stack.
The debugger prints a one-line display corresponding to the new current frame. This line is the same line that the cs command displays for the frame: to the left is the frame number, followed by the name of the subprogram, package, task (Ada), function or class (C/C++) that the frame represents, followed by the names and values of actual parameters, if any. Inline frames are marked with a + character immediately after the frame number.
Use cb to see local variables and parameters in the bottom frame of the call stack.
In Screen Mode
Type cb to move to the bottom of the stack in screen mode. Pressing Return afterward is not necessary.
In response to the command in screen mode, the debugger displays the source code surrounding the new home position in the source window. The one-line display mentioned above is shown in the command window.
cd
Syntax
cd [name
|number
]
Arguments
- name
Name of a frame on the call stack.
- number
Number of a frame on the call stack. If number is 0, cd moves the current position to the home position in the current frame. This is useful after moving away from the current frame, for example, in a new file with the e command. The * command is a synonym for cd 0.
Description
cd moves the current position down one frame on the call stack. If name or number is specified, the current position moves down to the next frame on the call stack with that name or number. (This moves in either direction —— up or down). The cs command displays the contents of the stack, starting with the current frame and shows the frame numbers.
The call stack is represented with the breakpointed subprogram (Ada) or function (C/C++) being at the top of the stack. The call stack is displayed with the cs command, starting with the current frame. Each frame is shown with its number. cd moves down to the frame of the procedure that called the top frame.
After the cd command executes, the new frame becomes the current frame and the line executing in that frame becomes the home position. The line containing the current home position is always marked with * when it is displayed on the screen in screen mode or by a display command (l, li, w, wi) in line mode.
After executing the cd command, the debugger prints a one-line display corresponding to the new current frame. This line is the same line that the cs command displays for the frame: to the left is the frame number, followed by the name of the subprogram, package, task (Ada), function or class (C/C++) that the frame represents, followed by the names and values of actual parameters, if any. Inline frames are marked with a + character immediately following the frame number.
To display the values of local variables and parameters of a procedure currently active on the call stack, move the current frame to that frame on the stack. This makes the local variables visible.
In Screen Mode
Type cd in screen mode. Pressing Return afterward is not necessary.
The name option cannot be used directly in screen mode but the number option is supported. However, the number parameter must precede cd (unlike line mode where the number follows cd). For example, to move to stack frame 5 on the call stack in screen mode, type 5cd.
In response to the command in screen mode, the debugger displays the source code surrounding the new home position in the source window. The one-line display mentioned above is shown in the command window.
ct
Move to the call stack top frame
Syntax
ct
Description
ct moves the current frame and current position to the top of the stack that is also the breakpointed frame. When a process breakpoints, the current position is initialized to the top of the stack. Use cs to display the call stack.
The debugger prints a one-line display corresponding to the new current frame. This line is the same line that the cs command displays for the frame, to the left is the frame number, followed by the name of the subprogram, package, task (Ada), function or class (C/C++) that the frame represents, followed by the names and values of actual parameters if any. Inline frames are marked with a + character immediately following the frame number.
Local variables and parameters of the subprogram (Ada) or function (C/C++) at the top of the call stack are made visible with ct.
In Screen Mode
Type ct to move to the top of the stack in screen mode; pressing Return afterward is not necessary.
In response to the command in screen mode, the debugger displays the source code surrounding the new home position in the source window. The one-line display mentioned above is shown in the command window.
cu
Syntax
cu [name
|number
]
Arguments
Description
cu moves up one frame on the call stack. If name or number is provided, cu moves up to the next frame on the call stack with that name or number.
The new frame becomes the current frame and the line executing in that frame becomes the current home position, marked with *.
The debugger prints a one-line display corresponding to the new current frame. This line is the same line that the cs command displays for the frame: to the left is the frame number, followed by the name of the subprogram (Ada) or function (C/C++) that the frame represents, followed by the names and values of actual parameters, if any. Inline frames are marked with a + character immediately following the frame number.
Use cu 0 or * to move to the home position in the current frame. This is helpful after moving into a new file using the v command.
In Screen Mode
Type cu in screen mode; pressing Return afterward is not necessary. The name option cannot be used in screen mode but the number option is supported (however the number parameter precedes cu instead of following it as in line mode). For example, to move to stack frame 5 on the call stack in screen mode, type 5cu.
In response to the command in screen mode, the debugger displays the source code surrounding the new home position in the source window. The one-line display mentioned above is shown in the command window.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |