JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris Studio 12.2: Debugging a Program With dbx
search filter icon
search icon

Document Information

Preface

1.  Getting Started With dbx

2.  Starting dbx

3.  Customizing dbx

4.  Viewing and Navigating To Code

5.  Controlling Program Execution

6.  Setting Breakpoints and Traces

7.  Using the Call Stack

8.  Evaluating and Displaying Data

9.  Using Runtime Checking

10.  Fixing and Continuing

11.  Debugging Multithreaded Applications

12.  Debugging Child Processes

13.  Debugging OpenMP Programs

14.  Working With Signals

15.  Debugging C++ With dbx

16.  Debugging Fortran Using dbx

17.  Debugging a Java Application With dbx

18.  Debugging at the Machine-Instruction Level

19.  Using dbx With the Korn Shell

20.  Debugging Shared Libraries

A.  Modifying a Program State

B.  Event Management

Event Handlers

Event Safety

Creating Event Handlers

Manipulating Event Handlers

Using Event Counters

Setting Event Specifications

Breakpoint Event Specifications

in function

at [filename:]line_number

at address_expression

infile filename

infunction function

inmember function inmethod function

inclass classname [-recurse | -norecurse]

inobject object-expression [-recurse | -norecurse]

Data Change Event Specifications

access mode address-expression [, byte-size-expression]

change variable

cond condition-expression

System Event Specifications

dlopen [ lib-path ] dlclose [ lib-path ]

fault fault

lwp_exit

sig signal

sig signal sub-code

sysin code | name

sysout code | name

sysin | sysout

Execution Progress Event Specifications

exit exitcode

next

returns

returns function

step

Other Event Specifications

attach

detach

lastrites

proc_gone

prog_new

stop

sync

syncrtld

thr_create [thread_id]

thr_exit

throw

throw type

throw -unhandled

throw -unexpected

timer seconds

Event Specification Modifiers

-if condition

-resumeone

-in function

-disable

-count n-count infinity

-temp

-instr

-thread thread_id

-lwp lwp_id

-hidden

-perm

Parsing and Ambiguity

Using Predefined Variables

Variables Valid for when Command

$handlerid

Variables Valid for when Command and Specific Events

Event Handler Examples

Setting a Breakpoint for Store to an Array Member

Implementing a Simple Trace

Enabling a Handler While Within a Function (in function)

Determining the Number of Lines Executed

Determining the Number of Instructions Executed by a Source Line

Enabling a Breakpoint After an Event Occurs

Resetting Application Files for replay

Checking Program Status

Catch Floating Point Exceptions

C.  Command Reference

Index

Setting Event Specifications

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 (see stop Command, trace Command, and when Command).

Breakpoint Event Specifications

A breakpoint is a location where an action occurs, at which point the program stops executing. The following are event specifications for breakpoint events.

in function

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 may 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 (see -instr), 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 *)

Note - Do not confuse in function with the-in function modifier.


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 may 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.

at address_expression

The instruction at the given address is about to be executed. This event is available only with thestopi command (see stopi Command) or with the -instr event modifier (see -instr).

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.

infunction function

Equivalent to in function for all overloaded functions named function or all template instantiations thereof.

inmember function inmethod function

Equivalent to in function or the member function named function for every class.

inclass classname [-recurse | -norecurse]

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.

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

Data Change Event Specifications

The following are event specifications for events that involve access or change to the contents of a memory address.

access mode address-expression [, byte-size-expression]

The memory specified by address-expression has been accessed.

mode specifies how the memory was accessed. It can be composed of one or all of the letters:

r

The memory at the specified address has been read.

w

The memory has been written to.

x

The memory has been executed.

mode can also contain either of the following:

a

Stops the process after the access (default).

b

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 give 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 may overlap.


Note - The access event specification is a replacement for the modify event specification.


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 (see access mode address-expression [, byte-size-expression]).

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.

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:

