|
|
The Event menu in the debugger's default configuration allows the user to create events that will alter the control flow of a thread or process. Clicking MENU on the Event button brings up a menu with different options, depending on which panes are present in the window. The following options appear in the Event menu of one or more windows in the default configuration (remember that you can configure the Event menu to have different options, or can move these options to different menus):
The Cancel popup window lets you cancel any signals that are caught by the debugger. When a signal is posted to a process or thread, the debugger is notified before the process or thread receives it. Cancel allows you to get rid of the signal so the process or thread never sees it.
The popup window displays a scrolling list of the signals pending against the selected process or thread. The next time you let the process or thread run, it will not receive the signals you select from this list.
The signals in the list are ordered numerically by default. The list may be ordered alphabetically by selecting the Order list by Name option. The list of signals is searchable. See ``Searching in lists''.
If you popped up the Cancel window from a window containing a ``Process pane'' the signals displayed will be pending against the selected process or thread (if any) in the Process pane. Otherwise, the current process or thread is used.
In the debugger's default configuration, the Cancel option is available in the ``Event menu'' of every window.
The Change option provides a popup window that lets you edit an existing event. This option is available only if you have selected one event in the ``Event pane'', in either the Main Event area or the On Stop Event area. The popup window will look like one of the ``Stop'', ``Signal'', ``Syscall'', ``Exception'', or ``On Stop'' windows, depending on the type of the event you had selected. The fields in the window will be initialized with values from the selected event. You may then change any of the fields. When you finish, the changes you make will be reflected in the Event window.
The Change option may only be configured in windows that contain an ``Event pane''. In the debugger's default configuration, the Change option is available in the ``Event menu'' of the Event window.
The Delete Breakpoint option is available if you selected a source line with a stop sign on it in the ``Source pane'' or an instruction with a stop sign on it in the ``Disassembly pane''. The stop sign indicates that there is a breakpoint (a type of stop event) on that line or instruction. Clicking SELECT on the Delete Breakpoint option will remove the breakpoint and delete the event. You may also remove a breakpoint by clicking the SELECT button in the left margin of the line with the breakpoint.
The Delete Breakpoint option may only be configured in windows that contain a ``Source pane'' or a ``Disassembly pane''. In the debugger's default configuration, the Delete Breakpoint option is available in the ``Event menu'' of the Disassembly and Source windows.
The Destroy option sends the signal SIGKILL to the affected processes. This signal cannot be caught and causes the affected processes to terminate.
If you selected Destroy from a window containing a ``Process pane'' the processes (if any) selected in the Process pane will be affected. If nothing is selected, or if Destroy was selected up from a window that does not contain a Process pane, only the current process will be affected.
In the debugger's default configuration, the Destroy option is available in the ``Event menu'' of every window.
The Exception popup window lets you create an exception event. An exception event specifies an action to be executed whenever the processes or threads in the selected program throw or catch a specific type of exception.
You do not have to create an event simply to stop the process or thread when an exception is thrown or caught, since the debugger will do that by default. See ``Ignore Exceptions'' for details on turning that capability on and off.
You must enter a valid C++ type in the ``Type'' field. The debugger will halt the affected processes and threads when an exception of that type is thrown or caught, depending on which of the Throw or Catch options is selected. The actions for the event will apply to any assignment-compatible object, as specified by the C++ language definition. This includes derived classes and const-or-volatile qualified objects. You may also enter an ellipsis (...) to match any type.
You may enter, in the ``Commands'' field, an action for the debugger to perform when the event triggers. The action should be one or more of the commands available through the debugger's command-line interface. The results of executing the commands will be displayed in the Transcript area of the ``Command pane''.
If you popped up the Exception window from a window containing a ``Process pane'' the new event will apply to the selected programs (if any) in the ``Process pane''. Otherwise, the event applies to the current program or current process or thread.
By default, events apply to all the processes and threads derived from a program, not just the selected process or thread. If you want to change this behavior, use the ``Granularity'' popup window. The affected programs or processes are listed in the Programs line at the top of the popup window.
The event created by executing this command will be displayed in the Main Event pane of the ``Event pane''.
In the debugger's default configuration, the Exception option is available in the ``Event menu'' of every window.
By default, when an exception is thrown or caught, the debugger stops the process or thread and announces the occurrence of the exception. If you do not want the debugger to do this by default, you may tell it to ignore either throws, or catches, or both.
The Ignore Exceptions window gives you two choices for the defaults to display. The choices are:
In either case, you may change the action by selecting either item in the list (or both) and then selecting either the Ignore or Stop button.
If you popped up the Ignore Exceptions window from a window containing a ``Process pane'' the selected process or thread (if any) in the ``Process pane'' is affected when you choose Listed process. Otherwise, the current process or thread is affected.
In the debugger's default configuration, the Ignore Exceptions option is available in the ``Event menu'' of every window.
By default, when a signal is posted to a process or thread, the debugger intercepts (catches) the signal and announces its occurrence. You may then either cancel the signal (with the ``Cancel'') popup window, or run the process and let it receive the signal. If you do not want the debugger to intercept a particular signal, you may tell it to ignore that signal.
The Ignore Signals popup window lets you specify the debugger's action (either catch or ignore) for each signal. The window gives you two choices for the list of signals to display. The choices are:
In either case, the Ignore Signals window displays a scrolling list of signals with the either current action for the process or thread or the default debugger action. You may change the action by selecting one or more signals in the list.
The signals in the list are ordered numerically by default. The list may be ordered alphabetically by selecting the Order list by Name option. If you chose Listed process for the set of signals to affect, the list also includes the name of the signal handler registered by the program for each signal. The list of signals is searchable. See ``Searching in lists''.
If you popped up the Ignore Signals window from a window containing a ``Process pane'' the selected process or thread (if any) in the Process pane is affected. Otherwise, the current process or thread is affected.
In the debugger's default configuration, the Ignore Signals option is available in the ``Event menu'' of every window.
The Kill popup window lets you send a signal to a process or thread. The popup window displays a scrolling list of signals; you may select one signal from the list. The signals in the list are ordered numerically by default. The list may be ordered alphabetically by selecting the Order list by Name option. The list of signals is searchable. See ``Searching in lists''.
If you popped up the Kill window from a window containing a ``Process pane'', the signal will be sent to the processes and threads (if any) selected in the Process pane. If all threads of a process are selected, then you will be queried as to whether the signal should be sent to the parent process or each of the child threads. If nothing is selected, or if Kill was popped up from a window that does not contain a Process pane, the signal will be sent to the current process or thread. Note that signals cannot be sent to threads in the Off lwp or Suspended states.
In the debugger's default configuration, the Kill option is available in the ``Event menu'' of every window.
The On Stop popup window lets you create an onstop event. An onstop event specifies an action to be executed whenever an affected process or thread stops. Enter the action in the space labeled ``Commands''. The action should be one or more of the commands available through the debugger's command-line interface. Each time the process or thread stops, the commands are executed and the results displayed in the Transcript area of the ``Command pane''. Stopping includes single steps and stopping for another debugger event ( ``Signal'', ``Syscall'', ``Stop'', or ``Exception'').
If you popped up the On Stop window from a window containing a ``Process pane'' the new event will apply to the selected programs (if any) in the Process pane. Otherwise, the event applies to the current program or current process or thread.
By default, events apply to all the processes and threads derived from a program, not just the selected process or thread. If you want to change this behavior, use the ``Granularity'' popup window. The affected programs, processes or threads are listed at the top of the window.
The event created by executing this command will be displayed in the On Stop Event area of the ``Event pane''.
In the debugger's default configuration, the On Stop option is available in the ``Event menu'' of every window.
The Set Breakpoint option is available if you have selected a line in the ``Source pane'' or an instruction in the ``Disassembly pane'' and if the current process or thread is stopped. Clicking SELECT on this option will create a breakpoint (a type of stop event) in the current program or current process or thread. The event will be indicated by a stop sign on the selected line or instruction. The event will also be displayed in the Main Event area of the ``Event pane''. You may also set a breakpoint by clicking the SELECT button in the left margin of the selected line or instruction.
When attempting to set a breakpoint on a source line, the debugger will display a message if it is unable to set the breakpoint on the selected line. There are several reasons why it may not be able to set the breakpoint:
The Set Watchpoint option is available if you have selected one or more program variables in the ``Symbol pane''. Clicking SELECT on the Set Watchpoint option lets you set watchpoints on the selected variables.
A watchpoint is a type of stop event that tells the debugger to stop the program whenever the variable changes value. The debugger will create a separate stop event for each variable. The new events will be displayed, and may be deleted or disabled, in the ``Event pane''.
The Set Watchpoint option may only be configured in windows that contain a ``Symbol pane''. In the debugger's default configuration, the Set Watchpoint option is available in the ``Event menu'' of the Symbols window, and in the popup menu in the ``Symbol pane''.
The Signal popup window lets you create a signal event. A signal event specifies an action to be executed whenever the processes or threads in the selected program receive a particular signal.
You do not have to create an event simply to stop the process or thread when it receives a signal, since the debugger will do that by default. See ``Ignore Signals'' for details on turning that capability on and off.
The signals are displayed in a scrolling list. You must select one or more signals from the list. The signals in the list are ordered numerically by default. The list may be ordered alphabetically by selecting the Order list by Name option. The list of signals is searchable. See ``Searching in lists''.
You must enter, in the ``Commands'' field, an action for the debugger to perform when the event triggers. The action should be one or more of the commands available through the debugger's command-line interface. The results of executing the commands will be displayed in the ``Command pane''.
If you popped up the Signal window from a window containing a ``Process pane'' the new event will apply to the selected programs (if any) in the Process pane. Otherwise, the event applies to the current program or current process or thread.
By default, events apply to all the processes and threads derived from a program, not just the selected process or thread. If you want to change this behavior, use the ``Granularity'' popup window. The affected programs or processes are listed at the top of the popup window.
The event created by executing this command will be displayed in the Main Event area of the ``Event pane''.
In the debugger's default configuration, the Signal option is available in the ``Event menu'' of every window.
The Stop popup window lets you create a stop event. A stop event specifies some condition in the program's address space that will cause the debugger to stop the program's execution.
Enter a ``Stop expression'' on the ``Expression'' line. The debugger evaluates the stop expression continuously while the subject process or thread is running. The debugger will stop the process or thread when the expression becomes true.
You may enter, in the ``Commands'' field, an action for the debugger to perform any time the event triggers. The action should be one or more of the commands available through the debugger's command-line interface. The results of executing the commands will be displayed in the ``Command pane''
You may enter a number in the ``Count'' field to tell the debugger to let the event trigger that many times before halting the process or thread. After that, the process or thread will be halted on each occurrence of the event.
If text is selected in the ``Source pane'' or ``Disassembly pane'' the ``Location'' field will be initialized with the line number or location of the selection.
If you popped up the Stop window from a window containing a ``Process pane'' the new event will apply to the selected programs (if any) in the Process pane. Otherwise, the event applies to the current program or current process or thread.
By default, events apply to all the processes and threads derived from a program, not just not just the selected process or thread. If you want to change this behavior, use the ``Granularity'' popup window. The affected programs or processes are listed at the top of the popup window.
The event created by executing this command will be displayed in the Main Event area of the Event pane.
In the debugger's default configuration, the Stop option is available in the ``Event menu'' of every window.
Stop Expressions are special expressions accepted by the ``Stop'' command. A stop expression consists of one or more stop-events, joined by the special && (and) or || (or) operators. These operators are left-associative, but the debugger does not guarantee the order in which their operands are evaluated.
Each type of stop event has some action that will cause the event to be noticed by the debugger. When such an action occurs, the entire stop expression is evaluated for "truth". If true, the event triggers in the normal way (the debugger will inform you of the event and execute any associated commands). The three types of stop events are:
Locations are used in the
``Create'',
``Stop'',
``Jump'',
and
``Run Until''
popup windows.
The syntax for a location is:
[thread_id@][object@][compilation_unit@][header_file@]line
or [thread_id@][object@][compilation_unit@][header_file@]symbol[+-constant]
or [thread_id@][object@]address[+-constant]
or [thread_id@]register_name
where address is an octal or hexadecimal program address, and constant is a decimal integer. thread_id may refer to a thread or single-threaded process. object is the name of a shared object or executable; it specifies the symbol table in which to search for the given location. If a shared object is given in the address form of a location specifier, the base address at which the shared object was loaded is added to the specified address.
Header_file may be used to find a static function or object defined within a header file. If a header file is specified without specifying the name of the compilation unit and the debugger cannot find the header within the current file, debug will ask if you want it to search through all the compilation units in the program. If you are creating a stop event, this will allow you to set breakpoints on all instances of that function or line number. For all other commands the search will stop when any instance is found.
Some examples of locations are:
17 a line number in the current file (%file)
foo.c@17 a line number in some other file
0x80801234 an address
main a function name or label
main+3 three bytes after the label
p1@main a function name in a specified process
libfoo.so@bar a function name in a specified object
libfoo.so@0x304 an address within a specified object
%loc the current location
%line the current file and line number
%r0 a register
%r0+80 a register plus offset
%pc-4 a register minus offset
$myvar a user-defined variable
The Stop on Function popup window lets you set a breakpoint on a function.
The popup window displays two scrolling lists. The first list displays the objects (the executable file and shared libraries) making up the selected process or the parent process of the selected thread. The selection in this list determines the list of functions displayed in the second list. The popup window also provides a a ``Filter'' field. This field accepts a ``Pattern'' that can be used to further restrict the list of functions displayed. The pattern is a sh(1) style regular expression. Changing the pattern and then de-selecting and re-selecting the same object from the object list, will apply the new filter to the functions in the selected object. The list of functions is searchable. See ``Searching in lists''.
You must select one function in the second list to set a breakpoint on. Setting a breakpoint creates a stop event. By default, events apply to all the processes and threads derived from the selected program, not just the selected process or thread. If you want to change this behavior, use the ``Granularity'' option in the ``Properties menu''. If you have not selected a program in the ``Process pane'', or you invoke Stop on Function from a window that does not contain a process pane, the current program is assumed. The affected program, processes or threads are listed at the top of the popup window. The event created by executing this command will be displayed in the Main Event area of the ``Event pane''.
In the debugger's default configuration, the Stop on Function option is available in the ``Event menu'' of every window.
A pattern is a sh(1) style regular expression used to filter the list of functions generated in the ``Stop on Function'', ``Show Function Source'' and ``Show Function Dis'' dialogs. A pattern may contain any characters; the following are special:
| * | Matches any string, including the null string |
| ? | Matches any single character |
| [...] | Matches any one of the enclosed characters, ranges are allowed, and ! as the first character indicates negation. |
Filter Pattern Character Table
The Syscall popup window lets you create a syscall event. A syscall event specifies an action to be executed whenever the processes in the selected programs enter or exit a system call.
The valid system calls are displayed in a scrolling list. You must select one or more system calls from the list. The system calls are ordered alphabetically by default. The list may be ordered numerically by selecting the Order list by Number option. The list of system calls is searchable. See ``Searching in lists''. The debugger will halt the affected processes and threads on entry to, and/or exit from, the selected system calls if the Entry or Exit options, respectively, are set.
You may enter, in the ``Commands'' field, an action for the debugger to perform any time the event triggers. The action should be one or more of the commands available through the debugger's command-line interface. The results of executing the commands will be displayed in the ``Command pane''.
You may enter a number in the ``Count'' field to tell the debugger to let the event trigger that many times before halting the process or thread. After that, the process or thread will be halted on each occurrence.
If you popped up the Syscall window from a window containing a ``Process pane'' the new event will apply to the selected programs (if any) in the Process pane. Otherwise, the event applies to the current program or current process or thread.
By default, events apply to all the processes and threads derived from a program, not just not just the selected process or thread. If you want to change this behavior, use the ``Granularity'' popup window. The affected programs, processes, or threads are listed at the top of the popup window.
The event created by executing this command will be displayed in the Main Event area of the Event pane.
In the debugger's default configuration, the Syscall option is available in the ``Event menu'' of every window.