Sun Studio 12: Debugging a Program With dbx

Previous: Appendix B Event Management

Appendix C Command Reference

This appendix gives detailed syntax and functional descriptions of all of the dbx commands.

`assign` Command

In native mode, the assign command assigns a new value to a program variable. In Java mode, the assign command assigns a new value to a local variable or parameter.

Native Mode Syntax

assign variable = expression

where:

expression is the value to be assigned to variable.

Java Mode Syntax

assign identifier = expression

where:

class_name is the name of a Java class, using either the package path (using period (.) as a qualifier; for example, test1.extra.T1.Inner) or the full path name (preceded by a pound sign (#) and using slash (/) and dollar sign ($) as qualifiers; for example, #test1/extra/T1$Inner). Enclose class_name in quotation marks if you use the $ qualifier.

expression is a valid Java expression.

field_name is the name of a field in the class.

identifier is a local variable or parameter, including this, the current class instance variable (object_name.field_name) or a class (static) variable (class_name.field_name).

object_name is the name of a Java object.

`attach` Command

The attach command attaches dbx to a running process, stopping execution and putting the program under debugging control. It has identical syntax and identical functionality in native mode and Java mode.

Syntax

attach process_id: Begin debugging the program with process ID process_id. dbx finds the program using /proc.
attach -p process_id program_name: Begin debugging program_name with process ID process_id.
attach program_name process_id: Begin debugging program_name with process ID process_id. program_name can be —; dbx finds it using /proc.
attach -r ...: The -r option causes dbx to retain all watch commands, display commands, when commands, andstop commands. With no -r option, an implicit delete all command andundisplay 0 command are performed.

where:

process_id is the process ID of a running process.

program_name is the path name of the running program.

To Attach to a Running Java Process

Ensure that the JVM^TM software can find libdbx_agent.so by adding libdbx_agent.so to your LD_LIBRARY_PATH. libdbx_agent.so:
- If you are using the 32-bit version of the JVM software on a system running the Solaris OS, add /installation_directory/SUNWspro/libdbx_agent.so to LD_LIBRARY_PATH.
- If you are using the 64-bit version of the JVM software on a SPARC based system running the Solaris OS, add /installation_directory/SUNWspro/lib/v9/libdbx_agent.so to LD_LIBRARY_PATH.
- If you are using the 64-bit version of the JVM software on an x64 based system running the Linux OS, add /installation_directory/sunstudio12/lib/amd64/libdbx_agent.so to LD_LIBRARY_PATH.
The installation_directory is the location where the Sun Studio software is installed.

Start your Java application by typing:

java -Djava.compiler=NONE -Xdebug -Xnoagent -Xrundbx_agent myclass.class

Then you can attach to the process by starting dbx with the process id:

dbx -process_id

`bsearch` Command

The bsearch command searches backward in the current source file. It is valid only in native mode.

Syntax

bsearch string: Search backward for string in the current file.
bsearch: Repeat search, using the last search string.

where:

string is a character string.

`call` Command

In native mode, the call command calls a procedure. In Java mode, the call command calls a method.

Native Mode Syntax

call procedure ([parameters]) [-lang language] [-resumeone]

where:

language is the language of the called procedure.

procedure is the name of the procedure.

parameters are the procedure’s parameters.

You can also use the call command to call a function; to see the return value use the print command (see print Command).

Occasionally the called function hits a breakpoint. You can choose to continue using the cont command (see cont Command), or abort the call by using pop -c (see pop Command). The latter is useful also if the called function causes a segmentation fault.

The -lang option specifies the language of the called procedure and tells dbx to use the calling conventions of the specified language. This option is useful when the procedure being called was compiled without debugging information and dbx does not know how to pass parameters.

The -resumeone option resumes only one thread when the procedure is called. For more information, see Resuming Execution.

Java Mode Syntax

call [class_name.|object_name.] method_name ([parameters]}

where:

class_name is the name of a Java class, using either the package path (using period (.) as a qualifier for example, test1.extra.T1.Inner) or the full path name (preceded by a pound sign (#) and using slash (/) and dollar sign ($) as qualifiers; for example, #test1/extra/T1$Inner). Enclose class_name in quotation marks if you use the $ qualifier.

object_name is the name of a Java object.

method_name is the name of a Java method.

parameters are the method’s parameters.

Occasionally the called method hits a breakpoint. You can choose to continue using the cont command (see cont Command, or abort the call by using pop -c (see pop Command). The latter is useful also if the called method causes a segmentation fault.

`cancel` Command

The cancel command cancels the current signal. It is primarily used within the body of a when command (see when Command). It is valid only in native mode.

Signals are normally cancelled when dbx stops because of a signal. If awhen command is attached to a signal event, the signal is not automatically cancelled. The cancel command can be used to explicitly cancel the signal.

Syntax

cancel

`catch` Command

The catch command catches the given signal(s). It is valid only in native mode.

Catching a given signal causes dbx to stop the program when the process receives that signal. If you continue the program at that point, the signal is not processed by the program.

Syntax

catch: Print a list of the caught signals.
catch number number ...: Catch signal(s) numbered number.
catch signal signal ...: Catch signal(s) named by signal. SIGKILL cannot be caught or ignored.
catch $(ignore): Catch all signals.

where:

number is the number of a signal.

signal is the name of a signal.

`check` Command

The check command enables checking of memory access, leaks, or usage, and prints the current status of runtime checking (RTC). It is valid only in native mode.

Note –

The check command is available only on Solaris platforms.

The features of runtime checking that are enabled by this command are reset to their initial state by the debug command.

Syntax

check -access

Turn on access checking. RTC reports the following errors:

baf: Bad free
duf: Duplicate free
maf: Misaligned free
mar: Misaligned read
maw: Misaligned write
oom: Out of memory
rua: Read from unallocated memory
rui: Read from uninitialized memory
wro: Write to read-only memory
wua: Write to unallocated memory

The default behavior is to stop the process after detecting each access error, which can be changed using the rtc_auto_continue dbx environment variable. When set to on access errors are logged to a file (the file name is controlled by the dbx environment variable rtc_error_log_file_name). See dbxenv Command.

By default each unique access error is only reported the first time it happens. Change this behavior using the dbx environment variable rtc_auto_suppress (the default setting of this variable is on). See dbxenv Command.

check -leaks [-frames n] [-match m]

Turn on leak checking. RTC reports the following errors:

aib: Possible memory leak - only pointer points in the middle of the block
air: Possible memory leak - pointer to the block exists only in register
mel: Memory leak - no pointers to the block

With leak checking turned on, you get an automatic leak report when the program exits. All leaks including possible leaks are reported at that time. By default, a non-verbose report is generated (controlled by the dbx environment variable rtc_mel_at_exit). However, you can ask for a leak report at any time (see showleaks Command).

-frames n implies that up to n distinct stack frames are displayed when reporting leaks. -matchm is used for combining leaks; if the call stack at the time of allocation for two or more leaks matches n frames, then these leaks are reported in a single combined leak report.

The default value of n is 8 or the value of m (whichever is larger). Maximum value of n is 16. The default value of m is 3 for C++, and 2 otherwise.

check -memuse [-frames n] [-match m]

The -memuse option behaves similarly to the -leaks option, and also enables a blocks in use report (biu) when the program exits. By default a non-verbose blocks in use report is generated (controlled by the dbx environment variable rtc_biu_at_exit) At any time during program execution you can see where the memory in your program has been allocated (see showmemuse Command).

-frames n implies that up to n distinct stack frames will be displayed while reporting memory use and leaks. -matchm is used for combining these reports; if the call stack at the time of allocation for two or more leaks matches m frames, then these are reported in a single combined memory leak report.

The default value of n is 8 or the value of m (whichever is larger). Maximum value of n is 16. The default value of m is 3 for C++, and 2 otherwise. See check -leaks as well.

check -all [-frames n] [-match m]

Equivalent to check -access or check -memuse [-frames n] [-match m]

The value of the dbx environment variable rtc_biu_at_exit is not changed with check -all, so by default no memory use report is generated at exit. See dbx Command for the description of the rtc_biu_at_exit environment variable.

check [functions] [files] [loadobjects]

Equivalent to check -all; suppress all; unsuppress all in functions, files, and loadobjects

where:

functions is one or more function names.

files is one or more file names.

loadobjects is one or more load object names

You can use this to focus runtime checking on places of interest.

Note –

To detect all errors, RTC does not require the program be compiled -g. However, symbolic ( -g) information is sometimes needed to guarantee the correctness of certain errors (mostly read from uninitialized memory). For this reason certain errors ( rui for a.out and rui + aib + air for shared libraries) are suppressed if no symbolic information is available. This behavior can be changed by using suppress and unsuppress.

`clear` Command

The clear command clears breakpoints. It is valid only in native mode.

Event handlers created using the stop command, trace command, or when command with the inclass argument, inmethod argument, or infunction argument create sets of breakpoints. If the line you specify in theclear command matches one of these breakpoints, only that breakpoint is cleared. Once cleared in this manner an individual breakpoint belonging to a set cannot be enabled again. However, disabling and then enabling the relevant event handler reestablishes all the breakpoints.

Syntax

clear: Clear all breakpoints at the current stopping point.
clear line: Clear all breakpoints at line.
clear filename:line: Clear all breakpoints at line in filename.

where:

line is the number of a source code line.

filename is the name of a source code file.

`collector` Command

The collector command collects performance data for analysis by the Performance Analyzer. It is valid only in native mode.

Note –

The collector command is available only on Solaris platforms.

Syntax

collector command_list: Specify one or more of the collector commands
collector archive options: Specify the mode for archiving an experiment when it terminates (see collector archive Command).
collector dbxsample options: Control the collection of samples when dbx stops the target process (see collector dbxsample Command).
collector disable: Stop data collection and close the current experiment (see collector disable Command).
collector enable: Enable the collector and open a new experiment (see collector enable Command).
collector heaptrace options: Enable or disable collection of heap tracing data (see collector heaptrace Command)
collector hwprofile options: Specify hardware counter profiling settings (see collector hw_profile Command).
collector limit options: Limit the amount of profiling data recoreded (see collector limit Command).
collector mpitrace options: Enables or disables collection of MPI tracing data (see collector mpitrace Command).
collector pause: Stop collecting performance data but leave experiment open (see collector pause Command).
collector profile options: Specify settings for collecting callstack profiling data (see collector profile Command).
collector resume: Start performance data collection after pause (see collector resume Command).
collector sample options: Specify sampling settings (see collector sample Command
collector show options: Show current collector settings (see collector show Command).
collector status: Inquire status about current experiment (see collector status Command).
collector store options: Experiment file control and settings (see collector store Command).
collector synctrace options: Specify settings for collecting thread synchronization wait tracing data (see collector synctrace Command).
collector tha options: Specify settings for collecting thread analyzer data (see collector tha Command.
collector version: Report the version of libcollector.so that would be used to collect data (see collector version Command).

where:

options are the settings that can be specified with each command.

To start collecting data, type either collector enable.

To turn off data collection, type collector disable.

`collector archive` Command

The collector archive command specifies the archiving mode to be used when the experiment terminates.

Syntax

collector archive on|off|copy: By default, normal archiving is used. For no archiving, specify off. To copy loadobjects into the experiment for portability, specify copy.

`collector dbxsample` Command

The collector dbxsample command specifies whether or not to record a sample when the process is stopped by dbx.

Syntax

collector dbxsample on|off: By default, a sample is collected when the process is stopped by dbx. To not collect a sample at this time, specify off.

`collector disable` Command

The collector disable command causes the data collection to stop and the current experiment to be closed.

Syntax

collector disable

`collector enable` Command

The collector enable command enables the collector and opens a new experiment.

Syntax

collector enable

`collector heaptrace` Command

The collector heaptrace command specifies options for collecting heap tracing (memory allocation) data.

Syntax

collector heaptrace on|off: By default, heap tracing data is not collected. To collect this data, specify on.

`collector hw_profile` Command

The collector hw_profile command specifies options for collecting hardware-counter overflow profiling data.

Syntax

collector hwprofile on|off: By default, hardware-counter overflow profile data is not collected. To collect this data, specify on.
collector hwprofile list: Print out the list of available counters.
collector hwprofile counter name interval [name2 interval2]: Specify hardware counter name(s) and interval(s).

where:

name is the name of a hardware counter.

interval is the collection interval in milliseconds.

name2 is the name of a second hardware counter.

interval2 is the collection interval in milliseconds.

Hardware counters are system-specific, so the choice of counters available to you depends on the system you are using. Many systems do not support hardware-counter overflow profiling. On these machines, the feature is disabled.

`collector limit` Command

The collector limit command specifies the experiment file size limit.

Syntax

collector limit value

where:

value, in megabytes, limits the amount of profiling data recorded. When the limit is reached, no more profiling data is recorded but the experiment remains open and sample points continue to be recorded. The default limit on the amount of data recorded is 2000 Mbytes.

`collector mpitrace` Command

The collector mpitrace command specifies options for collecting MPI tracing data.

Syntax

collector mpitrace on|off: By default, MPI tracing data is not collected. To collect this data, specify on.

`collector pause` Command

The collector pause command causes the data collection to stop but leaves the current experiment open. Sample points are not recorded while the Collector is paused. A sample is generated prior to a pause, and another sample is generated immediately following a resum. Data collection can be resumed with the collector resume command (see collector resume Command).

Syntax

collector pause

`collector profile` Command

The collector profile command specifies options for collecting profile data.

Syntax

collector profile on|off: Specify profile data collection mode.
collector profile timer interval: Specify profile timer period, fixed or floating point, with an optional trailing m for milliseconds or u for microseconds.

`collector resume` Command

The collector resume command causes the data collection to resume after a pause created by the collector pause command (see collector pause Command).

Syntax

collector resume

`collector sample` Command

The collector sample command specifies the sampling mode and the sampling interval.

Syntax

collector sample periodic|manual: Specify sampling mode.
collector sample period seconds: Specify sampling interval in seconds.
collector sample record [name]: Record a sample with an optional name.

where:

seconds is the length of the sampling interval.

name is the name of the sample.

`collector show` Command

The collector show command shows the settings of one or more categories of options.

Syntax

collector show all: Show all settings.
collector show archive: Show archive setting.
collector show profile: Show call stack profiling settings.
collector show synctrace: Show thread synchronization wait tracing settings.
collector show hwprofile: Show hardware counter data settings.
collector show heaptrace: Show heap tracing data settings.
collector show limit: Show experiment size limits.
collector show mpitrace: Show MPI trace data settings.
collector show sample: Show sample settings.
collector show store: Show store settings.
collector show tha: Show thread analyzer data settings.

`collector status` Command

The collector status command inquires about the status of the current experiment.

Syntax

collector status

`collector store` Command

The collector store command specifies the directory and file name where an experiment is stored.

Syntax

collector store directory pathname: Specify directory where experiment is stored.
collector store filename filename: Specify experiment file name.
collector store group string: Specify experiment group name.

where:

pathname is the pathname of the directory where an experiment is to be stored.

filename is the name of the experiment file

string is the name of an experiment group.

`collector synctrace` Command

The collector synctrace command specifies options for collecting synchronization wait tracing data.

Syntax

collector synctrace on|off: By default, thread synchronization wait tracing data is not collected. To collect this data, specify on.
collector synctrace threshold milliseconds: Specify threshold in microseconds. The default value is 1000.
collector synctrace threshold calibrate: Threshold value will be calculated automatically.

where:

microseconds is the threshold below which synchronization wait events are discarded.

`collector tha` Command

Syntax

collector tha on|off: By default, thread analyzer data is not collected. To collect this data, specify on.

`collector version` Command

The collector version command reports the version of libcollector.so that would be used to collect data.

Syntax

collector version

`cont` Command

The cont command causes the process to continue execution. It has identical syntax and identical functionality in native mode and Java mode.

Syntax

cont: Continue execution. In an MT process all threads are resumed. Use Control-C to stop executing the program.
cont ... -sig signal: Continue execution with signal signal.
cont ... id: The id specifies which thread or LWP to continue.
cont at line [id]: Continue execution at line line. id is required if the application is multi-threaded.
cont ... -follow parent|child|both: If the dbx follow_fork_mode environment variable is set to ask, and you have chosen stop, use this option to choose which process to follow. both is only applicable in the Sun Studio IDE.

`dalias` Command

The dalias command defines a dbx-style (csh-style) alias. It is valid only in native mode.

Syntax

dalias: (dbx alias) List all currently defined aliases.
dalias name: List the definition, if any, of alias name.
dalias name definition: Define name to be an alias for definition. definition may contain white space. A semicolon or newline terminates the definition.

where:

name is the name of an alias

definition is the definition of an alias.

dbx accepts the following csh history substitution meta-syntax, which is commonly used in aliases:

!:<n>

!-<n>

The ! usually needs to be preceded by a backslash. For example:

dalias goto "stop at \!:1; cont; clear"

For more information, see the csh(1) man page.

`dbx` Command

The dbx command starts dbx.

Native Mode Syntax

dbx options program_name: Debug program_name.
dbx options program_name core: Debug program_name with corefile core.
dbx options program_name process_id: Debug program_name with process ID process_id.
dbx options - process_id: Debug process ID process_id; dbx finds the program via /proc.
dbx options - core: Debug using corefile core; see also debug Command.
dbx options -r program_name arguments: Run program_name with arguments arguments; if abnormal termination, start debugging program_name, else just exit.

where:

program_name is the name of the program to be debugged.

process_id is the process ID of a running process.

arguments are the arguments to be passed to the program.

options are the options listed in Options.

Java Mode Syntax

dbx options program_name{.class | .jar}: Debug program_name.
dbx options program_name{.class | .jar} process_id: Debug program_name with process ID process_id.
dbx options - process_id: Debug process ID process_id; dbx finds the program using /proc.
dbx options -r program_name{.class | .jar} arguments: Run program_name with arguments arguments; if abnormal termination, start debugging program_name, else just exit.

where:

program_name is the name of the program to be debugged.

process_id is the process ID of a running process.

arguments are the arguments to be passed to the program (not to the JVM software).

options are the options listed in Options.

Options

For both native mode and Java mode, options are the following options:

`-B`	Suppress all messages; return with exit code of program being debugged.
`-c` `commands`	Execute `commands` before prompting for input.
`-C`	Preload the Runtime Checking library (see `check` Command).
`-d`	Used with `-s`, removes `file` after reading.
`-e`	Echo input commands.
`-f`	Force loading of core file, even if it doesn’t match.
`-h`	Print the usage help on `dbx`.
`-I` `dir`	Add `dir` to `pathmap` set (see `pathmap` Command).
`-k`	Save and restore keyboard translation state.
`-q`	Suppress messages about reading stabs.
`-r`	Run program; if program exits normally, exit.
`-R`	Print the readme file on `dbx.`
`-s` `file`	Use `file` instead of `/`current_directory`/.dbxrc` or `$HOME/.dbxrc` as the startup file
`-S`	Suppress reading of initialization file `/`installation_directory`/lib/dbxrc`.
`-V`	Print the version of `dbx`.
`-w` `n`	Skip `n` frames on `where` command.
`-x exec32`	Run the 32-bit `dbx` binary instead of the 64-bit `dbx` binary that runs by default on systems running a 64-bit OS.
`--`	Marks the end of the option list; use this if the program name starts with a dash.

`dbxenv` Command

The dbxenv command is used to list or set dbx environment variables. It has identical syntax and identical functionality in native mode and Java mode.

Syntax

dbxenv: Display the current settings of the dbx environment variables.
dbxenv environment_variable setting: Set environment_variable to setting.

where:

environment_variable is a dbx environment variable.

setting is a valid setting for that variable.

`debug` Command

The debug command lists or changes the program being debugged. In native mode, it loads the specified application and begins debugging the application. In Java mode, it loads the specified Java application, checks for the existence of the class file, and begins debugging the application.

Native Mode Syntax

debug: Print the name and arguments of the program being debugged.
debug program_name: Begin debugging program_name with no process or core.
debug -c core program_name: Begin debugging program_name with core file core.
debug -p process_id program_name: Begin debugging program_name with process ID process_id.
debug program_name core: Begin debugging program with core file core. program_name may be -. dbx will attempt to extract the name of the executable from the core file. For details, see Debugging a Core File.
debug program_name process_id: Begin debugging program_name with process ID process_id. program_name may be -; dbx finds it using /proc.
debug -f ...: Force loading of a core file, even if it doesn’t match.
debug -r ...: The -r option causes dbx to retain all display, trace, when, andstop commands. With no -r option, an implicitdelete all andundisplay O are performed.
debug -clone ...: The -clone option causes another dbx process to begin execution, permitting debugging of more than one process at a time. Valid only if running in the Sun Studio IDE..
debug -clone: Starts another dbx process debugging nothing. Valid only if running in the Sun Studio IDE.
debug [options] -- program_name: Start debugging program_name, even if program_name begins with a dash.

where:

core is the name of a core file.

options are the options listed inOptions.

pid is the process ID of a running process.

program_name is the path name of the program.

Leaks checking and access checking are turned off when a program is loaded with the debug command. You can enable them with the check command (see check Command).

Java Mode Syntax

debug: Print the name and arguments of the program being debugged.
debug program_name [.class | .jar]: Begin debugging program_name with no process.
debug -p process_id program_name [.class | .jar]: Begin debugging program_name with process ID process_id.
debug program_name [.class | .jar] process_id: Begin debugging program_name with process ID process_id. program_name may be -; dbx finds it using /proc
debug -r: The -r option causes dbx to retain all watch commands, display commands, trace commands, when commands, andstop commands. With no -r option, an implicitdelete all command and undisplay 0 command are performed.
debug -clone ...: The -clone option causes another dbx process to begin execution, permitting debugging of more than one process at a time. Valid only if running in the Sun Studio IDE.
debug -clone: Starts another dbx process debugging nothing. Valid only if running in the Sun Studio IDE.
debug [options] -- program_name{.class | .jar}: Start debugging program_name, even if program_name begins with a dash.

where:

file_name is the name of a file.

options are the options listed inOptions.

process_id is the process ID of a running process.

program_name is the path name of the program.

Options

-c commands: Execute commands before prompting for input.
-d: Used with -s, removes
-e: Echo input commands.
-I directory_name: Add directory_name to pathmap set (see pathmap Command.
-k: Save and restore keyboard translation state.
-q: Suppress messages about reading stabs.
-r: Run program; if program exits normally, then exit.
-R: Print the readme file fordbx.
-s file: Use file instead of /current_directory/.dbxrc or $HOME/.dbxrc as the startup file
-S: Suppress reading of initialization file /installation_directory/lib/dbxrc.
-V: Print the version of dbx.
-w n: Skip n frames on where command.
--: Marks the end of the option list; use this if the program name starts with a dash.

`delete` Command

The delete command deletes breakpoints and other events. It has identical syntax and identical functionality in native mode and Java mode.

Syntax

delete [-h] handler_id ...: Remove trace commands, when commands, or stop commands of given handler_id(s). To remove hidden handlers, you must give the -hoption.
delete [-h] O | all | -all: Remove all trace commands, when commands, and stopcommands excluding permanent and hidden handlers. Specifying -hremoves hidden handlers as well.
delete -temp: Remove all temporary handlers.
delete $firedhandlers: Delete all the handlers that caused the latest stoppage.

where:

handler_id is the identifier of a handler.

`detach` Command

The detach command releases the target process from dbx’s control.

Native Mode Syntax

detach: Detach dbx from the target, and cancel any pending signals.
detach -sig signal: Detach while forwarding the given signal.
detach -stop: Detach dbx from the target and leave the process in a stopped state. This option allows temporary application of other /proc-based debugging tools that might be blocked due to exclusive access. For an example, see Detaching dbx From a Process.

where:

signal is the name of a signal.

Java Mode Syntax

detach: Detach dbx from the target, and cancel any pending signals.

`dis` Command

The dis command disassembles machine instructions. It is valid only in native mode.

Syntax

dis [ -a ] address [/count]: Disassemble count instructions (default is 10), starting at address address.
dis address1, address2: Disassemble instructions from address1 through address2.
dis: Disassemble 10 instructions, starting at the value of + (see examine Command).

where:

address is the address at which to start disassembling. The default value of address is the address after the last address previously assembled. This value is shared by the examine command (see examine Command).

address1 is the address at which to start disassembling.

address2 is the address at which to stop disassembling.

count is the number of instructions to disassemble. The default value of count is 10.

Options

-a: When used with a function address, disassembles the entire function. When used without parameters, disassembles the remains of the current visiting function, if any.

`display` Command

In native mode, the display command reevaluates and prints expressions at every stopping point. In Java mode, the display command evaluates and prints expressions, local variables, or parameters at every stopping point. Object references are expanded to one level and arrays are printed itemwise.

The expression is parsed the current scope at the time you type the command, and reevaluated at every stopping point. Because the expression is parsed at entry time, the correctness of the expression can be immediately verified.

Native Mode Syntax

display: Print the list of expressions being displayed.
display expression, ...: Display the value of expressions expression, ... at every stopping point.
display [-r|+r|-d|+d|-p|+p|-L|-fformat|-Fformat|--] expression, ...: See print Command for the meaning of these flags.

where:

expression is a valid expression.

format is the output format you want used to print the expression. For information on valid formats, see print Command.

Java Mode Syntax

display: Print the list of variables and parameters being displayed.
display expression|identifier, ...: Display the value of variables and parameters of identifier, ... at every stopping point.
display [-r|+r|-d|+d|-p|+p|-fformat|-Fformat|-Fformat|--] expression|identifier, ...: See print Command for the meaning of these flags.

where:

expression is a valid Java expression.

field_name is the name of a field in the class.

format is the output format you want used to print the expression. For information on valid formats, see print Command.

identifier is a local variable or parameter, including this, the current class instance variable (object_name.field_name) or a class (static) variable (class_name.field_name).

object_name is the name of a Java object.

`down` Command

The down command moves down the call stack (away from main). It has identical syntax and identical functionality in native mode and Java mode.

Syntax

down: Move down the call stack one level.
down number: Move down the call stack number levels.
down -h [number]: Move down the call stack, but don’t skip hidden frames.

where:

number is a number of call stack levels.

`dump` Command

The dump command prints all variables local to a procedure. It has identical syntax and identical functionality in native mode and Java mode.

Syntax

dump: Print all variables local to the current procedure.
dump procedure: Print all variables local to procedure.

where:

procedure is the name of a procedure.

`edit` Command

The edit command invokes $EDITOR on a source file. It is valid only in native mode.

The edit command uses $EDITOR if dbx is not running in the Sun Studio IDE. Otherwise, it sends a message to the IDE to display the appropriate file.

Syntax

edit: Edit the current file.
edit file_name: Edit the specified file file_name.
edit procedure: Edit the file containing function or procedure procedure.

where:

file_name if the name of a file.

procedure is the name of a function or procedure.

`examine` Command

The examine command shows memory contents. It is valid only in native mode.

Syntax

examine [address] [ / [count] [format]]

Display the contents of memory starting at address for count items in format format.

examine address1, address2 [ / [format]]

Display the contents of memory from address1 through address2 inclusive, in format format.

examine address= [format]

Display the address (instead of the contents of the address) in the given format.

The address may be +, which indicates the address just after the last one previously displayed (the same as omitting it).

x is a predefined alias for examine.

where:

address is the address at which to start displaying memory contents. The default value of address is the address after the address whose contents were last displayed. This value is shared by the dis command (see dis Command).

address1 is the address at which to start displaying memory contents.

address2 is the address at which to stop displaying memory contents.

count is the number of addresses from which to display memory contents. The default value of count is 1.

format is the format in which to display the contents of memory addresses. The default format is X (hexadecimal) for the first examine command, and the format specified in the previous examine command for subsequent examine commands. The following values are valid for format:

o,O: octal (2 or 4 bytes)
x,X: hexadecimal (2 or 4 bytes)
b: octal (1 byte)
c: character
w: wide character
s: string
W: wide character string
f: hexadecimal and floating point (4 bytes, 6 digit precision)
F: hexadecimal and floating point (8 bytes, 14 digit precision )
g: same as F
E: hexadecimal and floating point (16 bytes, 14 digit precision)
ld,lD: decimal (4 bytes, same as D)
lo,lO: octal 94 bytes, same as O
lx,lX: hexadecimal (4 bytes, same as X)
Ld,LD: decimal (8 bytes)
Lo,LO: octal (8 bytes)
Lx,LX: hexadecimal (8 bytes)

`exception` Command

The exception command prints the value of the current C++ exception. It is valid only in native mode.

Syntax

exception [-d | +d]: Prints the value of the current C++ exception, if any.

See the print Command for the meaning of the -d flag.

`exists` Command

The exists command checks for the existence of a symbol name. It is valid only in native mode.

Syntax

exists name: Returns 0 if name is found in the current program, 1 if name is not found.

where:

name is the name of a symbol.

`file` Command

The file command lists or changes the current file. It has identical syntax and identical functionality in native mode and in Java mode.

Syntax

file: Print the name of the current file.
file file_name: Change the current file.

where:

file_name is the name of a file.

`files` Command

In native mode, the files command lists file names that match a regular expression. In Java mode, the files command lists all of the Java source files known to dbx. If your Java source files are not in the same directory as the .class or .jar files, dbx might not find them unless you have set the $JAVASRCPATH environment variable (see Specifying the Location of Your Java Source Files).

Native Mode Syntax

files: List the names of all files that contributed debugging information to the current program (those that were compiled with -g).
files regular_expression: List the names of all files compiled with-g that match the given regular expression.

where:

regular_expression is a regular expression.

For example:

(dbx) files ^r
myprog:
retregs.cc
reg_sorts.cc
reg_errmsgs.cc
rhosts.cc

Java Mode Syntax

files: List the names of all of the Java source files known to dbx.

`fix` Command

The fix command recompiles modified source files and dynamically links the modified functions into the application. It is valid only in native mode. It is not valid on Linux platforms.

Syntax

fix: Fix the current file.
fix file_name file_name: Fix files in list.
fix -f: Force fixing the file, even if source hasn’t been modified.
fix -a: Fix all modified files.
fix -g: Strip -O flags amd add -g flag.
fix -c: Print compilation line (may include some options added internally for use by dbx).
fix -n: Do not execute compile/link commands (use with -v).
fix -v: Verbose mode (overrides dbx fix_verbose environment variable setting).
fix +v: Non-verbose mode (overrides dbx fix_verbose environment variable setting).

`fixed` Command

The fixed command lists the names of all fixed files. It is valid only in native mode.

Syntax

fixed

`fortran_modules` Command

The fortran_modules command lists the Fortran modules in the current program, or the functions or variables in one of the modules.

Syntax

fortran_modules: Lists all Fortran modules in the current program.
fortran_modules -f module_name: Lists all functions in the specified module.
fortran_modules -v module_name: Lists all variables in the specified module.

`frame` Command

The frame command lists or changes the current stack frame number. It has identical syntax and identical functionality in native mode and in Java mode.

Syntax

frame: Display the frame number of the current frame.
frame [-h] number: Set the current frame to frame number.
frame [-h] +[number]: Go number frames up the stack; default is 1.
frame [-h] -[number]: Go number frames down the stack; default is 1.
-h: Go to frame, even if frame is hidden.

where:

number is the number of a frame in the call stack.

`func` Command

In native mode, the func command lists or changes the current function. In Java mode, the func command lists or changes the current method.

Native Mode Syntax

func: Print the name of the current function.
func procedure: Change the current function to the function or procedure procedure.

where:

procedure is the name of a function or procedure.

Java Mode Syntax

func: Print the name of the current method.
func [class_name.]method_name [(parameters)]: Change the current function to the method method_name.

where:

method_name is the name of a Java method.

parameters are the method’s parameters.

`funcs` Command

The funcs command lists all function names that match a regular expression. It is valid only in native mode.

Syntax

funcs: List all functions in the current program.
funcs [-f file_name] [-g] [regular_expression]: If -f file_name is specified, list all functions in the file. If -g is specified, list all functions with debugging information. If regular_expression is specified, list all functions that match the regular expression.

where:

file_name is the name of the file for which you wish to list all the functions.

regular_expression is the regular expression for which you wish to list all the matching functions.

For example:

(dbx) funcs [vs]print
”libc.so.1”isprint
”libc.so.1”wsprintf
”libc.so.1”sprintf
”libc.so.1”vprintf
”libc.so.1”vsprintf

`gdb` Command

The gdb command supports the gdb command set. It is valid only in native mode.

Syntax

gdb on | off: Usegbd on to enter the gdb command mode under which dbx understands and accepts gdb commands. To exit the gdb command mode and return to the dbx command mode, type gdb off. dbx commands are not accepted while in gdb command mode and vice versa. All debugging settings such as breakpoints are preserved across different command modes.

gdb on | off

The following gdb commands are not supported in this release:

commands
define
handle
hbreak
interrupt
maintenance
printf
rbreak
return
signal
tcatch
until

`handler` Command

The handler command modifies event handlers (enable, disable, etc.). It has identical syntax and identical functionality in native mode and in Java mode.

A handler is created for each event that needs to be managed in a debugging session. The commands trace, stop, and whencreate handlers. Each of these commands returns a number known as the handler ID (handler_id). The handler, status, anddelete commands manipulate or provide information about handlers in a generic fashion.

Syntax

handler -enable handler_id ...: Enable given handlers, specify handler_id as all for all handlers.
handler -disable handler_id ...: Disable given handlers, specify handler_id as all for all handlers. Use $firedhandlers instead of handler_id to disable the handlers that caused the most recent stoppage.
handler -count handler_id: Print value of trip counter for given handler.
handler -count handler_id new_limit: Set new count limit for given event.
handler -reset handler_id: Reset trip counter for given handler.

where:

handler_id is the identifier of a handler.

`hide` Command

The hide command hides stack frames that match a regular expression. It is valid only in native mode.

Syntax

hide: List the stack frame filters currently in effect.
hide regular_expression: Hide stack frames matching regular_expression. The regular expression matches either the function name, or the name of the load object, and is a sh or ksh file matching style regular expression.

where:

regular_expression is a regular expression.

`ignore` Command

The ignore command tells the dbx process not to catch the given signal(s). It is valid only in native mode.

Ignoring a signal causes dbx not to stop when the process receives that kind of signal.

Syntax

ignore: Print a list of the ignored signals.
ignore number ...: Ignore signal(s) numbered number.
ignore signal ...: Ignore signal(s) named by signal. SIGKILL cannot be caught or ignored.

where:

number is the number of a signal.

signal is the name of a signal.

`import` Command

The import command imports commands from a dbx command library. It has identical syntax and identical functionality in native mode and in Java mode.

Syntax

import path_name: Import commands from the dbx command library path_name.

where:

path_name is the path name of a dbx command library.

`intercept` Command

The intercept command throws (C++ exceptions) of the given type (C++ only). It is valid only in native mode.

dbx stops when the type of a thrown exception matches a type on the intercept list unless the type of the exception also matches a type on the excluded list. A thrown exception for which there is no matching catch is called an “unhandled” throw. A thrown exception that doesn’t match the exception specification of the function it is thrown from is called an “unexpected” throw.

Unhandled and unexpected throws are intercepted by default.

Syntax

intercept -x excluded_typename [, excluded_typename ...]: Add throws of excluded_typename to the excluded list.
intercept -a[ll] -x excluded_typename [, excluded_typename ...]: Add all types except excluded_typename to the intercept list.
intercept -s[et] [intercepted_typename [, intercepted_typename ...]] [-x excluded_typename [, excluded_typename]]: Clear both the intercept list and the excluded list, and set the lists to intercept or exclude only throws of the specified types.
intercept: List intercepted types.

where:

included_typename and excluded_typename are exception type specifications such as List <int> or unsigned short.

`java` Command

The java command is used when dbx is in JNI mode to indicate that the Java version of a specified command is to be executed. It causes the specified command to use the Java expression evaluator, and when relevant, to display Java threads and stack frames.

Syntax

java command

where:

command is the command name and arguments of the command to be executed.

`jclasses` Command

The jclasses command prints the names of all Java classes known to dbx when you give the command. It is valid only in Java mode.

Classes in your program that have not yet been loaded are not printed.

Syntax

jclasses: Print the names of all Java classes known to dbx.
jclasses -a: Print system classes as well as other known Java classes.

`joff` Command

The joffcommand switches dbx from Java mode or JNI mode to native mode.

Syntax

joff

`jon` Command

The jon command switches dbx from native mode to Java mode.

Syntax

jon

`jpkgs` Command

The jpkgs command prints the names of all Java packages known to dbx when you give the command. It is valid only in Java mode.

Packages in your program that have not yet been loaded are not printed.

Syntax

jpkgs

`kill` Command

The kill command sends a signal to a process. It is valid only in native mode.

Syntax

kill -l: List all known signal numbers, names, and descriptions.
kill: Kill the controlled process.
kill job ...: Send the SIGTERM signal to the listed jobs.
kill -signal job ...: Send the given signal to the listed jobs.

where:

job may be a process ID or may be specified in any of the following ways:

%+: Kill the current job.
%-: Kill the previous job.
%number: Kill job number number.
%string: Kill the job that begins with string.
%?string: Kill the job that contains string.

signal is the name of a signal.

`language` Command

The language command lists or changes the current source language. It is valid only in native mode.

Syntax

language: Print the current language mode set by the dbx language_mode environment variable (see Setting dbx Environment Variables). If the language mode is set to autodetect or main, the command also prints the name of the current language used for parsing and evaluating expressions.

where:

language is c, c++, fortran, or fortran90.

Note –

c is an alias for ansic.

`line` Command

The line command lists or change the current line number. It has identical syntax and identical functionality in native mode and in Java mode.

Syntax

line: Display the current line number.
line number: Set the current line number to number.
line "file_name": Set current line number to line 1 in file_name.
line "file_name":number: Set current line number to line number in file_name.

where:

file_name is the name of the file in which to change the line number. The ““ around the filename is optional.

number is the number of a line in the file.

Examples

line 100
line "/root/test/test.cc":100

`list` Command

The list command displays lines of a source file. It has identical syntax and identical functionality in native mode and in Java mode.

The default number of lines listed, N, is controlled by the dbx output_list_size environment variable.

Syntax

list: List N lines.
list number: List line number number.
list +: List next N lines.
list +n: List next n lines.
list -: List previous N lines.
list: List previous n lines.
list n1, n2: List lines from n1 to n2.
list n1, +: List from n1 to n1 + N.
list n1, +n2: List from n1 to n1 + n2.
list n1, -: List from n1-N to n1.
list n1, -n2: List from n1-n2 to n1.
list function: List the start of the source for function. list function changes the current scope. See Program Scope for more information.
list file_name: List the start of the file file_name.
list file_name:n: List file filename from line n. Where appropriate, the line number may be ”$” which denotes the last line of the file. Comma is optional.

where:

file_name is the file name of a source code file.

function is the name of a function to display.

number is the number of a line in the source file.

n is a number of lines to display.

n1 is the number of the first line to display.

n2 is the number of the last line to display.

Options

-i or -instr: Intermix source lines and assembly code.
-w or -wn: List N (or n) lines (window) around line or function. This option is not allowed in combination with the ”+” or ”-” syntax or when two line numbers are specified.
-a: When used with a function name, lists the entire function. When used without parameters, lists the remains of the current visiting function, if any.

Examples

list                      // list N lines starting at current line
list +5                      // list next 5 lines starting at current line
list -                    // list previous N lines
list -20                  // list previous 20 lines
list 1000                 // list line 1000
list 1000,$               // list from line 1000 to last line
list 2737 +24             // list line 2737 and next 24 lines
list 1000 -20             // list line 980 to 1000
list test.cc:33           // list source line 33 in file test.cc
list -w                   // list N lines around current line
list -w8 ”test.cc”func1   // list 8 lines around function func1
list -i 500 +10                // list source and assembly code for line
                500 to line 510

`listi` Command

The listi command displays source and disassembled instructions. It is valid only in native mode.

See list Command for details.

`loadobject` Command

The loadobject command lists and manages symbolic information from load objects. It is valid only in native mode.

Syntax

loadobject -list [regexp] [-a]: Show currently loaded load objects (see loadobject -list Command
load -load loadobject: Load symbols for specified load object (see loadobject -load Command).
load -unload [regexp]: Unload specified load objects (see loadobject -unload Command).
load -hide [regexp]: Remove load object from dbx's search algorithm (see loadobject -hide Command).
loadobject -use [regexp]: Add load object to dbx's search algorithm (see loadobject -use Command).
load -dumpelf [regexp]: Show various ELF details of the load object (see loadobject -dumpelf Command).
loadobject -exclude ex_regexp: Don't automatically load load objects matching ex_regexp (see loadobject -exclude Command).
loadobject exclude -clear: Clear the exclude list of patterns (see loadobject -exclude Command).

where:

regexp is a regular expression. If it is not specified the command applies to all load objects.

ex-regexp is not optional, it must be specified.

This command has a default alias lo.

`loadobject -dumpelf` Command

The loadobject -dumpelf command shows various ELF details of the load object. It is valid only in native mode.

Syntax

loadobject -dumpelf [regexp]

where:

regexp is a regular expression. If it is not specified the command applies to all load objects.

This command dumps out information related to the ELF structure of the load object file on disk. The details of this output are highly subject to change. If you want to parse this output, use the Solaris OS commands dump or elfdump.

`loadobject -exclude` Command

The loadobject -exclude command tells dbx not to automatically load load objects matching the specified regular expression.

Syntax

loadobject -exclude ex_regexp [-clear]

where:

ex_regexp is a regular expression.

This command prevents dbx from automatically loading symbols for load objects that match the specified regular expression. Unlike regexp in other loadobject subcommands, if ex_regexp is not specified, it does not default to all. If you do not specify ex_regexp, the command lists the excluded patterns that have been specified by previous loadobject -exclude commands.

If you specify -clear, the list of excluded patterns is deleted.

Currently this functionality cannot be used to prevent loading of the main program, or the runtime linker. Also, using it to prevent loading of C++ runtime libraries could cause the failure of some C++ functionality.

This option should not be used with runtime checking (RTC).

`loadobject -hide` Command

The loadobject -hide command removes loadobjects from dbx’s search algorithm.

Syntax

loadobject -hide [regexp]

where:

regexp is a regular expression. If it is not specified the command applies to all load objects.

This command removes a load object from the program scope, and hides its functions and symbols from dbx. This command also resets the ’preload’ bit

`loadobject -list` Command

The loadobject -list command shows currently loaded loadobjects. It is valid only in native mode.

Syntax

loadobject -list [regexp] [-a]

where:

regexp is a regular expression. If it is not specified the command applies to all load objects.

The full path name for each load object is shown along with letters in the margin to show status. Load objects that are hidden are listed only if you specify the -a option.

h: This letter means “hidden” (the symbols are not found by symbolic queries like whatis or stop in).
u: If there is an active process, u means “unmapped.”
p: This letter indicates a load object that is preloaded, that is, the result of a loadobject -load command or a dlopen event in the program.

For example:

(dbx) lo -list libm
/usr/lib/64/libm.so.1
/usr/lib/64/libmp.so.2
(dbx) lo -list ld.so
h  /usr/lib/sparcv9/ld.so.1 (rtld)

This last example shows that the symbols for the runtime linker are hidden by default. To use those symbols in dbxcommands, see loadobject -use Command.

`loadobject -load` Command

The loadobject -load command loads symbols for specified load objects. It is valid only in native mode.

Syntax

loadobject -list [regexp] [-a]

where:

loadobject can be a full path name or a library in /usr/lib or /usr/lib/sparcv9. If there is a program being debugged, then only the proper ABI library directory will be searched.

`loadobject -unload` Command

The loadobject -unload command unloads specified load objects. It is valid only in native mode.

Syntax

loadobject -unload [regexp]

where:

regexp is a regular expression. If it is not specified the command applies to all load objects.

This command unloads the symbols for any load objects matching the regexp supplied on the command line. The main program loaded with the debug command cannot be unloaded. dbx may also refuse to unload other load objects that might be currently in use, or critical to the proper functioning of dbx.

`loadobject -use` Command

The loadobject -use command adds load objects from dbx’s search algorithm. It is valid only in native mode.

Syntax

loadobject -use [regexp]

where:

regexp is a regular expression. If it is not specified the command applies to all load objects.

`lwp` Command

The lwp command lists or changes the current LWP (lightweight process). It is valid only in native mode.

Note –

The lwp command is available only on Solaris platforms.

Syntax

lwp: Display current LWP.
lwp lwp_id: Switch to LWP lwp_id.
lwp -info: Displays the name, home, and masked signals of the current lwp.
lwp [lwp_id] -setfp address_expression: Tells dbx that the fp register has the value address_expression. The state of the program being debugged is not changed. debugging a core file, where assign $fp=... is unavailable. A frame pointer set with the -setfp option is reset to its original value upon resuming execution.
lwp [lwp_id] -resetfp: Sets the frame pointer logical value from the register value in the current process or core file, undoing the effect of a previous lwp -setfp command.

where:

lwp_id is the identifier of a lightweight process.

If the command is used with both an lwp_id and an option, corresponding action is applied to LWP specified by the lwp_id, but the current LWP is not changed.

The -setfp and -resetfp options are useful when the frame pointer (fp) of the LWP is corrupted. In this event, dbx cannot reconstruct the call stack properly and evaluate local variables. These options work when debugging a core file, where assign $fp=... is unavailable.

To make changes to the fp register visible to the application being debugged, use the assign $fp=address_expression command.

`lwps` Command

The lwps command lists all LWPs (lightweight processes) in the process. It is valid only in native mode.

Note –

The lwps command is available only on Solaris platforms.

Syntax

lwps: List all LWPs in the current process.

`mmapfile` Command

The mmapfile command views the contents of memory mapped files that are missing from a core dump. It is valid only in native mode.

Solaris core files do not contain any memory segments that are read-only. Executable read-only segments (that is, text) are dealt with automatically and dbx resolves memory accesses against these by looking into the executable and the relevant shared objects.

Syntax

mmapfile mmapped_file address offset length: View contents of memory mapped files missing from core dump.

where:

mmapped_file is the file name of a file that was memory mapped during a core dump.

address is the starting address of the address space of the process.

length is length in bytes of the address space to be viewed.

offset is the offset in bytes to the starting address in mmapped_file.

`module` Command

The module command reads debugging information for one or more modules. It is valid only in native mode.

Syntax

module [-v]: Print the name of the current module.
module [-f] [-v] [-q] name: Read in debugging information for the module called name.
module [-f] [-v] [-q] -a: Read in debugging information for all modules.

where:

name is the name of a module for which to read debugging information.

-a specifies all modules.

-f forces reading of debugging information, even if the file is newer than the executable (use with caution!).

-v specifies verbose mode, which prints language, file names, etc.

-q specifies quiet mode.

Example

Read-only data segments typically occur when an application memory maps a database. For example:

caddr_t vaddr = NULL;
off_t offset = 0;
size_t = 10 * 1024;
int fd;
fd = open("../DATABASE", ...)
vaddr = mmap(vaddr, size, PROT_READ, MAP_SHARED, fd, offset);
index = (DBIndex *) vaddr;

To be able to access the database through the debugger as memory you would type:

mmapfile ../DATABASE $[vaddr] $[offset] $[size]

Then you could look at your database contents in a structured way by typing:

print *index

`modules` Command

The modules command lists module names. It is valid only in native mode.

Syntax

modules [-v]: List all modules.
modules [-v] -debug: List all modules containing debugging information.
modules [-v] -read: List names of modules containing debugging information that have been read in already.

where:

-v specifies verbose mode, which prints language, file names, etc.

`native` Command

The native command is used when dbx is in Java mode to indicate that the native version of a specified command is to be executed. Preceding a command with “native” results in dbx executing the command in native mode. This means that expressions are interpreted and displayed as C expressions or C++ expressions, and certain other commands produce different output than they do in Java mode.

This command is useful when you are debugging Java code but you want to examine the native environment.

Syntax

native command

where:

command is the command name and arguments of the command to be executed.

`next` Command

The next command steps one source line (stepping over calls).

The dbx step_events environment variable (see Setting dbx Environment Variables) controls whether breakpoints are enabled during a step.

Native Mode Syntax

next: Step one line (step over calls). With multithreaded programs when a function call is stepped over, all LWPs (lightweight processes) are implicitly resumed for the duration of that function call in order to avoid deadlock. Non-active threads cannot be stepped.
next n: Step n lines (step over calls).
next ... -sig signal: Deliver the given signal while stepping.
next ... thread_id: Step the given thread.
next ... lwp_id: Step the given LWP. Will not implicitly resume all LWPs when stepping over a function.

where:

n is the number of lines to step.

signal is the name of a signal.

thread_id is a thread ID.

lwp_id is an LWP ID.

When an explicit thread_id or lwp_id is given, the deadlock avoidance measure of the generic next command is defeated.

See also nexti Command for machine-level stepping over calls.

Note –

For information on lightweight processes (LWPs), see the Solaris Multithreaded Programming Guide.

Java Mode Syntax

next: Step one line (step over calls). With multithreaded programs when a function call is stepped over, all LWPs (lightweight processes) are implicitly resumed for the duration of that function call in order to avoid deadlock. Non-active threads cannot be stepped.
next n: Step n lines (step over calls).
next ... thread_id: Step the given thread.
next ... lwp_id: Step the given LWP. Will not implicitly resume all LWPs when stepping over a function.

where:

n is the number of lines to step.

thread_id is a thread identifier.

lwp_id is an LWP identifier.

When an explicit thread_id or lwpid is given, the deadlock avoidance measure of the generic next command is defeated.

Note –

For information on lightweight processes (LWPs), see the Solaris Multithreaded Programming Guide. threaded Programming Guide.

`nexti` Command

The nexti command steps one machine instruction (stepping over calls). It is valid only in native mode.

Syntax

nexti: Step one machine instruction (step over calls).
nexti n: Step n machine instructions (step over calls).
nexti -sig signal: Deliver the given signal while stepping.
nexti ... lwp_id: Step the given LWP.
nexti ... thread_id: Step the LWP on which the given thread is active. Will not implicitly resume all LWPs when stepping over a function.

where:

n is the number of instructions to step.

signal is the name of a signal.

thread_id is a thread ID.

lwp_id is an LWP ID.

`pathmap` Command

The pathmap command maps one path name to another for finding source files, etc. The mapping is applied to source paths, object file paths and the current working directory (if you specify -c). The pathmap command has identical syntax and identical functionality in native mode and in Java mode.

The pathmap command is useful for dealing with automounted and explicit NFS mounted filesystems with different paths on differing hosts. Specify -c when you are trying to correct problems arising due to the automounter since CWD’s are inaccurate on automounted filesystems as well. The pathmap command is also useful if source or build trees are moved.

pathmap /tmp_mnt / exists by default.

The pathmap command is used to find load objects for core files when the dbx environment variable core_lo_pathmap is set to on. Other than this case, the pathmap command has no effect on finding load objects (shared libraries). See Debugging a Mismatched Core File.

Syntax

pathmap [ -c ] [ -index ] from to: Establish a new mapping from from to to.
pathmap [ -c ] [ -index ] to: Map all paths to to.
pathmap: List all existing path mappings (by index).
pathmap -s: The same, but the output can be read by dbx.
pathmap -d from1 from2 ...: Delete the given mapping(s) by path.
pathmap -d index1 index2 ...: Delete the given mapping(s) by index.

where:

from and to are filepath prefixes. from refers to the filepath compiled into the executable or object file and to refers to the filepath at debug time.

from1 is filepath of the first mapping to be deleted.

from2 is filepath of the last mapping to be deleted.

index specifies the index with which the mapping is to be inserted in the list. If you do not specify an index, the mapping is added to the end of the list.

index1 is the index of the first mapping to be deleted.

index2 is the index of the last mapping to be deleted.

If you specify -c, the mapping is applied to the current working directory as well.

If you specify -s, the existing mappings are listed in an output format that dbx can read.

If you specify -d, the specified mappings are deleted.

Examples

(dbx) pathmap /export/home/work1 /net/mmm/export/home/work2
  # maps /export/home/work1/abc/test.c to /net/mmm/export/home/work2/abc/test.c
(dbx) pathmap /export/home/newproject
  # maps /export/home/work1/abc/test.c to /export/home/newproject/test.c
(dbx) pathmap
(1) -c /tmp_mnt /
(2) /export/home/work1 /net/mmm/export/home/work2
(3) /export/home/newproject

`pop` Command

The pop command removes one or more frames from the call stack. It is valid only in native mode.

You can pop only to a frame for a function that was compiled with -g. The program counter is reset to the beginning of the source line at the callsite. You cannot pop past a function call made by the debugger; use pop -c.

Normally a pop command calls all the C++ destructors associated with the popped frames; you can override this behavior by setting the dbx pop_auto_destruct environment variable to off (see Setting dbx Environment Variables).

Syntax

pop: Pop current top frame from stack.
pop number: Pop number frames from stack.
pop -f number: Pop frames from stack until specified frame number.
pop -c: Pop the last call made from the debugger.

where:

number is the number of frames to pop from the stack.

`print` Command

In native mode, the print command prints the value of an expression. In Java mode, the print command prints the value of an expression, local variable, or parameter.

Native Mode Syntax

print expression, ...: Print the value of the expression(s) expression, ... .
print -r expression: Print the value of the expression expression including its inherited members (C++ only).
print +r expression: Don’t print inherited members when the dbx output_inherited_members environment variable is on (C++ only).
print -d [-r] expression: Show dynamic type of expression expression instead of static type (C++ only).
print +d [-r] expression: Don’t use dynamic type of expression expression when the dbx output_dynamic_type environment variable is on (C++ only).
print -p expression: Call the prettyprint function.
print +p expression: Do not call the prettyprint Function when the dbx output_pretty_print environment variable is on.
print -L expression: If the printing object expression is larger than 4K, enforce the printing.
print +l expression: If the expression is a string (char *), print the address only, do not print the literal.
print -l expression: ('Literal’) Do not print the left side. If the expression is a string (char *), do not print the address, just print the raw characters of the string, without quotes.
print -fformat expression: Use format as the format for integers, strings, or floating-point expressions.
print -Fformat expression: Use the given format but do not print the left hand side (the variable name or expression).
print -o expression: Print the value of expression, which must be an enumeration as an ordinal value. You may also use a format string here (-fformat). This option is ignored for non-enumeration expressions.
print -- expression: ”--’ signals the end of flag arguments. This is useful if expression may start with a plus or minus (seeProgram Scope for scope resolution rules.

where:

expression is the expression whose value you want to print.

format is the output format you want used to print the expression. If the format does not apply to the given type, the format string is silently ignored and dbx uses its built-in printing mechanism.

The allowed formats are a subset of those used by the printf(3S) command. The following restrictions apply:

No n conversion.
No * for field width or precision.
No %<digits>$ argument selection.
Only one conversion specification per format string.

The allowed forms are defined by the following simple grammar:

FORMAT ::= CHARS % FLAGS WIDTH PREC MOD SPEC CHARS

CHARS ::= <any character sequence not containing a %>

| %%

| <empty>

| CHARS CHARS

FLAGS ::= + | - | <space> | # | 0 | <empty>

WIDTH ::= <decimal_number> | <empty>

PREC ::= . | . <decimal_number> | <empty>

MOD ::= h | l | L | ll | <empty>

SPEC ::= d | i | o | u | x | X | f | e | E | g | G |

c | wc | s | ws | p

If the given format string does not contain a %, dbx automatically prepends one. If the format string contains spaces, semicolons, or tabs, the entire format string must be surrounded by double quotes.

Java Mode Syntax

print expression, ... | ...: Print the value(s) of the expression(s) expression, ... or identifier(s) identifier, ....
print -r expression | identifier: Print the value of expression or identifier including its inherited members.
print +r expression | identifier: Don’t print inherited members when the dbx output_inherited_members environment variable is on.
print -d [-r] expression | identifier: Show dynamic type of expression or identifier instead of static type.
print +d [-r] expression | identifier: Don’t use dynamic type of expression or identifier when the dbx output_dynamic_type environment variable is on.
print -- expression | identifier: ”--’ signals the end of flag arguments. This is useful if expression may start with a plus or minus (see Program Scope for scope resolution rules.

where:

expression is the Java expression whose value you want to print.

field_name is the name of a field in the class.

identifier is a local variable or parameter, including this, the current class instance variable (object_name.field_name) or a class (static) variable (class_name.field_name).

object_name is the name of a Java object.

`proc` Command

The proc command displays the status of the current process. It has identical syntax and identical functionality in native mode and in Java mode.

Syntax

proc -map: Show the list of loadobjects with addresses.
proc -pid: Show current process ID (pid).

`prog` Command

The prog command manages programs being debugged and their attributes. It has identical syntax and identical functionality in native mode and Java mode.

Syntax

prog -readsyms: Read symbolic information which was postponed by having set the dbx run_quick environment variable to on.
prog -executable: Prints the full path of the executable, - if the program was attached to using -.
prog -argv: Prints the whole argv, including argv[0].
prog -args: Prints the argv, excluding argv[0].
prog -stdin: Prints < filename or empty if stdin is used.
prog -stdout: Prints > filename or >> filename or empty if stdout is used. The outputs of -args, -stdin, -stdout are designed so that the strings can be combined and reused with the run command (see run Command).

`quit` Command

The quit command exits dbx. It has identical syntax and identical functionality in native mode and Java mode.

If dbx is attached to a process, the process is detached from before exiting. If there are pending signals, they are cancelled. Use the detach command (see detach Command) for fine control.

Syntax

quit: Exit dbx with return code 0. Same as exit.
quit n: Exit with return code n. Same as exit n.

where:

n is a return code.

`regs` Command

The regs command prints the current value of registers. It is valid only in native mode.

Syntax

regs [-f] [-F]

where:

-f includes floating-point registers (single precision) (SPARC platform only)

-F includes floating-point registers (double precision) (SPARC platform only)

Example (SPARC platform)

dbx[13] regs -F
current thread: t@1
current frame:  [1]
g0-g3              0x00000000 0x0011d000 0x00000000 0x00000000
g4-g7              0x00000000 0x00000000 0x00000000 0x00020c38
o0-o3              0x00000003 0x00000014 0xef7562b4 0xeffff420
o4-o7              0xef752f80 0x00000003 0xeffff3d8 0x000109b8
l0-l3              0x00000014 0x0000000a 0x0000000a 0x00010a88
l4-l7              0xeffff438 0x00000001 0x00000007 0xef74df54
i0-i3              0x00000001 0xeffff4a4 0xeffff4ac 0x00020c00
i4-i7              0x00000001 0x00000000 0xeffff440 0x000108c4
y                  0x00000000
psr                0x40400086
pc                 0x000109c0:main+0x4    mov     0x5, %l0
npc                0x000109c4:main+0x8    st      %l0, [%fp - 0x8]
f0f1               +0.00000000000000e+00
f2f3               +0.00000000000000e+00
f4f5               +0.00000000000000e+00
f6f7               +0.00000000000000e+00

`replay` Command

The replay command replays debugging commands since the last run, rerun, or debug command. It is valid only in native mode.

Syntax

replay [-number]: Replay all or all minus number commands since last run command, rerun command, ordebug command.

where:

number is the number of commands not to replay.

`rerun` Command

The rerun command runs the program with no arguments. It has identical syntax and identical functionality in native mode and Java mode.

Syntax

rerun: Begin executing the program with no arguments.
rerun arguments: Begin executing the program with new arguments by the save command (see save Command).

`restore` Command

The restore command restores dbxto a previously saved state. It is valid only in native mode.

Syntax

restore [file_name ]

where:

file_name is the name of the file to which the dbx commands executed since the last run, rerun, or debugcommand were saved.

`rprint` Command

The rprint command prints an expression using shell quoting rules. It is valid only in native mode.

Syntax

rprint [-r|+r|-d|+d|-p|+p|-L|-l|-f format | -Fformat | -- ] expression: Print the value of the expression. No special quoting rules apply, so rprint a > b puts the value of a (if it exists) into file b (see print Command for the meanings of the flags).

where:

expression is the expression whose value you want to print.

format is the output format you want used to print the expression. For information on valid formats, see print Command.

`rtc showmap` Command

The rtc showmap command reports the address range of program text categorized by instrumentation type (branches and traps). It is valid only in native mode.

Note –

The rtc showmap command is available only on Solaris platforms.

Syntax

rtc showmap

This command is intended for expert users, and internal debugging of dbx. Runtime checking instruments program text for access checking. The instrumentation type can be a branch or a trap instruction based on available resources. The rtc showmapcommand reports the address range of program text categorized by instrumentation type. This map can be used to find an optimal location for adding patch area object files, and to avoid the automatic use of traps. SeeRuntime Checking Limitations for details.

`rtc skippatch` Command

The rtc skippatch command excludes load objects, object files and functions from being instrumented by runtime checking.The effect of the command is permanent to each dbx session unless the load object is unloaded explicitly.

Since dbx does not track memory access in load objects, object files, and functions affected by this command, incorrect rui errors might be reported for functions that were not skipped. dbx cannot determine whether an rui error was introduced by this command, so such an error was not suppressed automatically.

Syntax

rtc skippatch load_object ...: Exclude the specified load objects from being instrumented.
rtc skippatch load_object [-o object_file ...] [-f function ...]: Exclude the specified object files and functions in the specified load object from being instrumented.

where:

load_object is the name of a load object or the path to the name of a load object.

object_file is the name of an object file.

function is the name of a function.

`run` Command

The run command runs the program with arguments.

Use Control-C to stop executing the program.

Native Mode Syntax

run: Begin executing the program with the current arguments.
run arguments: Begin executing the program with new arguments.
run ... >|>> output_file: Set the output redirection.
run ... < input_file: Set the input redirection.

where:

arguments are the arguments to be used in running the target process.

input_file is the file name of the file from which input is to be redirected.

output_file is the file name of the file to which output is to be redirected.

Note –

There is currently no way to redirect stderr using the run or runargs command.

Java Mode Syntax

run: Begin executing the program with the current arguments.
run arguments: Begin executing the program with new arguments.

where:

arguments are the arguments to be used in running the target process. They are passed to the Java application, not to the JVM software. Do not include the main class name as an argument.

You cannot redirect the input or output of a Java application with the run command.

Breakpoints you set in one run persist in subsequent runs.

`runargs` Command

The runargs command changes the arguments of the target process. It has identical syntax and identical functionality in native mode and Java mode.

Use the debug command (see debug Command) with no arguments to inspect the current arguments of the target process.

Syntax

runargs arguments: Set the current arguments, to be used by the run command (see run Command).
runargs ... >|>>file: Set the output redirection to be used by the run command.
runargs ... <file: Set the input redirection to be used by the run command.
runargs: Clear the current arguments.

where:

arguments are the arguments to be used in running the target process.

file is the file to which output from the target process or input to the target process is to be redirected.

`save` Command

The savecommand saves commands to a file. It is valid only in native mode.

Syntax

save [ -number ] [ file_name ]: Save all or all minus number commands since last run command, rerun command, ordebug command to the default file or file_name.

where:

number is the number of commands not to save.

filename is the name of the file to save the dbx commands executed since the last run, rerun, or debug command.

`scopes` Command

The scopes command prints a list of active scopes. It is valid only in native mode.

Syntax

scopes

`search` Command

The search command searches forward in the current source file. It is valid only in native mode

Syntax

search string: Search forward for string in the current file.
search: Repeat search, using last search string.

where:

string is the character string for which you wish to search.

`showblock` Command

The showblock command shows where the particular heap block was allocated from runtime checking. It is valid only in native mode.

Note –

The showblock command is available only on Solaris platforms.

When memory use checking or memory leak checking is turned on, the showblock command shows the details about the heap block at the specified address. The details include the location of the blocks’ allocation and its size. See check Command.

Syntax

showblock -a address

where:

address is the address of a heap block.

`showleaks` Command

The showleaks command reports new memory leaks since last showleaks command. It is valid only in native mode.

Note –

The showleaks command is available only on Solaris platforms.

In the default non-verbose case, a one line report per leak record is printed. Actual leaks are reported followed by the possible leaks. Reports are sorted according to the combined size of the leaks.

Syntax

showleaks [-a] [-m m] [-n number] [-v]

where:

-a shows all the leaks generated so far (not just the leaks since the last showleaks command).

-m m combines leaks; if the call stack at the time of allocation for two or more leaks matches m frames, then these leaks are reported in a single combined leak report. If the -m option is given, it overrides the global value of m specified with the check command (see check Command)..

-n number shows up to number records in the report. The default is to show all records.

-v Generate verbose output. The default is to show non-verbose output.

`showmemuse` Command

The showmemuse command shows memory used since last showmemuse command. It is valid only in native mode.

Note –

The showmemuse command is available only on Solaris platforms.

A one line report per “block in use” record is printed. The commands sorts the reports according to the combined size of the blocks. Any leaked blocks since the last showleaks command (see showleaks Command) are also included in the report.

Syntax

showmemuse [-a] [-m <m>] [-n number] [-v]

where:

-a shows all the blocks in use (not just the blocks since the last showmemuse command).

-m m combines the blocks in use reports. The default value of m is 2 or the global value last given with the check command (see check Command). If the call stack at the time of allocation for two or more blocks matches m frames then these blocks are reported in a single combined report. If the -m option is given, it overrides the global value of m.

-n number shows up to number records in the report. The default is 20.-v generates verbose output. The default is to show non-verbose output.

`source` Command

The source command executes commands from a given file. It is valid only in native mode.

Syntax

source file_name: Execute commands from file file_name. $PATH is not searched.

`status` Command

The status command lists event handlers (breakpoints, etc.). It has identical syntax and identical functionality in native mode and Java mode.

Syntax

status: Print trace, when, and stop breakpoints in effect.
status handler_id: Print status for handler handler_id.
status -h: Print trace, when, and stop breakpoints in effect including the hidden ones.
status -s: The same, but the output can be read by dbx.

where:

handler_id is the identifier of an event handler.

Example

(dbx) status -s > bpts
...
(dbx) source bpts

`step` Command

The step command steps one source line or statement (stepping into calls that were compiled with the -g option).

The dbx step_events environment variable controls whether breakpoints are enabled during a step.

The dbx step_granularity environment variable controls granularity of source linestepping.

The dbx step_abflow environment variable controls whether dbx stops when it detects that "abnormal" control flow change is about to occur. Such control flow change can be caused by a call to siglongjmp() or longjmp() or an exception throw.

Native Mode Syntax

step

Single step one line (step into calls). With multithreaded programs when a function call is stepped over, all threads are implicitly resumed for the duration of that function call in order to avoid deadlock. Non-active threads cannot be stepped.

step n

Single step n lines (step into calls).

step up

Step up and out of the current function.

step ... -sig signal

Deliver the given signal while stepping. If a signal handler exists for the signal, step into it if the signal handler was compiled with the -g option.

step ...thread_id

Step the given thread. Does not apply to step up.

step ...lwp_id

Step the given LWP. Does not implicitly resume all LWPs when stepping over a function.

step to [ function ]

Attempts to step into function called from the current source code line. If function is not given, steps into the last function, helping to avoid long sequences of step commands and step up commands. Examples of the last function are:

f()->s()-t()->last();

last(a() + b(c()->d()));

where:

n is the number of lines to step.

signal is the name of a signal.

thread_id is a thread ID.

lwp_id is an LWP ID.

function is a function name.

Only when an explicit lwp_id is given, the deadlock avoidance measure of the generic step command is defeated.

When executing the step tocommand, while an attempt is made to step into the last assemble call instruction or step into a function (if specified) in the current source code line, the call may not be taken due to a conditional branch. In a case where the call is not taken or there is no function call in the current source code line, the step to command steps over the current source code line. Take special consideration on user-defined operators when using the step to command.

See also stepi Command for machine-level stepping.

Java Mode Syntax

step: Single step one line (step into calls). With multithreaded programs when a method call is stepped over, all threads are implicitly resumed for the duration of that method call in order to avoid deadlock. Non-active threads cannot be stepped.
step n: Single step n lines (step into calls).
step up: Step up and out of the current method.
step ...thread_id: Step the given thread. Does not apply to step up.
step ...lwp_id: Step the given LWP. Does not implicitly resume all LWPs when stepping over a method.

`stepi` Command

The stepi command steps one machine instruction (stepping into calls). It is valid only in native mode.

Syntax

stepi: Single step one machine instruction (step into calls).
stepi n: Single step n machine instructions (step into calls).
stepi -sig signal: Step and deliver the given signal.
stepi ...lwp_id: Step the given LWP.
stepi ...thread_id: Step the LWP on which the given thread is active.

where:

n is the number of instructions to step.

signal is the name of a signal.

lwp_id is an LWP ID.

thread_id is a thread ID.

`stop` Command

The stop command sets a source-level breakpoint.

Syntax

The stop command has the following general syntax:

stop event_specification [modifier]

When the specified event occurs, the process is stopped.

Native Mode Syntax

The following specific syntaxes are some of the more important syntaxes that are valid in native mode. For additional events, see Setting Event Specifications.

stop [ -update ]: Stop execution now. Only valid within the body of a whencommand.
stop -noupdate: Stop execution now but do not update the Sun Studio IDE Debugger windows.
stop access mode address_expression [,byte_size_expression ]: Stop execution when the memory specified by address_expression has been accessed. See also Stopping Execution When an Address Is Accessed.
stop at line-number: Stop execution at line_number. See also Setting a stop Breakpoint at a Line of Source Code.
stop change variable: Stop execution when the value of variable has changed.
stop cond condition_expression: Stop execution when the condition denoted by condition_expression evaluates to true.
stop in function: Stop execution when function is called. See also Setting a stop Breakpoint in a Function.
stop inclass class_name [ -recurse | -norecurse ]: C++ only: Set breakpoints on all member functions of a class, struct, union, or template class. -norecurse is the default. If -recurse is specified, the base classes are included. See also Setting Breakpoints in Member Functions of the Same Class.
stop infunction name: C++ only: Set breakpoints on all non-member functions name.
stop inmember name: C++ only: set breakpoints on all member functions name. See Setting Breakpoints in Member Functions of Different Classes.
stop inobject object_expression [ -recurse | -norecurse ]: C++ only: set breakpoint on entry into any non-static method of the class and all its base classes when called from the object object_expression. -recurse is the default. If- norecurse is specified, the base classes are not included. See also Setting Breakpoints in Objects.

line_number is the number of a source code line.

function is the name of a function.

class_name is the name of a C++ class, struct, union, or template class.

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 the following:

a: Stops the process after the access (default).
b: Stops the process before the access.

name is the name of a C++ function.

object_expression identifies a C++ object.

variable is the name of a variable.

The following modifiers are valid in native mode.

-if condition_expression: The specified event occurs only when condition_expression evaluates to true.
-in function: Execution stops only if the specified event occurs during the extent of function.
-count number: Starting at 0, each time the event occurs, the counter is incremented. When number is reached, execution stops and the counter is reset to 0.
-count infinity: Starting at 0, each time the event occurs, the counter is incremented. Execution is not stopped.
-temp: Create a temporary breakpoint that is deleted when the event occurs.
-disable: Create the breakpoint in a disabled state.
-instr: Do instruction level variation. For example, step becomes instruction level stepping, and at takes a text address for an argument instead of a line number.
-perm: Make this event permanent across debug. Certain events (like breakpoints) are not appropriate to be made permanent. delete all will not delete permanent handlers, use delete hid.
-hidden: Hide the event from the status command. Some import modules may choose to use this. Use status -h to see them.
-lwp lwp_id: Execution stops only if the specified event occurs in the given LWP.
-thread thread_id: Execution stops only if the specified event occurs in the given thread.

Java Mode Syntax

The following specific syntaxes are valid in Java mode.

stop access mode class_name.field)name: Stop execution when the memory specified by class_name.field_name has been accessed.
stop at line_number: Stop execution at line_number.
stop at file_name:line_number: Stop execution at line_number in file_name.
stop change class_name.field_name: Stop execution when the value of field_name in class_name has changed.
stop classload: Stop execution when any class is loaded.
stop classload class_name: Stop execution when class_name is loaded.
stop classunload: Stop execution when any class is unloaded.
stop classunload class_name: Stop execution when class_name is unloaded.
stop cond condition_expression: Stop execution when the condition denoted by condition_expression evaluates to true.
stop in class_name.method_name: Stop execution when class_name.method_name has been entered, and the first line is about to be executed. If no parameters are specified and the method is overloaded, a list of methods is displayed.
stop in class_name.method_name([parameters]): Stop execution when class_name.method_name has been entered, and the first line is about to be executed.
stop inmethod class_name.method_name: Set breakpoints on all non-member methods class_name.method_name.
stop inmethod class_name.method_name ([parameters]): Set breakpoints on all non-member methods class_name.method_name.
stop throw: Stop execution when a Java exception has been thrown.
stop throw type: Stop execution when a Java exception of type has been thrown.

where:

condition_expression can be any expression, but it must evaluate to an integral type.

field_name is the name of a field in the class.

file_name is the name of a file.

line_number is the number of a source code line.

method_name is the name of a Java method.

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.

mode can also contain the following:

b: Stops the process before the access.

The program counter will point at the offending instruction.

parameters are the method’s parameters.

type is a type of Java exception. -unhandled or -unexpected can be used for type.

The following modifiers are valid in Java mode:

-if condition_expression: The specified event occurs only when condition_expression evaluates to true.
-count number: Starting at 0, each time the event occurs, the counter is incremented. When number is reached, execution stops and the counter is reset to 0.
-count infinity: Starting at 0, each time the event occurs, the counter is incremented. Execution is not stopped.
-temp: Create a temporary breakpoint that is deleted when the event occurs.
-disable: Create the breakpoint in a disabled state.

See also stopi Command for setting a machine-level breakpoint.

For a list and the syntax of all events see Setting Event Specifications.

`stopi` Command

The stopi command sets a machine-level breakpoint. It is valid only in native mode.

Syntax

The stopi command has the following general syntax:

stopi event_specification [modifier]

When the specified event occurs, the process is stopped.

The following specific syntaxes are valid:

stopi at address: Stop execution at location address.
stopi in function: Stop execution when function is called.

where:

address is any expression resulting in or usable as an address.

function is the name of a function.

For a list and the syntax of all events see Setting Event Specifications.

`suppress` Command

The suppress command suppresses reporting of memory errors during runtime checking. It is valid only in native mode.

Note –

The suppress command is available only on Solaris platforms.

If the dbx rtc_auto_suppress environment variable is on, the memory error at a given location is reported only once.

Syntax

suppress: History of suppress and unsuppress commands (not including those specifying the -d and -reset options).
suppress -d: List of errors being suppressed in functions not compiled for debugging (default suppression). This list is per load object. These errors can be unsuppressed only by using the unsuppress with the -d option.
suppress -d errors: Modify the default suppressions for all load objects by further suppressing errors.
suppress -d errors in load_objects: Modify the default suppressions in the load_objects by further suppressing errors.
suppress -last: At error location suppress present error.
suppress -reset: Set the default suppression to the original value (startup time).
suppress -r id...: Remove the unsuppress events as given by the id(s), which can be obtained with unsuppress command (see unsuppress Command).
suppress -r 0 | all | -all: Remove all the unsuppress events as given by the unsuppress command (see unsuppress Command).
suppress errors: Suppress errors everywhere.
suppress errors in [ functions ] [ files ] [ load_objects ]: Suppress errors in list of functions, list of files, and list of load_objects.
suppress errors at line: Suppress errors at line.
suppress errors at "file":line: Suppress errors at line in file.
suppress errors addr address: Suppress errors at location address.

where:

address is a memory address.

errors are blank separated and can be any combination of:

all: All errors
aib: Possible memory leak - address in block
air: Possible memory leak - address in register
baf: Bad free
duf: Duplicate free
mel: Memory leak
maf: Misaligned free
mar: Misaligned read
maw: misaligned write
oom: Out of memory
rua: Read from unallocated memory
rui: Read from uninitialized memory
wro: Write to read-only memory
wua: Write to unallocated memory
biu: Block in use (allocated memory). Though not an error, you can use biu just like errors in the suppress commands.

file is the name of a file.

files is the names of one or more files.

functions is one or more function names.

line is the number of a source code line.

load_objects is one or more load object names.

See Suppressing Errors for more information on suppressing errors.

See the unsuppress Command for information on unsuppressing errors.

`sync` Command

The sync command shows information about a given synchronization object. It is valid only in native mode.

Note –

The sync command is available only on Solaris platforms.

Syntax

sync -info address: Show information about the synchronization object at address.

where:

address is the address of the synchronization object.

`syncs` Command

The syncs command lists all synchronization objects (locks). It is valid only in native mode.

Note –

The syncs command is available only on Solaris platforms.

Syntax

syncs

`thread` Command

The thread command lists or changes the current thread.

Native Mode Syntax

thread: Display current thread.
thread thread_id: Switch to thread thread_id.

In the following variations, a missing thread_id implies the current thread.

thread -info [thread_id]: Print everything known about the given thread.
thread -hide [thread_id]: Hide the given (or current) thread. It will not show up in the generic threads listing.
thread -unhhide [thread_id]: Unhide the given (or current) thread.
thread -unhide all: Unhide all threads.
thread -suspend thread_id: Keep the given thread from ever running. A suspended thread shows up with an “S” in the threads list.
thread -resume thread_id: Undo the effect of -suspend.
thread -blocks [thread_id]: List all locks held by the given thread blocking other threads.
thread -blockedby [thread_id]: Show which synchronization object the given thread is blocked by, if any.

where:

thread_id is a thread ID.

Java Mode Syntax

thread: Display current thread.
thread thread_id: Switch to thread thread_id.

In the following variations, a missing thread_id implies the current thread.

thread -info [thread_id]: Print everything known about the given thread.
thread -hide [thread_id]: Hide the given (or current) thread. It will not show up in the generic threads listing.
thread -unhide [thread_id]: Unhide the given (or current) thread.
thread -unhide all: Unhide all threads.
thread -suspend thread_id: Keep the given thread from ever running. A suspended thread shows up with an “S” in the threads list.
thread -resume thread_id: Undo the effect of -suspend.
thread -blocks [thread_id]: Lists the Java monitor owned by thread_id.
thread -blockedby [thread_id]: Lists the Java monitor on which thread_id is blocked.

where:

thread_id is a dbx-style thread ID of the form t@number or the Java thread name specified for the thread.

`threads` Command

The threads command lists all threads.

Native Mode Syntax

threads: Print the list of all known threads.
threads -all: Print threads normally not printed (zombies).
threads -mode all|filter: Controls whether all threads are printed or threads are filtered. The default is to filter threads. When filtering is on, threads that have been hidden by the thread -hide command are not listed.
threads -mode auto|manual: Under the dbx Debugger, enables automatic updating of the thread listing.
threads -mode: Echo the current modes.

Each line of information is composed of the following:

An * (asterisk) indicating that an event requiring user attention has occurred in this thread. Usually this is a breakpoint.

An ”o’ instead of an asterisk indicates that a dbx internal event has occurred.
An > (arrow) denoting the current thread.
t@num, the thread id, referring to a particular thread. The number is the thread_t value passed back by thr_create.
b l@num meaning the thread is bound (currently assigned to the designated LWP), or a l@num meaning the thread is active (currently scheduled to run).
The “Start function” of the thread as passed to thr_create. A ?() means that the start function is not known.
The thread state, which is one of the following:
- monitor
- running
- sleeping
- wait
- unknown
- zombie
The function that the thread is currently executing.

Java Mode Syntax

threads: Print the list of all known threads.
threads -all: Print threads normally not printed (zombies).
threads -mode all|filter: Controls whether all threads are printed or threads are filtered. The default is to filter threads.
threads -mode auto|manual: Under the dbx Debugger, enables automatic updating of the thread listing.
threads -mode: Echo the current modes.

Each line of information in the listing is composed of the following:

An > (arrow) denoting the current thread
t@number, a dbx-style thread ID
The thread state, which is one of the following:
- monitor
- running
- sleeping
- wait
- unknown
- zombie
The thread name in single quotation marks
A number indicating the thread priority

`trace` Command

The trace command shows executed source lines, function calls, or variable changes.

The speed of a trace is set using the dbx trace_speed environment variable.

If dbx is in Java mode and you want to set a trace breakpoint in native code, switch to Native mode using the joff command (see joff Command) or prefix the tracecommand with native(see native Command).

If dbx is in JNI mode and you want to set a trace breakpoint in Java code, prefix the trace command with java (see java Command).

Syntax

The trace command has the following general syntax:

trace event_specification [modifier]

When the specified event occurs, a trace is printed.

Native Mode Syntax

The following specific syntaxes are valid in native mode:

trace -file file_name: Direct all trace output to the given file_name. To revert trace output to standard output use - for file_name. trace output is always appended to file_name. It is flushed whenever dbx prompts and when the application has exited. The file_name is always re-opened on a new run or resumption after an attach.
trace step: Trace each source line, function call, and return.
trace next -in function: Trace each source line while in the given function.
trace at line_number: Trace given source line..
trace in function: Trace calls to and returns from the given function.
trace inmember function: Trace calls to any member function named function.
trace infunction function: Trace when any function named function is called.
trace inclass class: Trace calls to any member function of class.
trace change variable: Trace changes to the variable.

where:

file_name is the name of the file to which you want trace output sent.

function is the name of a function.

line_number is the number of a source code line.

class is the name of a class.

variable is the name of a variable.

The following modifiers are valid in native mode.

-if condition_expression: The specified event occurs only when condition_expression evaluates to true.
-in function: Execution stops only if the specified event occurs in function.
-count number: Starting at 0, each time the event occurs, the counter is incremented. When number is reached, execution stops and the counter is reset to 0.
-count infinity: Starting at 0, each time the event occurs, the counter is incremented. Execution is not stopped.
-temp: Create a temporary breakpoint that is deleted when the event occurs.
-disable: Create the breakpoint in a disabled state.
-instr: Do instruction level variation. For example, step becomes instruction level stepping, and at takes a text address for an argument instead of a line number.
-perm: Make this event permanent across debug. Certain events (like breakpoints) are not appropriate to be made permanent. delete all will not delete permanent handlers, use delete hid.
-hidden: Hide the event from the status command. Some import modules may choose to use this. Use status -h to see them.
-lwp lwpid: Execution stops only if the specified event occurs in the given LWP.
-thread thread_id: Execution stops only if the specified event occurs in the given thread.

Java Mode Syntax

The following specific syntaxes are valid in Java mode.

trace -file file_name: Direct all trace output to the given file_name. To revert trace output to standard output use - for file_nametrace output is always appended to file_name. It is flushed whenever dbxprompts and when the application has exited. The file_nameis always re-opened on a new run or resumption after an attach.
trace at line_number: Trace line_number.
trace at file_name.line_number: Trace give source file_name.line_number.
trace in class_name.method_name: Trace calls to and returns from class_name. method_name.
trace in class_name.method_name([parameters]).: Trace calls to and returns from class_name.method_name([parameters]).
trace inmethod class_name.method_name: Trace when any method named class_name.method_name is called.
trace inmethod class_name.method_name[(parameters)]: Trace when any method named class_name.method_name [(parameters)] is called.

where:

class_name is the name of a Java class, using either the package path (using period (.) as a qualifier, for example, test1.extra.T1.Inner) or the full path name (preceded by a pound sign (#) and using slash (/) and dollar sign ($) as qualifiers, for example, #test1/extra/T1$Inner). Enclose class_name in quotation marks if you use the $ qualifier.

file_name is the name of a file.

line_number is the number of a source code line.

method_name is the name of a Java method.

parameters are the method’s parameters

The following modifiers are valid in Java mode.

-if condition_expression: The specified event occurs and the trace is printed only when condition_expression evaluates to true.
-count number: Starting at 0, each time the event occurs, the counter is incremented. When number is reached, the trace is printed and the counter is reset to 0.
-count infinity: Starting at 0, each time the event occurs, the counter is incremented. Execution is not stopped.
-temp: Create a temporary breakpoint that is deleted when the event occurs and the trace is printed. If -temp is used with -count, the breakpoint is deleted only when the counter is reset to 0.
-disable: Create the breakpoint in a disabled state.

For a list and the syntax of all events see Setting Event Specifications.

`tracei` Command

The tracei command shows machine instructions, function calls, or variable changes. It is valid only in native mode.

tracei is really a shorthand for trace event-specification -instr where the- instr modifier causes tracing to happen at instruction granularity instead of source line granularity. When the event occurs, the printed information is in disassembly format instead of source line format.

Syntax

tracei step: Trace each machine instruction.
tracei next -in function: Trace each instruction while in the given function.
tracei at address_expression: Trace the instruction at address.
tracei in function: Trace calls to and returns from the given function.
tracei inmember function: Trace calls to any member function named function.
tracei infunction function: Trace when any function named function is called.
tracei inclass class: Trace calls to any member function of class.
tracei change variable: Trace changes to the variable.

where:

filename is the name of the file to which you want trace output sent.

function is the name of a function.

line is the number of a source code line.

class is the name of a class.

variable is the name of a variable.

See trace Command for more information.

`uncheck` Command

The uncheck command disables checking of memory access, leaks, or usage. It is valid only in native mode.

Note –

The uncheck command is available only on Solaris platforms.

Syntax

uncheck: Print current status of checking.
uncheck -access: Turn off access checking.
uncheck -leaks: Turn off leak checking.
uncheck -memuse: Turn off memory use checking (leak checking is turned off as well).
uncheck -all: Equivalent to uncheck -access; uncheck -memuse.
uncheck [functions] [files] [loadobjects]: Equivalent to suppress all in functions files loadobjects.

where:

functions is one or more function names.

files is one or more file names.

loadobjects is one or more loadobject names

See check Command for information to turn on checking.

See suppress Command for information on suppressing of errors.

See Capabilities of Runtime Checking for an introduction to runtime checking.

`undisplay` Command

The undisplay command undoes display commands.

Native Mode Syntax

undisplay expression, ...: Undo a display expression command.
undisplay n, ...: Undo all the display commands numbered n, ...
undisplay 0: Undo all display commands.

where:

expression is a valid expression.

Java Mode Syntax

undisplay expression, ... | identifier, ...: Undo a display expression, ... or display identifier, ... command.
undisplay n, ...: Undo the display commands numbered n, ...
undisplay 0 do all display commands.: Undo all display commands.

where:

expression is a valid Java expression.

field_name is the name of a field in the class.

identifier is a local variable or parameter, including this, the current class instance variable (object_name.field_name) or a class (static) variable (class_name.field_name).

`unhide` Command

The unhide command undoes hide commands. It is valid only in native mode.

Syntax

unhide 0: Delete all stack frame filters.
unhide regular_expression: Delete stack frame filter regular_expression.
unhide number: Delete stack frame filter number number.

where:

regular_expression is a regular expression.

number is the number of a stack frame filter.

The hide command (see Catch Floating Point Exceptions) lists the filters with numbers.

`unintercept` Command

The unintercept command undoes intercept commands (C++ only). It is valid only in native mode.

Syntax

unintercept intercepted_typename [, intercepted_typename ... ]: Delete throws of type intercepted_typename from the intercept list.
unintercept -a[ll]: Delete all throws of all types from intercept list.
unintercept -x excluded_typename [, excluded_typename ... ]: Delete excluded_typename from excluded list.
unintercept -x -a[ll]: Delete all throws of all types from the excluded list.
unintercept: List intercepted types.

where:

included_typename and excluded_typename are exception type specifications such as List <int> or unsigned short.

`unsuppress` Command

The unsuppress command undoes suppress commands. It is valid only in native mode.

Note –

The unsuppress command is available only on Solaris platforms.

Syntax

unsuppress: History of suppressandunsuppress commands (not those specifying the -d and -reset options).
unsuppress -d: List of errors being unsuppressed in functions that are not compiled for debugging. This list is per loadobject. Any other errors can be suppressed only by using the suppress command (see suppress Command) with the -d option.
unsuppress -d errors: Modify the default suppressions for all loadobjects by further unsuppressing errors.
unsuppress -d errors in loadobjects: Modify the default suppressions in the loadobjects by further unsuppressing errors.
unsuppress -last: At error location unsuppress present error.
unsuppress -reset: Set the default suppression mask to the original value (startup time).
unsuppress errors: Unsuppress errors everywhere.
unsuppress errors in [functions] [files] [loadobjects]: Suppress errors in list of functions, list of files, and list of loadobjects.
unsuppress errors at line: Unsuppress errors at line.
unsuppress errors at "file"line: Unsuppress errors at line in file.
unsuppress errors addr address: Unsuppress errors at location address.

`unwatch` Command

The unwatch command undoes a watch command. It is valid only in native mode.

Syntax

unwatch expression, ...: Undo a watch expression command.
unwatch n, ...: Undo the watch commands numbered n.
unwatch 0: Undo allwatch commands.

where:

expression is a valid expression.

`up` Command

The up command moves up the call stack (toward main). It has identical syntax and identical functionality in native mode and in Java mode.

Syntax

up: Move up the call stack one level.
up number: Move up the call stack number levels.
up -h [number]: Move up the call stack, but don’t skip hidden frames.

where:

number is a number of call stack levels.

`use` Command

The use command lists or changes the directory search path. It is valid only in native mode.

This command is an anachronism and usage of this command is mapped to the following pathmap commands:

use is equivalent to pathmap -s

use directory is equivalent to pathmap directory.

`watch` Command

The watch command evaluates and prints expressions at every stopping point in the scope current at that stop point. Because the expression is not parsed at entry time, the correctness of the expression cannot be immediately verified. The watch command is valid only in native mode.

Syntax

watch: Print the list of expressions being displayed.
watch expression, ...: Watch the value of expressions expression, ... at every stopping point.
watch [-r|+r|-d|+d|-p|+p|-L|-fformat|-Fformat|--] expression, ...: See print Command for the meaning of these flags.

where:

expression is a valid expression.

format is the output format you want used to print the expression. For information on valid formats, see print Command.

`whatis` Command

In native mode, the whatis command prints the type of expression or declaration of type. In Java mode, the whatis command prints the declaration of an identifier. If the identifier is a class, it prints method information for the class, including all inherited methods.

Native Mode Syntax

what is [-n] [-r] name: Print the declaration of the non-type name.
whatis -t [-r] type: Print the declaration of the type type.
whatis -e [-r] [-d] expression: Print the type of the expression expression.

where:

name is the name of a non-type.

type is the name of a type.

expression is a valid expression.

-d shows dynamic type instead of static type (C++ only).

-e displays the type of an expression.

-n displays the declaration of a non-type. It is not necessary to specify -n; this is the default if you type the whatis command with no options.

-r prints information about base classes (C++ only).

-t displays the declaration of a type.

The whatis command, when run on a C++ class or structure, provides you with a list of all the defined member functions (undefined member functions are not listed), the static data members, the class friends, and the data members that are defined explicitly within that class.

Specifying the -r (recursive) option adds information from the inherited classes.

The-d flag, when used with the -e flag, uses the dynamic type of the expression.

For C++, template-related identifiers are displayed as follows:

All template definitions are listed with whatis -t.
Function template instantiations are listed with whatis.
Class template instantiations are listed with whatis -t.

Java Mode Syntax

whatis identifier: Print the declaration of identifier.

where:

identifier is a class, a method in the current class, a local variable in the current frame, or a field in the current class.

`when` Command

The when command executes commands when a specified event occurs.

If dbx is in Java mode and you want to set a when breakpoint in native code, switch to Native mode using the joff command (see joff Command) or prefix the when command with native (see native Command).

If dbx is in JNI mode and you want to set a when breakpoint in Java code, prefix the when command with java (see java Command).

Syntax

The when command has the following general syntax:

when event_specification [modifier]{command; ... }

When the specified event occurs, the commands are executed. The following commands are forbidden in the when command:

attach
debug
next
replay
rerun
restore
run
save
step

A cont command with no options is ignored.

Native Mode Syntax

The following specific syntaxes are valid in native mode:

when at line_number { command; }: Execute command(s) when line_number is reached.
when in procedure { command; }: Execute command(s) when procedure is called.

where:

line_number is the number of a source code line.

command is the name of a command.

procedure is the name of a procedure.

Java Mode Syntax

The following specific syntaxes are valid in Java mode.

when at line_number: Execute command(s) when source line_number is reached.
when at file_name.line_number: Execute command(s) when file_name.line_number is reached.
when in class_name.method_name: Execute command(s) when class_name.method_name is called.
when in class_name.method_name([parameters]): Execute command(s) when class_name.method_name([parameters]) is called.

file_name is the name of a file.

line_number is the number of a source code line.

method_name is the name of a Java method.

parameters are the method’s parameters.

For a list and the syntax of all events, see Setting Event Specifications.

See wheni Command for executing commands on given low-level event.

`wheni` Command

The wheni command executes commands when a given low-level event occurs. It is valid only in native mode.

The wheni command has the following general syntax:

Syntax

wheniwheni event_specification [modifier]{command... ; }

When the specified event occurs, the commands are executed.

The following specific syntax is valid:

wheni at address_expression { command; }: Execute command(s) when address_expression is reached.

where:

address is any expression resulting in or usable as an address.

command is the name of a command.

For a list and the syntax of all events see Setting Event Specifications.

`where` Command

The where command prints the call stack.

Native Mode Syntax

where: Print a procedure traceback.
where number: Print the number top frames in the traceback.
where -f number: Start traceback from frame number.
where -fp address_expression: Print traceback as if fp register hadaddress_expression value.
where -h: Include hidden frames.
where -l: Include library name with function name.
where -q: Quick traceback (only function names).
where -v: Verbose traceback (include function args and line info).

where:

number is a number of call stack frames.

Any of the above forms may be combined with a thread or LWP ID to obtain the traceback for the specified entity.

The -fp option is useful when the fp (frame pointer) register is corrupted, in which event dbx cannot reconstruct call stack properly. This option provides a shortcut for testing a value for being the correct fp register value. Once you have identified the correct value has been identified, you can set it with an assign command or lwp command.

Java Mode Syntax

where [thread_id]: Print a method traceback.
where [thread_id] number: Print the number top frames in the traceback.
where -f [thread_id] number: Start traceback from frame number.
where -q [thread_id]: Quick trace back (only method names).
where -v [thread_id]: Verbose traceback (include method arguments and line information).

where:

number is a number of call stack frames.

thread_id is a dbx-style thread ID or the Java thread name specified for the thread.

`whereami` Command

The whereamicommand displays the current source line. It is valid only in native mode.

Syntax

whereami: Display the source line corresponding to the current location (top of the stack), and the source line corresponding to the current frame, if different.
whereami -instr: Same as above, except that the current disassembled instruction is printed instead of the source line.

`whereis` Command

The whereis command prints all uses of a given name, or symbolic name of an address. It is valid only in native mode.

Syntax

whereis name: Print all declarations of name.
whereis -a address_expression: Print location of an address_expression.

where:

name is the name of a loadable object that is in scope; for example, a variable, function, class template, or function template.

address is any expression resulting in or usable as an address.

`which` Command

The which command prints the full qualification of a given name. It is valid only in native mode.

Syntax

which [-n] name: Print full qualification of name.
which -t type: Print full qualification of type.

where:

name is the name of something that is in scope; for example, a variable, function, class template, or function template.

type is the name of a type.

-n displays the full qualification of a non-type. It is not necessary to specify -n; this is the default if you type the which command with no options.

-t displays the full qualification of a type.

`whocatches` Command

The whocatches command tells where a C++ exception would be caught. It is valid only in native mode.

Syntax

whocatches type

Tell where (if at all) an exception of type type would be caught if thrown at the current point of execution. Assume the next statement to be executed is a throw x where x is of type type, and display the line number, function name, and frame number of the catch clause that would catch it.

Will return "type is unhandled" if the catch point is in the same function that is doing the throw.

where:

type is the type of an exception.

Previous: Appendix B Event Management

Appendix C Command Reference

assign Command

Native Mode Syntax

Java Mode Syntax

attach Command

Syntax

To Attach to a Running Java Process

bsearch Command

Syntax

call Command

Native Mode Syntax

Java Mode Syntax

cancel Command

Syntax

catch Command

Syntax

check Command

Syntax

clear Command

Syntax

collector Command

Syntax

collector archive Command

Syntax

collector dbxsample Command

Syntax

collector disable Command

Syntax

collector enable Command

Syntax

collector heaptrace Command

Syntax

collector hw_profile Command

Syntax

collector limit Command

Syntax

collector mpitrace Command

Syntax

collector pause Command

Syntax

collector profile Command

Syntax

collector resume Command

Syntax

collector sample Command

Syntax

collector show Command

Syntax

collector status Command

Syntax

collector store Command

Syntax

collector synctrace Command

Syntax

collector tha Command

Syntax

collector version Command

Syntax

cont Command

Syntax

dalias Command

Syntax

dbx Command

Native Mode Syntax

Java Mode Syntax

Options

dbxenv Command

Syntax

debug Command

Native Mode Syntax

Java Mode Syntax

Options

delete Command

Syntax

detach Command

Native Mode Syntax

Java Mode Syntax

dis Command

Syntax

Options

`assign` Command

`attach` Command

`bsearch` Command

`call` Command

`cancel` Command

`catch` Command

`check` Command

`clear` Command

`collector` Command

`collector archive` Command

`collector dbxsample` Command

`collector disable` Command

`collector enable` Command

`collector heaptrace` Command

`collector hw_profile` Command

`collector limit` Command

`collector mpitrace` Command

`collector pause` Command

`collector profile` Command

`collector resume` Command

`collector sample` Command

`collector show` Command

`collector status` Command

`collector store` Command

`collector synctrace` Command

`collector tha` Command

`collector version` Command

`cont` Command

`dalias` Command

`dbx` Command

`dbxenv` Command

`debug` Command

`delete` Command

`detach` Command

`dis` Command

`display` Command

`down` Command

`dump` Command

`edit` Command

`examine` Command

`exception` Command

`exists` Command

`file` Command

`files` Command

`fix` Command

`fixed` Command

`fortran_modules` Command

`frame` Command

`func` Command

`funcs` Command

`gdb` Command

`handler` Command

`hide` Command

`ignore` Command

`import` Command

`intercept` Command

`java` Command

`jclasses` Command

`joff` Command

`jon` Command

`jpkgs` Command

`kill` Command

`language` Command

`line` Command

`list` Command

`listi` Command

`loadobject` Command

`loadobject -dumpelf` Command