stop step -if conditional_expression

System Event Specifications

The following are event specifications for system events.

dlopen [ lib-path ] dlclose [ lib-path ]

These 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 “+” or a “-”, 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.

fault fault

The fault event occurs when the specified fault is encountered. The faults are architecture-dependent. The following set of faults known to dbx is defined in the proc(4) man page.

Fault
Description
FLTILL
Illegal instruction
FLTPRIV
Privileged instruction
FLTBPT*
Breakpoint trap
FLTTRACE*
Trace trap (single step)
FLTACCESS
Memory access (such as alignment)
FLTBOUNDS
Memory bounds (invalid address)
FLTIOVF
Integer overflow
FLTIZDIV
Integer zero divide
FLTPE
Floating-point exception
FLTSTACK
Irrecoverable stack fault
FLTPAGE
Recoverable page fault
FLTWATCH*
Watchpoint trap
FLTCPCOVF
CPU performance counter overflow

Note - BPT, TRACE, and BOUNDS are used by dbx to implement breakpoints and single-stepping. Handling them might interfere with how dbx works.



Note - FLTBPT and FLTTRACE are ignored because they would interfere with basic dbx functionality such as breakpoints and single-stepping (see Event Safety).


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.


Note - The fault event is not available on Linux platforms.


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.


Note - The lwpexit event is not available on Linux platforms.


sig signal

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 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
    }
}

Note - When the sig event is received, the process has not seen it yet. Only if you continue the process with the specified signal is the signal forwarded to it.


sig signal 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 type the sub-code as a decimal number, in uppercase or lowercase; the prefix is optional.

sysin code | 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 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.


Note - The sysin event is not available on Linux platforms.



Note - The list of kernel system call traps in /usr/include/sys/syscall.h is part of a private interface in the 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. It is unlikely that the names supported by dbx exactly match those of any particular release of the 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.


sysout code | name

The specified system call is finished, and the process is about to return to user mode.


Note - The sysout event is not available on Linux platforms.


sysin | sysout

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.

Execution Progress Event Specifications

The following are event specifications for events pertaining to execution progress.

exit exitcode

The exit event occurs when the process has exited.

next

The next event is similar to the step event except that functions are not stepped into.

returns

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.

returns function

The returns 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; }
step

The step event occurs when the first instruction of a source line is executed. For example, you can get simple tracing with:

when step { echo $lineno: $line; }; cont

When enabling a step event, you instruct dbx to single step automatically next time the contcommand is used.


Note - The step (and next) events do not occur upon the termination of the step command. The step command is implemented in terms of the step event roughly as follows: alias step="when step -temp { whereami; stop; }; cont"


Other Event Specifications

The following are event specifications for other types of events.

attach

dbx has successfully attached to a process.

detach

dbx has successfully detached from the program being debugged.

lastrites

The process being debugged is about to expire, which can happen for the following reasons:

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.


Note - The lastrites event is not available on Linux platforms.


proc_gone

The proc_gone event occurs when dbx is no longer associated with a debugged process. The predefined variable $reason may be signal, exit, kill, or detach.

prog_new

The prog_new event occurs when a new program has been loaded as a result of follow exec.


Note - Handlers for this event are always permanent.


stop

The process has stopped. 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;}
sync

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.


Note - The sync event is not available on Linux platforms.


syncrtld

The syncrtld event occurs after a sync (or 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.

thr_create [thread_id]

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
thr_exit

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
throw

The throw event occurs whenever any exception that is not unhandled or unexpected is thrown by the application.


Note - The throw event is not available on Linux platforms.


throw type

If an exception type is specified with the throw event, only exceptions of that type cause the throw event to occur.

throw -unhandled

-unhandled is a special exception type signifying an exception that is thrown but for which there is no handler.

throw -unexpected

-unexpected is a special exception type signifying an exception that does not satisfy the exception specification of the function that threw it.

timer seconds

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.