Event management refers to the capability of dbx to perform actions when events take place in the program being debugged.
This appendix contains the following sections:
Event management is based on the concept of a handler. The name comes from an analogy with hardware interrupt handlers. Each event management command typically creates a handler, which consists of an ev ent specification and a series of side-effect actions. (See Setting Event Specifications.) The event specification specifies the event that will trigger the handler.
When the event occurs and the handler is triggered, the handler evaluates the event according to any modifiers included in the event specification. (See Event Specification Modifiers.) If the event meets the conditions imposed by the modifiers, the handler’s side-effect actions are performed (that is, the handler “fires”).
An example of the association of a program event with a dbx action is setting a breakpoint on a particular line.
The most generic form of creating a handler is by using the when command.
when event-specification {action; ... }
Examples in this chapter show how you can write a command (like stop, step, or ignore) in terms of when. These examples are meant to illustrate the flexibility of the when command and the underlying handler mechanism, but they are not always exact replacements.
Use the when command, stop command, and trace command to create event handlers. (For detailed information, see when Command, stop Command, and trace Command.)
stop is shorthand for a common when idiom.
when event-specification { stop -update; whereami; }
An event-specification is used by the event management commands stop, when, and trace to specify an event of interest. (see Setting Event Specifications).
Most of the trace commands can be handcrafted using the when command, ksh functionality, and event variables. This is especially useful if you want stylized tracing output.
Every command returns a number known as a handler id (hid). You can access this number using the predefined variable $newhandlerid.
You can use the following commands to manipulate event handlers. For more information on each command, see the cited section.
|
An event handler has a trip counter, which has a count limit. Whenever the specified event occurs, the counter is incremented. The action associated with the handler is performed only if the count reaches the limit, at which point the counter is automatically reset to 0. The default limit is 1. Whenever a process is rerun, all event counters are reset.
You can set the count limit using the –count modifier with a stop command, when command, or trace command. Otherwise, use the handler command to individually manipulate event handlers.
handler [ -count | -reset ] hid new-count new-count-limit
While dbx provides you with a rich set of breakpoint types through the event mechanism, it also uses many events internally. By stopping on some of these internal events you can easily disrupt the internal workings of dbx. If you modify the process state in these cases the chance of disruption is even higher. See Appendix A, Modifying a Program State and Call Safety.
dbx can protect itself from disruption in some cases but not all cases. Some events are implemented in terms of lower level events. For example, all stepping is based on the fault FLTTRACE event. So, issuing the command stop fault FLTTRACE disrupts stepping.
During the following phases of debugging, dbx is unable to handle user events because they interfere with some careful internal orchestration. These phases include:
When rtld runs at program startup (see Dynamic Linker)
The beginning and end of processes
Following the fork() function and the exec() function (see Following the fork Function and Following the exec Function
During calls when dbx needs to initialize a head in the user process (proc_heap_init())
During calls when dbx needs to ensure availability of mapped pages on the stack (ensure_stack_memory())
In many cases you can use the when command instead of the stop command, and echo the information you would have otherwise acquired interactively.
dbx protects itself by:
Disallowing the stop command for the sync, syncrtld, and prog_new events
Ignoring the stop command during the rtld handshake and the other phases mentioned above
For example:
...SolBook linebreakstopped in munmap at 0xff3d503c 0xff3d503c: munmap+0x0004: ta %icc,0x00000008SolBook linebreak dbx76: warning: 'stop' ignored -- while doing rtld handshake
Only the stoppage effect, including recording in the $firedhandlers variable, is ignored. Counts or filters are still active. To stop in such a case, set the event_safety environment variable to off.
Event specifications are used by the stop command, stopi command, when command, wheni command, trace command, and tracei command to denote event types and parameters. The format consists of a keyword representing the event type and optional parameters. The meaning of an event specification is generally identical for all three commands. Exceptions are documented in the command descriptions in Appendix D.
A breakpoint is a location where an action occurs, at which point the program stops executing. This section describes event specifications for breakpoint events.
The syntax for the in event specification is:
infunction
The function has been entered, and the first line is about to be executed. The first executable code after the prolog is used as the actual breakpoint location. This might be a line where a local variable is being initialized. In the case of C++ constructors, execution stops after all base class constructors have executed. If the –instr modifier is used, it is the first instruction of the function about to be executed. The function specification can take a formal parameter signature to help with overloaded function names or template instance specification. For example:
stop in mumble(int, float, struct Node *)
The syntax for the at event specification is:
at[filename:]line-number
The designated line is about to be executed. If you specify filename, then the designated line in the specified file is about to be executed. The file name can be the name of a source file or an object file. Although quotation marks are not required, they might be necessary if the file name contains special characters. If the designated line is in template code, a breakpoint is placed on all instances of that template.
You can also use specify a specific address:
ataddress-expression
The instruction at the given address is about to be executed. This event is available only with the stopi command or with the –instr event modifier
The syntax for the infile event specification is:
infile filename
This event puts a breakpoint on every function defined in a file. The stop infile command iterates through the same list of functions as the funcs –f filename command.
Method definitions in .h files, template files, or plain C code in .h files, such as the kind used by the regexp command, might contribute function definitions to a file, but these definitions are excluded.
If the specified filename is the name of an object file (that is, it ends in .o). breakpoints are put on every function that occurs in that object file.
The stop infile list.h command does not put breakpoints on all instances of methods defined in the list.h file. Use events like inclass or inmethod to do so.
The fix command might eliminate or add a function to a file. The stop infile command puts breakpoints on all old versions of function in a file as well as any functions that might be added in the future.
No breakpoints are put on nested functions or subroutines in Fortran files.
You can use the clear command to disable a single breakpoint in the set created by the infile event.
The syntax for the infunction event specification is:
infunctionfunction
This specification is equivalent to in function for all overloaded functions named function or all template instantiations thereof.
The syntax for the inmember event specification is:
inmember function
This specification is an alias for the inmethod event specification.
The syntax for the inmember event specification is:
inmethod function
This specification is equivalent to in function or the member method named function for every class.
The syntax for the inclass event specification is:
inmember classname [-recurse | -norecurse]
This specification is equivalent to in function for all member functions that are members of classname, but not any of the bases of classname. –norecurse is the default. If –recurse is specified, the base classes are included.
The syntax for the inobject event specification is:
inobject object-expression [-recurse | -norecurse]
A member function called on the specific object at the address denoted by object-expression has been called. stop inobject ox is roughly equivalent to the following, but unlike inclass, bases of the dynamic type of ox are included. –recurse is the default. If –norecurse is specified, the base classes are not included.
stop inclass dynamic_type(ox) -if this==ox
This section describes event specifications for events that involve access or change to the contents of a memory address.
The syntax for the access event specification is:
access mode address-expression [,byte-size-expression]
The memory specified by address-expression has been accessed.
mode specifies how the memory was accessed. Valid values are one or all of the following letters:
The memory at the specified address has been read.
The memory has been written to.
The memory has been executed.
mode can also contain either of the following:
Stops the process after the access (default).
Stops the process before the access.
In both cases the program counter will point at the offending instruction. The “before” and “after” refer to the side effect.
address-expression is any expression that can be evaluated to produce an address. If you provide a symbolic expression, the size of the region to be watched is automatically deduced. You can override it by specifying byte-size-expression. You can also use nonsymbolic, typeless address expressions, in which case, the size is mandatory. For example:
stop access w 0x5678, sizeof(Complex)
The access command has the limitation that no two matched regions can overlap.
The syntax for the change event specification is:
change variable
The value of variable has changed. The change event is roughly equivalent to:
when step { if [ $last_value !=$[variable]]
then
stop
else
last_value=$[variable]
fi
}
This event is implemented using single-stepping. For faster performance, use the access event.
The first time variable is checked causes one event, even though no change is detected. This first event provides access to the initial value of variable. Subsequent detected changes in the value of variable trigger additional events.
The syntax for the cond event specification is:
cond condition-expression
The condition denoted by condition-expression evaluates to true. You can specify any expression for condition-expression, but it must evaluate to an integral type. The cond event is roughly equivalent to the following stop command:
stop step -if conditional-expression
This section describes event specifications for system events.
The syntax for the dlopen() and dlopen() event specifications is:
dlopen [ lib-path ]
dlclose [ lib-path ]
System events occur after a dlopen() call or a dlclose() call succeeds. A dlopen() call or dlclose() call can cause more than one library to be loaded. The list of these libraries is always available in the predefined variable $dllist. The first shell word in $dllist is a + (plus sign) or a - (minus sign), indicating whether the list of libraries is being added or deleted.
lib-path is the name of a shared library. If it is specified, the event occurs only if the given library was loaded or unloaded. In that case, $dlobj contains the name of the library. $dllist is still available.
If lib-path begins with a /, a full string match is performed. Otherwise, only the tails of the paths are compared.
If lib-path is not specified, then the events always occur whenever there is any dl-activity. In this case, $dlobj is empty but $dllist is valid.
The syntax for the fault event specification is:
fault fault
The fault event occurs when the specified fault is encountered. The faults are architecture-dependent. The set of faults known to dbx is listed in the following list and defined in the proc(4) man page.
Illegal instruction
Privileged instruction
Breakpoint trap
Trace trap (single step)
Memory access (such as alignment)
Memory access (such as alignment)
Memory bounds (invalid address)
Integer overflow
Integer zero divide
Floating-point exception
Irrecoverable stack fault
Recoverable page fault
Watchpoint trap
CPU performance counter overflow
These faults are taken from /sys/fault.h. fault can be any of those listed above, in uppercase or lowercase, with or without the FLT- prefix, or the actual numerical code.
The syntax for the lwp_exit event specification is:
lwp_exit
The lwp_exit event occurs when lwp has been exited. $lwp contains the ID of the exited LWP (lightweight process) for the duration of the event handler.
The syntax for the sig event specification is:
sigsignal
The sig signal event occurs when the signal is first delivered to the program being debugged. signal can be either a decimal number or the signal name in uppercase or lowercase. The prefix is optional. This event is completely independent of the catch command and ignore command, although the catch command can be implemented as follows:
function simple_catch {
when sig $1 {
stop;
echo Stopped due to $sigstr $sig
whereami
}
}
Alternatively, you can specify a signal with a sub-code. The syntax for this option of the sig event specification is:
sigsignal sub-code
When the specified signal with the specified sub-code is first delivered to the child, the sig signal sub-code event occurs. As with signals, you can provide the sub-code as a decimal number, in uppercase or lowercase. The prefix is optional.
The syntax for the sysin event specification is:
sysincode|name
The specified system call has just been initiated, and the process has entered kernel mode.
The concept of system call supported by dbx is that provided by traps into the kernel as enumerated in /usr/include/sys/syscall.h.
This concept is not the same as the ABI notion of system calls. Some ABI system calls are partially implemented in user mode and use non-ABI kernel traps. However, most of the generic system calls (the main exception being signal handling) are the same between syscall.h and the ABI.
The list of kernel system call traps in /usr/include/sys/syscall.h is part of a private interface in the Oracle Solaris OS that changes from release to release. The list of trap names (codes) and trap numbers that dbx accepts includes all of those supported by any of the versions of the Solaris OS that dbx supports. The names supported by dbx are unlikely to exactly match those of any particular release of the Oracle Solaris OS, and some of the names in syscall.h might not be available. Any trap number (code) is accepted by dbx and works as expected, but a warning is issued if it does not correspond to a known system call trap.
The syntax for the sysout event specification is:
sysoutcode|name
The specified system call is finished, and the process is about to return to user mode.
Without arguments, all system calls are traced. Certain dbx features, for example, the modify event and runtime checking, cause the child to execute system calls for its own purposes and show up if traced.
This section describes event specifications for events pertaining to execution progress.
The syntax for the exit event specification is:
exitexitcode
The exit event occurs when the process has exited.
The next event is similar to the step event except that functions are not stepped into.
The returns event is a breakpoint at the return point of the current visited function. The visited function is used so that you can use the returns event specification after giving a number of step up commands. The returns event is always –temp and can only be created in the presence of a live process.
The syntax for the returns event specification is:
returnsfunction
The r eturns function event executes each time the given function returns to its call site. This is not a temporary event. The return value is not provided, but you can find integral return values by accessing the following registers:
SPARC based systems – $o0
x86 based systems – $eax
x64 based systems – $rax, $rdx
The event is roughly equivalent to:
when in func { stop returns; }
The step event occurs when the first instruction of a source line is executed. For example, you can get simple tracing with the following command:
when step { echo $lineno: $line; }; cont
When enabling a step event, you instruct dbx to single step automatically next time the contcommand is used.
The syntax for the throw event is:
throw [type | –unhandled | –unexpected]
The throw event occurs whenever any exception that is not unhandled or unexpected is thrown by the application.
If an exception type is specified with the throw event, only exceptions of that type cause the throw event to occur.
If the –unhandled option is specified, a special exception type signifying an exception is thrown but for which there is no handler.
The –unexpected option is specified, a special exception type signifying an exception does not satisfy the exception specification of the function that threw it.
The following section describes event specifications for tracked threads.
The omp_barrier event specification is when the tracked thread enters or exits a barrier. You can specify a type, which can be explicit or implicit, and a state, which can be enter, exit, or all_entered. The default is explicit all_entered.
The omp_taskwait event specification is when the tracked thread enters or exists a taskwait. You can specify a state, which can be enter or exit. The default is exit.
The omp_ordered event specification is when the tracked thread enters or exists an ordered region. You can specify a state, which can be begin, enter or exit. The default is enter.
The omp_critical event specification is when the tracked thread enters a critical region.
The omp_atomic event specification is when the tracked thread enters or exists an atomic region. You can specify a state, which can be begin or exit. The default is begin.
The omp_flush event specification is when the tracked thread enters a explicit flush region.
The omp_task event specification is when the tracked thread enters or exists a task region. You can specify a state, which can be create, start or finish. The default is start.
The omp_master event specification is when the tracked thread enters a master region.
The omp_single event specification is when the tracked thread enters a single region.
This section describes event specifications for other types of events.
The attach event is when dbx has successfully attached to a process.
The detach event is when dbx has successfully detached from the program being debugged.
The lastrites event is when process being debugged is about to expire, which can happen for the following reasons:
The _exit(2) system call has been called, either through an explicit call or when main() returns.
A terminating signal is about to be delivered.
The process is being killed by the kill command.
The final state of the process is usually, but not always, available when this event is triggered, giving you your last opportunity to examine the state of the process. Resuming execution after this event terminates the process.
The proc_gone event occurs when dbx is no longer associated with a debugged process. The predefined variable $reason can be signal, exit, kill, or detach.
The prog_new event occurs when a new program has been loaded as a result of follow exec.
The stop event occurs whenever the process stops such that the user receives a prompt, particularly in response to a stop handler. For example, the following commands are equivalent:
display x
when stop {print x;}
The sync event occurs when the process being debugged has just been executed with exec(). All memory specified in a.out is valid and present, but preloaded shared libraries have not been loaded. For example, printf, although available to dbx, has not been mapped into memory.
A stop on this event is ineffective; however, you can use the sync event with the when command.
The syncrtld event occurs after a sync or an attach if the process being debugged has not yet processed shared libraries. It executes after the dynamic linker startup code has executed and the symbol tables of all preloaded shared libraries have been loaded but before any code in the .init section has run.
A stop on this event is ineffective; however, you can use the syncrtld event with the when command.
The thr_create event occurs when a thread, or a thread with the specified thread ID, has been created. For example, in the following stop command, the thread ID t@1 refers to creating thread, while the thread ID t@5 refers to the created thread.
stop thr_create t@5 -thread t@1
The thr_exit event occurs when a thread has exited. To capture the exit of a specific thread, use the -thread option of the stop command as follows:
stop thr_exit -thread t@5
The syntax for the timer event is:
timerseconds
The timer event occurs when the program being debugged has been running for seconds. The timer used with this event is shared with collector command. The resolution is in milliseconds, so a floating point value for seconds, for example 0.001, is acceptable.
An event specification modifier sets additional attributes of a handler, the most common kind being event filters. Modifiers must appear after the keyword portion of an event specification. A modifier begins with a dash (-). The following are the valid event specification modifiers.
The syntax for the -if modifier is:
-ifcondition
The condition is evaluated when the event specified by the event specification occurs. The side effect of the handler is allowed only if the condition evaluates to nonzero.
If the –if modifier is used with an event that has an associated singular source location, such as in or at, condition is evaluated in the scope corresponding to that location. Otherwise, qualify it with the desired scope.
Macro expansion is performed on the condition according to same conventions as with the print command.
The –resumeone modifier can be used with the -if modifier in an event specification for a multithreaded program, and causes only one thread to be resumed if the condition contains function calls. For more information, see Qualifying Breakpoints With Conditional Filters.
The syntax for the -in modifier is:
-infunction
The event triggers only if it occurs between the time the first instruction of the given function is reached and the time the function returns. Recursion on the function are ignored.
The–disable modifier creates the handler in the disabled state.
The syntax for the -count modifier is:
-countn
or
-count infinity
The –count n and - count infinity modifiers have the handler count from 0 (see Using Event Counters). Each time the event occurs, the count is incremented until it reaches n. Once that happens, the handler fires and the counter is reset to zero.
Counts of all enabled handlers are reset when a program is run or rerun. More specifically, they are reset when the sync event occurs.
The count is reset when you begin debugging a new program with the debug –r command (see debug Command) or the attach –r command (see attach Command).
The -temp modifier creates a temporary handler. Once the event has occurred it is automatically deleted. By default, handlers are not temporary. If the handler is a counting handler, it is automatically deleted only when the count reaches 0 (zero).
Use the delete -temp command to delete all temporary handlers.
The -instr modifier makes the handler act at an instruction level. This event replaces the traditional ’i’ suffix of most commands. It usually modifies two aspects of the event handler:
Any message prints assembly-level rather than source-level information.
The granularity of the event becomes instruction level. For instance, step –instr implies instruction-level stepping.
The syntax for the -thread modifier is:
-threadthread-ID
The -thread modifier means the action is executed only if the thread that caused the event matches a different thread ID. The specific thread you have in mind might be assigned a different thread ID from one execution of the program to the next.
The syntax for the -lwp modifier is:
-lwplwp-ID
The -lwp modifier means the action is executed only if the thread that caused the event matches lwp-ID. The action is executed only if the thread that caused the event matches lwp-ID. The specific thread you have in mind might be assigned a different lwp-ID from one execution of the program to the next.
The -hidden modifier hides the handler in a regular status command. Use status –h to see hidden handlers.
Normally all handlers are thrown away when a new program is loaded. Using the –perm modifier retains the handler across debugging sessions. A plain delete command does not delete a permanent handler. Use delete –p to delete a permanent handler.
The syntax for event specifications and modifiers is keyword driven and based on ksh conventions. Everything is split into words delimited by spaces.
Expressions can have spaces embedded in them, causing ambiguous situations. For example, consider the following two commands:
when a -temp when a-temp
In the first example, even though the application might have a variable named temp, the dbx parser resolves the event specification in favor of –temp being a modifier. In the second example, a-temp is collectively passed to a language-specific expression parser. If no variables are named a and temp, an error occurs. Use parentheses to force parsing.
Certain read-only ksh predefined variables are provided. The variables listed in the following table are always valid.
|
The following example shows that whereami can be implemented:
function whereami {
echo Stopped in $func at line $lineno in file $(basename $file)
echo "$lineno\t$line"
}
The variables described in this section are valid only within the body of a when command.
During the execution of the body, $handlerid is the ID of the when command to which the body belongs. The following commands are equivalent:
when X -temp { do_stuff; }
when X { do_stuff; delete $handlerid; }
Certain variables are valid only within the body of a when command and for specific events, as shown in the following tables.
|
|
|
|
|
|
This section provides some examples of setting event handlers.
This example shows how to set a data change breakpoint on array[99]:
(dbx) stop access w &array[99] (2) stop access w &array[99], 4 (dbx) run Running: watch.x2 watchpoint array[99] (0x2ca88[4]) at line 22 in file "watch.c" 22 array[i] = i;
This example shows how to implement a simple trace:
(dbx) when step { echo at line $lineno; }
The following example shows how to enable a handler while within a function:
<dbx> trace step -in foo
This command is equivalent to the following:
# create handler in disabled state
when step -disable { echo Stepped to $line; }
t=$newhandlerid # remember handler id
when in foo {
# when entered foo enable the trace
handler -enable "$t"
# arrange so that upon returning from foo,
# the trace is disabled.
when returns { handler -disable "$t"; };
}
This example shows how to see how many lines have been executed in a small program, type:
(dbx) stop step -count infinity # step and stop when count=inf (2) stop step -count 0/infinity (dbx) run ... (dbx) status (2) stop step -count 133/infinity
The program never stops, and then the program terminates. The number of lines executed is 133. This process is very slow. It is most useful with breakpoints on functions that are called many times.
This example shows how to count how many instructions a line of code executes:
(dbx) ... # get to the line in question (dbx) stop step -instr -count infinity (dbx) step ... (dbx) status (3) stop step -count 48/infinity # 48 instructions were executed
If the line you are stepping over makes a function call, the lines in the function are counted as well. You can use the next event instead of step to count instructions, excluding called functions.
Enable a breakpoint only after another event has occurred. For example, you would use the following breakpoint if your program begins to execute incorrectly in function hash, but only after the 1300th symbol lookup.
(dbx) when in lookup -count 1300 {
stop in hash
hash_bpt=$newhandlerid
when proc_gone -temp { delete $hash_bpt; }
}
In this example, if your application processes files that need to be reset during a replay, you can write a handler to do that each time you run the program.
(dbx) when sync { sh regen ./database; }
(dbx) run < ./database... # during which database gets clobbered
(dbx) save
... # implies a RUN, which implies the SYNC event which
(dbx) restore # causes regen to run
This example shows how to see quickly where the program is while it is running, type:
(dbx) ignore sigint
(dbx) when sig sigint { where; cancel; }
You would then issue ^C to see a stack trace of the program without stopping it.
This example is basically what the collector hand sample mode does (and more). Use SIGQUIT (^\) to interrupt the program because ^C is now used.
The following example shows how to catch only specific floating-point exceptions, for example, IEEE underflow:
(dbx) ignore FPE # disable default handler (dbx) help signals | grep FPE # can’t remember the subcode name ... (dbx) stop sig fpe FPE_FLTUND ...
For more information about enabling ieee handlers, see Trapping the FPE Signal (Oracle Solaris Only).