DBX(1) — USER COMMANDS
NAME
dbx − source-level debugger
SYNOPSIS
dbx [ −c dbx_cmd ] [ −e ] [ −i ] [ −Idir ] [ −kbd ] [ −q ] [ −r ] [ −s startup ]
[ −sr startup ] [ execfile [ corefile | process-id ] ] [ − pid ]
DESCRIPTION
dbx is a utility for source-level debugging and execution of programs written in C++, ANSI C, FORTRAN , and Pascal. dbx accepts the same commands as debugger(1), but uses a standard terminal (tty) interface. For a full overview of dbx and Debugger features see the Debugging a Program user guide.
execfile is an executable file, produced by a compiler, with the −g option to include a symbol table. This symbol table contains the names of all the source files used to create the execfile (all of which may be browsed), as well as wide range of debugging information. Debugging support is limited for any parts of a program not compiled with the −g option.
Initially, symbol table information is stored piecemeal in each of the object files the compiler creates. (If compilation does not create an object file, all debugging information is stored in the execfile . ) Distributing the debugging information in the object files allows dbx to read and load debugging information as it is needed. This feature is called Auto-Read. If you need to move object files from their original location, make sure that dbx knows where to find them. (See the use command.) If it is not feasible to keep program .o files around, you can disable Auto-Read by compiling using the −xs option. -xs instructs the compiler to have the linker place all debugging information in the program executable.
If, when starting dbx , no execfile is specified, use the debug command to specify a program to be debugged. If you know a process ID but not the execfile , you can use the − pid (dash, space, pid ) option to attach the process to dbx .
If there is a file named core in the current directory, or a corefile argument is specified, you can use dbx to examine the state of the program when the core file was produced.
dbx executes commands in the .dbxinit file immediately before it reads the symbol table. dbx first searches for .dbxinit in the current directory. If .dbxinit does not exist in the current directory, dbx looks in the user’s home directory.
OPTIONS
−c dbx_cmd Execute dbx_cmd after initialization. For more than one dbx_cmd , use double quotes around the string of commands, separating each with a semi-colon.
−e Echo all input commands on standand out.
−i Force dbx to act as though the standard input were a terminal or terminal emulator.
−I dir Add dir to the list of directories in which to search for a source file. dbx normally searches the current directory and the directory where execfile is located. The directory search path can be reset with the use command.
−kbd Debug a program that sets the keyboard into up-down translation mode. This flag is necessary if a program uses up-down decoding.
−q Silence echoing of two loading messages: "Reading symbol table for..." and "Attached to ...". (This option is intended mainly for use by the auto-traceback facility.)
−r Execute execfile immediately. Parameters follow the object file name (redirection is handled properly). If the program terminates successfully, dbx exits. Otherwise, dbx reports the reason for termination and waits for a response. dbx reads from the terminal (/dev/tty) when −r is specified and standard input is a file or pipe.
−s startup Read initialization commands from the file named startup instead of from .dbxinit.
−sr startup Read initialization commands from the temporary file named startup, instead of from .dbxinit and then remove startup.
− pid (dash, space, pid ) For a program that is currently running, attach it to dbx using its process ID without supplying dbx its program name (executable ). Without its name, dbx will be able to issue commands like run with implicit arguments. This is also the only mechanism to "attach" to a running process.
USAGE
Refer to Debugger line commands in the Debugging a Program manual.
The basic commands to know are: run, to run the program being debugged; where, to obtain a stack trace with line numbers; print, to display variables; and stop, to set breakpoints.
Expressions
dbx expressions are combinations of variables, constants, procedure calls, and operators. Variables are either variables in the program being debugged or special dbx variables whose names begin with $. Hexadecimal constants must be preceded by a ‘0x’ and octal constants by a ‘0’. Character constants must be enclosed in single quotes. Expressions cannot involve strings, structures, or arrays, although elements of structures or arrays may be used.
Operators
+ − ∗ / div % Add, subtract, multiply, divide, integer division, and remainder.
dbx has two division operators. ‘/’ always yields a floating-point result and div always yields an integral result.
<< >> & | ~ Left-shift, right-shift, bitwise AND, bitwise OR, and bitwise complement.
& ∗ Address of operator and contents of operator.
< > <= >= == != !
Less than, greater than, less than or equal to, greater than or equal to, equal, not equal, and negation.
&& || Logical AND and logical OR
sizeof (cast) Size of variable or type and type cast.
. −> Field reference and pointed-to-field reference (however, dot works for both in dbx).
:: C++ scope resolution operator (two colons).
Precedence and associativity of operators are the same as for ANSI C; parentheses can be used for grouping.
Scope Rules
dbx resolves scope conflicts based on the values of the current file and function. These values are updated as files and functions are entered and exited during execution. You can also change them explicitly by using the file and func commands. When the current function is changed, the current file is updated along with it, but not vice versa.
C++ Symbolic Names
cfront mangles the original source names of locals, member functions, functions, and so on. dbx will demangle all those mangled names into C++ symbolic format in dbx output.
Commands to List Active and Post-Mortem Procedures
where [n]
List all, or the top n, active functions on the stack.
up [n]
Move up (towards “main”) the call stack n levels. If omitted, n is taken to be one.
down [n]
Move down the call stack n levels. If omitted, n is taken to be one.
Commands to Name, Display, and Set Data
Variables from another function or procedure with the same name as one in the current block must be qualified as follows:
[` sourcefile `] function` variable
[` sourcefile `] variable
For Pascal variables there may be more than one function or procedure name, each separated by a backquote.
print expression [ , expression ] ...
Print the value of each expression, which may involve function calls. Program execution halts when a breakpoint is reached, and dbx resumes.
display [ expression [ , expression ] ... ]
Print a list of the expressions currently being displayed, or display the value of each expression whenever execution stops.
undisplay [ expression [ , expression ] ... ]
Stop displaying the value of each expression whenever execution stops. If expression is a constant, it refers to a display-number as shown by the display command with no arguments.
whatis identifier
whatis
[ −r ] type
Print the declaration of the given identifier, type or class. types are useful for printing all the members of a structure, union, or enumerated type. If type is a C++ object, whatis prints the class declaration. −r prints recursively the declarations for that class and its inherited base classes. ( −v is obsolete, maintained for backward compatibility in this release.)
which identifier
Print the fully-qualified name of identifier as picked by the default scope rules.
whereis identifier
Print the fully qualified name of all symbols matching identifier.
assign variable = expression
set variable = expression
Assign the value of expression to variable. There is no type conversion for operands of differing type.
dump [ function ]
Display the names and values of local variables and parameters in the current or specified function.
Commands to Set Breakpoints
stop at sourceline [ if condition ]
stop in function [ if condition ]
stop inmember member_function [ if condition ]
stop inclass class [ if condition ]
stop infunction function [ if condition ]
stop variable [ if condition ]
stop if condition
Stop execution if: sourceline is reached, function is called, member_function of any C++ class is called, each member function of a C++ class is called, function (top-level; i.e., non-member) in a C++ module is called, variable is changed, or condition becomes true. Note, function , in stop in function , may also be a C++ member function; in this case, specify class::member_function ; program will stop at that specific member function only.
when in function { command ; [ command ; ] ... }
when inmember member_function { command ; [ command ; ] ... }
when inclass class { command ; [ command ; ] ... }
when infunction function { command ; [ command ; ] ... }
when at sourceline { command ; [ command ; ] ... }
when condition { command ; [ command ; ] ... }
Execute the dbx command(s) when function is called, member_function of any C++ class is called, each member function of a C++ class is called, function (top-level; i.e., non-member) in a C++ module is called, sourceline is reached, or condition is true.
status [ > filename ]
Display active trace, stop and when commands, and associated command numbers.
delete all
delete cmd-no [[ , ] cmd-no ] ...
Remove all traces, stops and whens when all is specified, or those corresponding to each dbx cmd-no (as displayed by status).
clear [ sourceline]
Clear all breakpoints at the current stopping point if no argument is given, or at sourceline.
catch [ signal [[ , ] signal ] ... ]
Display all signals currently being caught if no argument is given, or catch signal before it is sent to the program being debugged. A signal can be specified either by name (with the SIG prefix optional, as with kill(1)) or number. Initially all signals are caught except SIGHUP, SIGEMT, SIGFPE, SIGKILL, SIGALRM, SIGTSTP, SIGCONT, SIGCHLD, and SIGWINCH.
ignore [ signal [[ , ] signal ] ... ]
Display all signals currently being ignored, or stop catching signal, which may be specified by name or number as with catch.
Commands to Run and Trace Programs
^C Interrupt. Stop the program being debugged and return to dbx.
run [ args ] [ < infile ] [ > outfile | >> outfile ]
Start executing execfile. If no arguments are specified, dbx uses the argument list from the previous run command.
args Pass args as command-line arguments to the program.
<|>|>> Redirect input or output, or append output to a file.
rerun [ args ] [ < infile ] [ > outfile | >> outfile ]
Like the run command, except that when args are omitted, no args are passed to the program.
cont [ at sourceline ] [ sig signal ]
Continue execution from where it stopped.
at sourceline Start from sourceline
sig signal Continue as if signal had occurred. signal may be a signal number or name specified by the catch command.
trace [ in function ] [ if condition ]
trace sourceline [ if condition ]
trace function [ if condition ]
trace inmember member_function [ if condition ]
trace inclass class [ if condition ]
trace infunction function [ if condition ]
trace expression at sourceline [ if condition ]
trace variable [ in function ] [ if condition ]
Display tracing information. If no argument is specified, each tracing line is displayed before execution. Tracing is turned off when the function or procedure is exited.
in function Display tracing information only while executing the function or procedure function.
if condition Display tracing information only if condition is true.
sourceline Display the line immediately prior to executing it. Source line-numbers from another file are written as filename:n.
function Print name of function that called function ; its line number, parameters passed in, and return value.
inmember member_function
Print name of the function that called member_function of any class; its line number, parameters passed in, and return value.
inclass class Print name of the function that called any member_funtion in class ; its line number, parameters passed in, and its return value.
infunction function
Print name of the function that called any top level function in a C++ program; its line number, parameters passed in, and its return value.
expression at sourceline
Display the value of expression whenever sourceline is reached.
variable Display the name and value whenever variable changes.
step [n]
step up
Execute the next n source lines. If omitted, n is taken to be 1. Step into functions called in the next line. step up steps the program "up and out" of the current function, returning it to the next line following the line that called the current function.
next [n] Execute the next n source lines. If omitted, n is taken to be 1. next steps past functions.
call function(parameters)
Execute the named function. Arguments are passed according to the rules for the source-language of function.
save [-number] [filename]
Save the commands used in the latest debugging run, which consists of the dbx commands entered since the latest run, rerun, or debug command up to the save command. save also saves the state of the symbolic table at the start of the debugging run. The minus (-) number argument saves the run up to the save command minus the number of commands specified. Unless you specify a filename, save saves the commands to a hidden file for use later by the restore command.
restore [ filename ]
Companion command for save. Restores the symbolic table to its state at the start of the last saved debugging run, then re-issues the saved sequence of dbx commands. filename is the name of a specific save-file (see the save command). Restore issued without a filename, restores the most recent, hidden save-file.
replay [-number]
A save with an immediate restore: equivalent to "save - number; restore". The default is replay -1 , which means that dbx saves and immediately restores all of the comands in the current debugging run except the last one (effectively, then, an "undo" command).
Commands to Access Source Files and Directories
edit [ filename ]
edit [ procedure/function ]
Edit the current source file, or the given filename, or the file that contains function.
file [ filename ]
Print the name of the current source file or change the current source file to filename.
func [ procedure/function ]
Print the name of the current procedure/function or change to the given procedure/function. Also changes the current scope.
list [ startline [ , endline ] ]
list function
List the lines in the current source file from startline through endline . If no endline is given, list startline only. If neither startline nor endline is given, list the next 10 lines. If the name of a procedure or function is given, list from five lines above to five lines below the first line of of the procedure or function.
use [ directory ]
Set the list of directories in which to search for source files and object files.
cd [ directory ]
Change the current working directory for dbx to the value of the HOME environment variable if no argument is given, or to directory .
pwd Print the current working directory for dbx.
/reg-exp[/]
Search downward in the current file for reg-exp. The search begins with the line immediately after the current line and, if necessary, continues until the end of the file. The matching line becomes the current line.
?reg-exp [?]
Search upward in the current file for reg-exp. The search begins with the line immediately before the current line and, if necessary, continues until the top of the file. The matching line becomes the current line.
Miscellaneous Commands
sh [ command-line]
Pass the command-line to the shell for execution. The SHELL environment variable determines which shell is used.
alias new-command-name character-sequence
Respond to new-command-name as though it were character-sequence. Special characters occurring in character-sequence must be enclosed in quotation marks. Alias substitution as with the C shell (csh(1)) also occurs.
history [ number-of-commands-in-history-list ]
Displays a list of the most recently issued dbx commands. The default value is 15 commands. Use the number option to change the default. Issues a dbx command from the history list using the following substitutions:
!! Issue the last issued command.
!n Issue the command numbered n on the history list.
!-n Issue the command that is minus n commands from the most recently entered command.
!str Issue the most recently entered command from the history list that starts with the str characters.
help [ command ]
Display a synopsis of dbx commands or print a short message explaining command.
make Invoke make(1) with the name of the program as its argument. Any arguments set using dbxenv makeargs are also passed as arguments.
setenv name string
Set environment variable name to string.
source filename
Read and execute dbx commands from filename. Useful when the filename has been created by redirecting an earlier status command.
quit Exit dbx.
dbxenv
dbxenv case sensitive | insensitive
dbxenv makeargs string
dbxenv speed seconds
dbxenv stringlen num
dbx shortfname { on | off}
dbxenv autoflush { on | off}
dbxenv stepevents { off | on}
dbxenv logname filename
Display dbx attributes or set the named attribute:
case Controls whether upper- and lower-case characters are treated as different values. The default is sensitive.
makeargs Sets arguments to pass to make. The default is CC=cc −g.
speed Set the interval between execution during tracing. The default is 0.5 seconds.
stringlen Controls the maximum number of characters printed for a “char ∗” variable in a C program. The default is 512.
shortfname
Displays short name for files in standard output.
autoflush dbx automatically calls fflush() after calling a routine.
logname Specify a filename to which dbx writes the log of all commands entered in a session.
stepevents
If set (on), program will stop at previously placed breakpoints in functions encountered when executing step and next commands. Default is off : program ignores breakpoints during step and next operations.
debug [ execfile [ corefile | pid ] | − pid ]
With no arguments, print the name of the current program. With arguments: restart dbx and re-read the specified object module, saving some status information; begin debugging execfile , optionally using corefile or the current process ID (pid). The final method of attaching a process to the dbx uses the process ID only: − pid (dash, space, pid ) without informing dbx of the process’ program name. (Note that since the program name is unknown, a run command with implicit arguments will not work.)
kill Stop debugging and execution of the current program, but be ready to debug another.
detach
Detach the current program (process) from dbx. dbx will be unable to access or modify its state.
modules
With no modifier, modules lists the names of all modules that have already been read into the Debugger.
modules debug
Lists names of all modules containing debugging info, read-in or not.
modules all
Lists names of all program modules (with or without debugging info).
modules readall
Instructs dbx to read in all program modules for which there is debugging info.
modules module_name
Instructs dbx to read in debugging info for a specified module.
language [ lang ]
With no argument, prints the name of the current language. Set current language to lang where lang is c, ansic, c++, pascal, or fortran.
Machine-Level Commands
tracei [ address ] [ if condition ]
tracei [ variable ] [at address ] [ if condition ]
Trace execution of a specific machine-instruction address.
stopi [ variable ] [ if condition ]
stopi [at address ] [ if condition ]
Set a breakpoint at a machine instruction address.
stopi in function [ if condition ]
Set a breakpoint at the machine address of the first line of function. Use mainly for debugging optimized code.
stepi Single step as in step , but do a single machine instruction rather than a source line.
nexti Single step as in next, but do a single machine instruction rather than a source line.
address,address / [ mode ]
address / [count ] [ mode ]
+/ [count ] [ mode ]
Display the contents of memory starting at the first (or current) address up to the second address, or until count items have been displayed. If a + is specified, the address following the one displayed most recently is used. The mode specifies how memory is displayed; if omitted, the last specified mode is used. The initial display mode is X. The following modes are supported:
b byte in octal
c byte as a character
d word in decimal
D longword in decimal
E extended-precision real number (not supported on Sun-4)
f single precision real number
F double-precision real number
i the machine instruction
o word in octal
O longword in octal
s strings as characters terminated by a null
x word in hexadecimal
X longword in hexadecimal
An address can be specified as an item from the following list, as an expression made up of other addresses and the operators ‘+’, ‘−’, ‘∗’, and indirection (unary ‘∗’), or as an arbitrary expression enclosed in parentheses.
&name symbolic address
integer numeric address
address = [ mode ]
Display the value of the address.
Machine Registers
The machine registers for the current machine type are represented as special dbx variables. They can be used in expressions as any other dbx variable can. The registers and their variable names are:
Sun-4 Registers
$g[0-7] global registers
$o[0-7] “out” registers
$i[0-7] “in” registers
$l[0-7] “local” registers
$fp frame pointer, equivalent to register i6
$sp stack pointer, equivalent to register o6
$y Y register
$psr processor state register
$wim window invalid mask register
$tbr trap base register
$pc program counter
$npc next program counter
$f[0-31] FPU “f” registers
$fsr FPU status register
$fq FPU queue
Commands to Collect Performance Data
collector close
Close the current experiment. When the debug process is killed, detached, or exited, the experiment is automatically closed.
collector open
Open a new experiment with the current store settings and use the next highest version number. An experiment is automatically opened each time the dbx run command is issued. If the file name or directory is changed, then a new experiment is opened when the debugging process is resumed.
collector profile mode [off | pc_only | stack]
Select data to collect for profiling. Current PC (program counter) value is collected for pc_only mode. Stack backtrace and PC data is collected for stack mode.
collector profile timer <int>
Specify a regular time interval in milliseconds for collecting profiling data. The default is 10 milliseconds.
collector quit
Close down the Collector graphical user interface (GUI). Close current experiment and turn off the Collector.
collector sample mode [off | manual | continuous]
Select sample mode. Manual sampling requires executing a take sample command from the Collector GUI. Interval sampling automatically collects samples at regular intervals specified by the interval period command. If the collection sampling mode is turned on before typing the debug command, then lib.collector.so will be loaded with the program that is being debugged.
collector sample period <int>
Set up the interval sampling period. The default is one second.
collector show {<show_item> [ <show_item> ] ... ]
In all of the following collector_show options, if all optional parameters are omitted, then the option default is all.
collector show all
Show all instrumentation options.
collector show profile [all | mode ]
Show the current settings of profile mode, period or both.
collector show sample [all | mode | period]
Show the current settings of sample mode, period, next sample number, or all of the above.
collector show store [ all | directory | filename]
Show the current settings of directory name, file name, and version number of the current experiment, or all of the above.
collector show working_set [all | mode]
Show the current working set data collection mode.
collector status Shows whether an experiment is opend and the name of the experiment. Also shows the number of samples collected.
collector store directory "directory_name"
Specify the directory name of where the experiment database is to be created. The default is the current working directory.
collector store filename "file_name"
Specify the file name that is to be the name of the experiment. The default experiment name is test.<n>.er, where n is the next highest version number.
collector working set mode [on | off]
Determine whether working set sampling should be enabled.
collector update Send current user settings to the GUI Collector. If the GUI Collector is not activated, then collector update activates the GUI Collector.
ENVIRONMENT
dbx checks the environment variable EDITOR for the name of the text editor to use with the edit command.
FILES
core default core file
.dbxinit local dbx initialization file
~/.dbxinit user’s dbx initialization file
SEE ALSO
csh(1), dbxinit(5), debugger(1), kill(1), make(1),
Debugging a Program
For detailed information on the Collector, see Performance Tuning an Application .
NOTES
Because the cc command does not generate or support 8-bit symbol names, it is inappropriate to make dbx 8-bit clean. See cc(1V) for an explanation about why cc is not 8-bit clean.
— Last change: 20 August 1992