The pop command removes one or more execution frames from the call stack. The pop command undoes the work already done by the removed execution frames. It does not, however, reverse side effects such as changes to global variables. You may need to use the assign command to restore the values of global variables.

The pop command is useful when execution has already passed an error that needs to be corrected.

The following fragment of a debugger session shows the use of the pop command:

Reading symbolic information ...done (ladebug) bp factorial [#1: stop in int factorial(int) ] (ladebug) r Factorial time has begun. [1] stopped at [factorial:30 0x120001524] 30 printf("entered factorial\n"); (ladebug) where >0 0x120001524 in factorial(ii=1) c_listfunc_factorial.c:30 #1 0x12000140c in main() c_listfunc.c:41 (ladebug) pop [1] stopped at [main:41 0x120001410] 41 f = factorial(i); (ladebug) c [1] stopped at [factorial:30 0x120001524] 30 printf("entered factorial\n");

3.2.8 Attaching to a Running Process

To attach or detach a running process, choose Commands:Attach to Process... or Detach from Process... and select the process.

From the command interface, use the attach command followed by the process ID and image file name.

After Ladebug attaches to a process, control is returned to the debugger when the process stops (for example, after having received a signal). You can also manually return control to the debugger by pressing Ctrl/C or by setting the debugger variable $stoponattach to 1 to stop the attached process.

Use the detach command to detach the debugger from the previously attached process, based on the process ID you specify. Ladebug only detaches the specified process and removes all the user-specified breakpoints from that process.

The following restrictions apply when you debug an attached process:

• In the context of an attached process, the run and rerun commands are disabled.
• The quit command will terminate any process Ladebug created when invoking the debugger with an image file or when using the load image_file command. If it is attached to any process, Ladebug will detach itself from the process.

See Chapter 9 for more information about multiple processes.

3.3 Setting Breakpoints to Suspend Execution

This section is divided into the following parts:

• Identifying currently set breakpoints
• Setting breakpoints on source lines
• Setting breakpoints on routines with the source browser
• Activating, deactivating, and deleting breakpoints
• Setting and modifying conditional breakpoints
• Setting and modifying action breakpoints

A breakpoint is a location in your program at which you want execution to stop so that you can perform some action such as checking the current value of a variable, stepping into a routine, etc. You can set breakpoints on:

• Specific source lines
• Specific routines (for example, functions, subprograms)
• Specific instructions (displayed in the Instruction View--see Section 2.4)

A breakpoint with no condition associated with it can be set by using the Break menu, but it is often simpler to click on the toggle push button in the source display.

You can also qualify breakpoints as follows:

• You can set a conditional breakpoint which triggers only when a specified relational expression is evaluated as true.
• You can set an action breakpoint which executes one or more specified system-specific commands when the breakpoint triggers.

You can set a breakpoint that is both a conditional and an action breakpoint. The following sections explain these breakpoint options.

3.3.1 Identifying Currently Set Breakpoints

There are three ways to determine which breakpoints are currently set:

• Choose Views:Manage Views... on the Main or Manage View Window. The Manage Views dialog box appears with toggles for all the views. You can either toggle Breakpoint View or you can select Breakpoint View directly from the Views menu. Breakpoints are listed in the Breakpoint View display. A filled-in button in the State column indicates that the breakpoint is set and active. A cleared button indicates that the breakpoint is deactivated.
  Double clicking on an entry in the Breakpoint View expands the one-line entry into a description of the action and condition (if any) that are currently associated with the breakpoint, whether or not the breakpoint is active or deactivated (see Figure 3-1).

  Figure 3-1 Breakpoint View with Action and Condition

  ---

  
• Scroll through your source or instruction code and note the lines whose breakpoint button is filled in. This method can be time consuming and also does not show which breakpoints were set and then deactivated (see Section 3.3.2.2).
• You can use the status command in the command interface to display active breakpoints.

Example 3-9 uses the status command to display active breakpoints in a COBOL program.

Example 3-9 Using the status Command to Display Breakpoints

(ladebug) status #1 PC==0x120001e14 in testa "testa.cob":2 {break} #2 PC==0x120001ba4 in TESTB "testa.cob":47 {break} #3 PC==0x120001c1c in TESTB "testa.cob":50 {print CHARS of HOLD-CHARS; print SUB-1; ; cont ; ; }

3.3.2 Setting Breakpoints on Source Lines

You can set a breakpoint on any source line that has a toggle button to its left in the source pane. These are the lines for which the compiler has generated executable code (for example, routine declarations, assignment statements).

To set a breakpoint on a source line:

1. Find the source line on which you want to set a breakpoint (see Section 2.1).
2. To set the breakpoint, do one of the following:
   • Click on the toggle button to the left of that line.
   • Select the Toggle Breakpoint at line [line number] item in the pop-up menu in the annotation area or source display.
   • Select the Temporary Breakpoint at line [line number] item in the pop-up menu in the annotation area or source display.
   • Select the Toggle pop-up menu item in the Breakpoint View to activate or deactivate a selected breakpoint.
   • Enter the stop at or stop in commands at the command prompt.
   • Use the Source Browser.
   
   The breakpoint is set when the button is filled in. The breakpoint is set at the start of the source line---that is, on the first machine-code instruction associated with that line.

Figure 3-2 shows that a breakpoint has been set on the start of line 14.

Figure 3-2 Setting a Breakpoint on a Source Line

To set a breakpoint in the Instruction View:

1. In the Instruction View, find the instruction on which you want to set a breakpoint.
2. Click on the toggle button to the left of that line. (The breakpoint is set when the toggle button is filled in.)

Table 3-1 lists the commands you can use in the command interface for setting breakpoints.

Table 3-1 Commands for Setting Breakpoints

Command	Description
stop	Without a variable argument, suspends program execution and returns to the prompt. With a variable argument, suspends program execution when a variable changes.
stop at	Suspends execution when a specific line number is encountered.
stop in	For C++ programming; see the Command Reference for specific forms of this command.
stop if	Suspends execution when an expression evaluates to true.
stopi, stopi if, stopi at	For machine-level debugging; suspends program execution when the specified variable value changes, when an expression evaluates to true, or when a specified address is encountered.

Example 3-10 shows how to set a breakpoint on a variable.

Example 3-10 Setting a Breakpoint on a Variable

(ladebug) stop i [#2: stop if i changes ] (ladebug) run [1] stopped at [main:4 0x120000b14] 4 for (i=1 ; i<3 ; i++) { (ladebug) print i 0 (ladebug) cont Value of i changed before "sample.c":13 Old value = 0 New value = 1 [2] stopped at [factorial:13 0x120000bb8] 13 if (i<=1) (ladebug) print i 1 (ladebug)

Example 3-11 sets a breakpoint at line number 13 of the current source file.

Example 3-11 Setting a Breakpoint at a Line in C Source Code

(ladebug) stop at 13 [#1: stop at "sample.c":13 ] (ladebug) run [1] stopped at [factorial:13 0x120001224] 13 if (i<=1) (ladebug)

Example 3-12 Setting a Breakpoint at an Address in the Source Code

(ladebug) stopi at 0x120000b14 [#1: stopi at 4831841044 ] (ladebug) run [1] stopped at [main:4 0x120000b14] 4 for (i=1 ; i<3 ; i++) { (ladebug)

Example 3-13 shows how to set a breakpoint in a function.

Example 3-13 Setting a Breakpoint in a Function

(ladebug) stop in factorial [#1: stop in factorial ] (ladebug) run [1] stopped at [factorial:13 0x120001224] 13 if (i<=1) (ladebug)

In Example 3-14 the stop in command sets a breakpoint at the beginning of an Ada program procedure named add_integers.

Example 3-14 Setting a Breakpoint at the Start of an Ada Procedure

(ladebug) stop in add_integers [2] stop in add_integers (ladebug)run [2] stopped at [add_integers:3 +0x20002a69,0x120002a68] procedure add_integers is

Example 3-15 shows how to set a breakpoint with a user-defined expression.

Example 3-15 Setting a Conditional Breakpoint

(ladebug) stop if (iter==2) [#1: stop if iter==2 ] (ladebug) run [1] stopped at [doit:20 0x120000e14] 20 ++iter; (ladebug) print iter 2 (ladebug)

In this example, the breakpoint is activated only when the program variable iter equals 2.

Example 3-16 creates a breakpoint that stops only if the program is executing the factorial function and the program variable i is equal to 2.

Example 3-16 Setting a Conditional Breakpoint in a Function

(ladebug) stop in factorial if (i==2) [#1: stop in factorial if i==2 ] (ladebug) run 1! = 1 [1] stopped at [factorial:13 0x120000bb8] 13 if (i<=1) (ladebug) print 2 (ladebug)

3.3.2.2 Deactivating (Disabling) and Activating (Enabling) Breakpoints, Tracepoints, and Watchpoints

Within the debugger, the terms deactivate and activate are synonymous with disable and enable. Deactivate and activate are used in the GUI; disable and enable are used in the command interface.

Deactivating a breakpoint causes the debugger to ignore the breakpoint during program execution. However, the debugger keeps the breakpoint listed in the Breakpoint View so that you can activate it at a later time, for example, when you rerun the program (see Section 1.6.6). The following are procedures to deactivate or activate breakpoints:

• To deactivate or activate a specific breakpoint, toggle the button for that breakpoint in the source display, the instruction code display, or in the Breakpoint View.
  In the Breakpoint View, you can also choose Break:Toggle or press MB3, if the breakpoint is currently enabled.
• To deactivate or activate all breakpoints, choose Break:Deactivate All or Break:Activate All on the Instruction View or Optional Views Window.

You can enter commands in the command interface to enable and disable breakpoints, tracepoints, (see Section 3.4) and watchpoints (see Section 3.5). It is written in terms of breakpoints but all of these commands are also applicable to tracepoints and watchpoints.

To list all the breakpoints known to the debugger, enter the status command.

To delete, disable, or enable a breakpoint, identify the breakpoint by its reference number. When breakpoints are created, they are associated with a reference number. This reference number is shown when:

• The debugger confirms the creation of a new breakpoint
• The breakpoint is encountered
• You list all of the breakpoints with the status command

When you disable a breakpoint, the debugger ignores the breakpoint during program execution. A disabled breakpoint does not cause the program to suspend execution.

You can use the disable and enable commands in the command interface to disable and enable breakpoints.

The disabled breakpoint is still displayed by the status command, but it is listed as disabled. Example 3-17 shows breakpoints being disabled.

Example 3-17 Disabling Breakpoints

(ladebug) status #1 PC==0x120000b14 in main "sample.c":4 { break } #2 PC==0x120000bb8 in factorial "sample.c":13 { break } #3 PC==0x120000b14 in main "sample.c":4 { break } (ladebug) disable 1 (ladebug) status #1 PC==0x120000b14 in main "sample.c":4 { break } Disabled #2 PC==0x120000bb8 in factorial "sample.c":13 { break } #3 PC==0x120000b14 in main "sample.c":4 { break } (ladebug) disable 2,3 (ladebug) status #1 PC==0x120000b14 in main "sample.c":4 { break } Disabled #2 PC==0x120000bb8 in factorial "sample.c":13 { break } Disabled #3 PC==0x120000b14 in main "sample.c":4 { break } Disabled (ladebug)

Disabled breakpoints remain disabled until you enter the enable command to enable the breakpoint.

Example 3-18 shows the breakpoints that were disabled earlier and then reactivated with the enable command.

Example 3-18 Enabling Breakpoints

(ladebug) status #1 PC==0x4001b8 in main "sample.c":4 { break } Disabled #2 PC==0x400250 in factorial "sample.c":13 { break } Disabled #3 PC==0x4001b8 in main "sample.c":4 { break } Disabled (ladebug) enable 2 (ladebug) status #1 PC==0x4001b8 in main "sample.c":4 { break } Disabled #2 PC==0x400250 in factorial "sample.c":13 { break } #3 PC==0x4001b8 in main "sample.c":4 { break } Disabled (ladebug) enable all (ladebug) status #1 PC==0x4001b8 in main "sample.c":4 { break } #2 PC==0x400250 in factorial "sample.c":13 { break } #3 PC==0x4001b8 in main "sample.c":4 { break } (ladebug)

A breakpoint that has been reactivated with the enable command appears as an active breakpoint in the status list. Note that the last status list in this example is the same as the first status list in the preceding example (except for the PC values), showing three active breakpoints.

3.3.3 Setting Breakpoints on Routines

The Browse Source dialog box displays hierarchical information about all the binary files in your application. For each binary file, it displays information about the modules contained in the binary. For each module, you can display a list of routines in that module.

Setting a breakpoint on a routine enables you to move execution directly to the routine and inspect the local environment.

To set a breakpoint on a routine:

1. Choose File:Browse Source... on the Main Window (see Figure A-1). The Browse Source dialog box appears, listing your program file.
2. Double click on the name of your program file. The names of any additional source files required for compilation are displayed (indented) under the program name.
3. Double click on the name of the file where you want to set a breakpoint. The names of the routines in that file are displayed in the Routine column (see Figure 3-3).
4. Do one of the following:
   • Double click on the name of the routine on which you want to set a breakpoint.
   • Click on the name of the routine and then on the Set Breakpoint button.
     Either of these actions sets a breakpoint at the start of the routine (directly after any prolog code).

In the source pane, the toggle button to the left of the source line that contains the start of the routine is now filled in, confirming that the breakpoint is set. (If the Instruction Window is open, the breakpoint will also display for the corresponding instruction.)

Figure 3-3 Setting a Breakpoint on a Routine

A conditional breakpoint suspends execution only when a specified expression is evaluated as true. For example, you can specify that a breakpoint take effect when the value of a variable in your program is 4. The breakpoint is ignored if the value is other than 4.

The debugger evaluates the conditional expression when the breakpoint triggers during execution of your program.

To set a conditional breakpoint:

1. Display the source or instruction line on which you want to set the conditional breakpoint (see Section 2.1).
2. Display the Set/Modify Breakpoint dialog box in one of the following ways:
   • Press Ctrl/MB1 on the button to the left of the source line, an instruction line, or a breakpoint entry in the Breakpoint View or press MB3 in the annotation area. This causes the Set/Modify Breakpoint dialog box to appear, which shows the source line you selected in the Location: field (see Figure 3-4).
   • Select a breakpoint entry in the Breakpoint View on the Manage Views window. Press MB3 to access the Breakpoint pop-up menu and choose Set/Modify. The Set/Modify Breakpoint dialog box appears with the location of the source line showing in the Location field.
   • Choose Break:Set... (Instruction Window) or Break:Set/Modify (Optional Views Window). When the Set/Modify dialog box appears, enter the location in the Location field, as shown in the following examples:

     at line 10 in factorial.c in routine seven at address 0x01024b

3. Enter a relational expression in the Condition: field of the dialog box. The expression must be valid in the source language. For example, a[3] :=,= 0 is a valid relational expression in the C language.
4. Click on OK. The conditional breakpoint is now set. The debugger indicates that a breakpoint is conditional by changing the shape of the breakpoint's button from a square to a diamond.

Figure 3-4 Setting a Conditional Breakpoint

The following procedure modifies a conditional breakpoint; it can be used to change the location or condition associated with an existing conditional breakpoint, or to change an unqualified breakpoint into a conditional breakpoint:

1. Press Ctrl/MB1 on the button to the left of a source line, an instruction code line, or a breakpoint entry in the Breakpoint View.
2. Click on a breakpoint entry in the Breakpoint View, and choose the Set/Modify item from the Break menu.
3. Enter a relational expression in the Condition: field of the dialog box. The expression must be valid in the source language. For example, a[3] :=,= 0 is a valid relational expression in the C language.
4. Click on OK. The conditional breakpoint is now set. The debugger indicates that a breakpoint is conditional by changing the shape of the breakpoint's button from a square to a diamond.
5. Press MB3 over the breakpoint item in the Breakpoint View.

You can enter the when and wheni commands in the command interface to set breakpoints at function entry points that execute debugger commands, (rather than suspend program execution) when the specified conditions are satisfied.

Example 3-19 creates a breakpoint that prints a stack trace when line 16 is reached.

Example 3-19 Setting a Breakpoint That Executes a Stack Trace

(ladebug) when at 16 {where} [#1: when at "sample.c":16 { where } ] (ladebug) run 1! = 1 [1] when [factorial:16 0x12000123c] >0 0x12000123c in factorial(i=2) sample.c:16 #1 0x120001194 in main() sample.c:5 2! = 2 Thread has finished executing (ladebug)

Example 3-20 creates a breakpoint that displays the contents of the expression HOLD-CHARS and SUB-1 in a COBOL program when line 50 is reached and then resumes execution.

Example 3-20 Setting a Breakpoint That Executes Multiple Commands

(ladebug) when at 50 {print chars of hold-chars; print SUB-1; cont;} [#3 when at "testa.cob":50 ( print CHARS of HOLD-CHARS; print SUB-1; ; cont ; } ]