Setting traps is one of the most important functions of a debugger or performance analyzer. A trap enables you to select a location or condition within your program at which you can stop the process or collect performance data automatically. In general, you set or clear traps from Main View (Source View) or the Trap Manager. You can also specify traps in the Debugger command line at the bottom of the Main View window. For signal traps, you can also use the Signal Panel window. For system call traps, use the Syscall Panel window.
When you are debugging a program, you typically set a trap in a process to determine if there is a problem at that point. WorkShop lets you inspect the call stack, examine variables, or perform other procedures to get information about the state of the process.
Traps are also useful for analyzing a program's performance. They let you collect data related to resource usage without stopping the process.
This chapter covers the following topics:
For a tutorial on the use of traps, see "Setting Traps".
In WorkShop, the term trap refers to any intentional process interruption. A trap has two dimensions: the trigger, which specifies when the trap fires, and the action taken when the trap fires, either stopping the process or capturing data.
When used as a verb, the term trigger refers to engaging a trap but not necessarily firing it. There are some circumstances where the process may hit a trap but not satisfy all the conditions necessary for firing it.
You can set traps at a specified location or when a specified event occurs. The triggers provided in WorkShop are
at a given line in a file (traditionally referred to as "breakpoints")
at a given instruction address
at the entry or exit for a given function
after set time intervals (referred to as "pollpoints")
when a given variable or address is read, written, or executed (referred to as "watchpoints")
when a given signal is received
when a given system call is entered or exited
Furthermore, you can specify a condition (as an expression) that must be met before a trap fires. You can also specify the cycle count, that is, a specific number of passes through a trap without firing it.
Two actions can occur when a trap is fired:
one or all processes can be stopped
a sample of performance data can be taken
A trap that stops processes is called a stop trap, or a breakpoint. A trap that collects performance data is called a sample trap.
In single process debugging, a stop trap stops the current process. In multiprocess debugging, you can specify the stop trap to stop all processes or the current process only.
Sample traps are used only in performance analysis, not directly in debugging. They collect data without stopping the process. You can specify sample traps to collect such information as call stack data, function counts, basic block counts, PC profile counts, mallocs/frees, system calls, and page faults. Sample traps can use any of the triggers that stop traps use. Sample traps are often set up as pollpoints so that they collect data at set time intervals.
You can set traps directly in Main View by using the Traps Menu or by clicking the mouse in the source annotation column. You can also specify traps in the Debugger command line.
The Traps Menu in Main View is shown in Figure 4-1.
To set a trap using the Traps menu, you need to identify where the trap is to be located and its type.
To set a stop trap at a line displayed in Main View (or Source View), click the cursor in the source annotation column next to the appropriate line in the source code and select "Set Trap," then "Stop" or "Sample."
For a trap at the beginning or end of a function, highlight the function name in the source code display area and select "Set Trap," then "Stop At Function Entry," "Stop At Function Exit," "Sample At Function Entry," or "Sample At Function Exit," as appropriate.
The traps are indicated by icons in the source annotation column (and also appear in Trap Manager if you have it open). Figure 4-2 shows some typical trap icons. Sampling is indicated by a dot in the center of the icon. Traps appear in normal color or grayed out, depending on whether they are active or inactive. A transcript of the trap activity appears in the Debugger command line area. The active/inactive nature of traps is discussed in "Enabling and Disabling Traps."
The "Clear Trap" selection in the Traps menu deletes the trap on the line containing the cursor. You must designate a "Stop" or "Sample" trap type, since both types can exist at the same location, appearing superimposed on each other.
The quickest way to set a trap is to click in the source annotation column in Main View and Source View. A subsequent click removes the trap. When the trap is set, an icon appears representing the trap. If data collection mode has been specified in the Performance Data window, clicking produces a sample trap; otherwise, a stop trap is entered. (The way to tell if data collection is on is to look at the Debug option menu in the upper-right corner of the Debugger main view, and see whether it is set to "Debug Only," "Performance," or "Purify.")
The Trap Manager helps you manage all the traps involved with a process. Its two major functions are to list all traps in the process (except signals) and to let you add, delete, modify, or disable traps. The Trap Manager appears in Figure 4-3 with the Config, Traps, and Display menus displayed.
New or modified traps are entered in the Trap: field. They have the general form:
[stop | sample] [all] [pgrp] <location | condition> |
The entry [stop | sample] refers to the trap action. You can set a default for it in the Traps menu ("Stop Trap Default" or "Sample Trap Default") and omit entering it at the beginning of the specification.
The entries [all] and [pgrp] are used in multiprocess analysis. The [all] entry causes all processes in the process group to stop or sample when the trap fires. The [pgrp] entry sets the trap in all processes within the process group that contains the code where the trap is set. These will be entered by default if the "Stop All Default" and "Group Trap Default" toggles in the Traps menu are on.
The specific syntaxes for the location and condition are shown below. After you enter the trap (by the Add or Modify button or by <Enter>), the full syntax of the specification appears in the field. The Clear button clears the Trap and Condition fields and the cycle fields.
Some typical trap examples are provided in Figure 4-4. The entries made in the Trap field are shown in the left portion of the figure, the trap display in Trap Manager resulting from these entries is shown on the right, and the trap display shown at the command line in Main View is shown at the bottom.
The Condition: field lets you specify a condition necessary for the trap to be fired. A condition can be any legal expression and will be true if it returns a nonzero value when the corresponding trap is encountered. The expression must be valid in the context in which it will be evaluated. For example, a Fortran condition like a .gt. 2 cannot be evaluated if it is tested while the program is stopped in a C function.
There are two possible sequences for entering a trap with a condition:
Define the trap.
Define the condition.
Click Add.
and
Define the trap.
Click Add.
Define the condition.
Click Modify or press <Enter>.
An example of a trap with a condition is shown in Figure 4-4. The expression i==1 has been entered in the Condition: field. (If you were debugging in Fortran, you would use the Fortran syntax, for example,
i .eq. 1.) After the trap has been entered, the condition appears as part of the trap definition in the display area. During execution, the requirements set by the trigger must be satisfied first for the condition to be tested. A condition is true if the expression (valid in the language of the program you are debugging) evaluates to a nonzero value.
The Cycle Count field lets you pass through a trap a specific number of times without firing. If you set a cycle count of n, the trap will fire at the nth time the trap is encountered and every n iterations thereafter. The Current Count field indicates the number of times the process has passed the trap since either the cycle count was set or the trap last fired. The current count updates only when the process stops.
The Traps menu in Trap Manager (see Figure 4-5) lets you specify traps in conjunction with Main View or Source View. Clicking "At Source Line" sets a trap at the line in the source display area containing the current selection.
To set a trap at the beginning or end of a function, you select the function name in the source display and then click "Entry Function" or "Exit Function." The trap set in all of these cases is governed by the defaults you have set in the menu.
The trap display area shows all traps set for the current process. You have vertical and horizontal scroll bars for moving around the display area. The Search field lets you incrementally search for any string in any trap.
Each trap has an indicator to its left for toggling back and forth between its active and inactive states. This feature lets you accumulate traps and turn them on only as needed. Thus, when you don't need the trap, it won't get in your way. When you do need it, it is readily re-enabled.
You can trap signals using Signal Panel and system calls using Syscall Panel (see Figure 4-6).
Both are selected from the Views menu in Main View. Signal Panel sets a trap on receipt of the signal(s) selected. Syscall Panel sets a trap at the selected entry to or return from the system call.