dbx(1) General Commands Manual dbx(1)
Name
dbx - source level debugger
Syntax
dbx [-I dir] [-c file] [-k] [-i] [-r] [-pixie] [object [core]]
Description
The command invokes a source-level debugger. Once you invoke you issue commands that control the debugger. These commands allow you to
examine source files, control program execution, display the state of the program, and debug at the machine level.
You can use command options to modify some steps that performs during startup. (For information on the available options, see Options.)
Unless you specify the -r option, prompts you for a command before it begins executing your program. The prompt appears as follows:
(dbx)
To leave issue the quit command.
Arguments
On the command line, the object argument names the object file that you want to read as input. For complete support, the object file must
contain extended symbol table information. The supported compilers each have a -g option that produces the symbol table information in the
object file.
The extended symbol table contains the name of all the source files translated by the compiler to create the object file. This information
allows you to look at all the source code that went into creating an object file during your debugging session. (The extended symbol table
also contains other information.)
If your object file does not contain the extended symbol table information, use the commands described in Debugging at the Machine Level to
debug your program.
If you omit the object argument, prompts you for the name of an object file. If you press the Return key, attempts to read a file named
from the current directory. If no file exists, exits.
The core argument names a core dump file. You can examine the core dump file to determine the state of the program when it failed.
Initialization File
During its startup, reads and executes the commands in an initialization file, if one is present. By default, searches for the file in the
current directory. If no file exists in the current directory, searches your home directory for the file. You can use the initialization
file to issue setup commands automatically when you begin a session.
Debugger Expressions
You specify expressions using the C or Pascal syntax for expressions. The debugger supports a subset of the expression syntax for both lan-
guages; that is, it supports the syntax that is common between the two languages.
In some cases, the debugger supports the syntax of either C or Pascal. For example, you can denote indirection using either an asterisk
(*) as a prefix or a circumflex (^) as a suffix. You can use the field reference operator (.) with pointers as well as records or struc-
tures, making the C operator (->) unnecessary (although it is supported).
You must enclose array expressions in brackets ([ ]).
You can also specify a register name in an expression. You denote registers by $rN where N is the number of the register.
Debugger Name Resolution
The debugger resolves names by searching for the name in the static scope of the current function. If no name is defined in the static
scope, the debugger searches the dynamic scope. If neither scope yields a defined name, the debugger chooses an arbitrary symbol and dis-
plays the following message:
[using qualified.name]
The debugger substitutes the qualified name of the arbitrary symbol for qualified.name in the message.
You can override this name resolution procedure by qualifying identifiers with a block name, as in module.variable. For the C language,
the debugger treats a source file as a module named from the filename without
Options
-c file Selects a command file other than
-i Invokes in interactive mode. This option causes the debugger to not treat source lines beginning with number signs (#) as
comments.
-I dir Adds dir to the list of directories that searches for source files. By default, searches the current directory and the
directory where object is located. You can specify multiple directories by using multiple -I options.
-k Maps memory addresses. This option is useful for kernel debugging.
-pixie Reads in output from the utility. The utility is a code profiler.
For this option to work, you must have executable output and the executable file in the same directory. The output must be
named filename.pixie, where filename is the name of the executable file.
-r Executes the object file immediately. If program execution terminates with an error, displays the message that describes the
error. You can then either invoke the debugger or let the program continue exiting. The debugger reads from when you specify
the -r option and standard input is not a terminal. If the program executes successfully, prompts you for input.
dbx Commands
The debugger supplies a number of commands that you can issue at the dbx prompt. This section describes each command.
The Monitor
The following commands control the monitor:
!string
!integer
!-integer Executes a command from the history list. You can specify the command name in the string argument. If you specify an inte-
ger, executes the command having that number in the history list. If you specify -integer, the debugger executes the command
that you issued integer commands ago. For example, if you specify -3, the debugger issues the command you issued three com-
mands ago. The debugger echoes the command on standard output before executing it.
help [topic] With no argument, displays a list of topics for which help information is available. If you name a topic, the debugger dis-
plays help information on that topic.
history Displays a list of the previous commands you issued. By default, the debugger displays the previous 20 commands. You can
change the number of commands keeps in the history list by using the set command to modify the $lines debugger variable.
quit Exit
Controlling dbx
You can use the following commands to control the operation of the debugger:
alias [name[(arg1,arg2,...)] "string"]
Lists all existing aliases or defines an alias. If you omit all arguments to the alias command, displays a list of the
existing aliases.
You can supply arguments to define a new alias. If you specify a command for string, the debugger assigns name as an alias
for that command. For example, to define an alias rr for the command rerun, issue the following command:
(dbx) alias rr "rerun"
If you specify parameters in the alias command, the debugger substitutes the values you supply on the command line when it
executes the command. For example, to define halt as an alias that sets a stop at a particular line, issue the following
command:
(dbx) alias halt(x) "stop at x"
Once you issue this command, interprets the following commands the same:
(dbx) halt(12)
(dbx) stop at 12
Both commands set a breakpoint at source line 12.
To remove an alias, use the unalias command, as shown:
(dbx) unalias halt
delete event-number, ...
delete all
delete * Deletes the specified breakpoint, trace event, or record event from the status list. The argument all and the argument *
delete all events from the status list.
playback input [file]
Replays commands that were saved with the record input command in a text file. If you omit file, the debugger reads commands
from the temporary file it creates by default when you issue the record input command.
playback output [file]
Replays debugger output that was saved with the record output command. If you omit file, the debugger displays output stored
in a temporary file it creates by default when you issue the record output command.
record input [file]
Records all commands you enter at the prompt. If you omit file, the debugger creates a temporary file that it deletes when
you exit from the debugger.
The debugger associates an event number with each record command you issue. You use the event number to turn off recording,
as described with the delete command.
record output [file]
Records all output. If you omit file, the debugger creates a temporary file that it deletes when you exit from the debugger.
The debugger associates an event number with each record command you issue. You use the event number to turn off recording,
as described with the delete command.
source file Executes the commands from the specified file. This command is an alias for the playback input command.
status Lists current breakpoints, record events, and trace events.
set [variable = expression]
Lists existing debugger variables and their values or defines a value for the named debugger variable.
Some debugger variables contain either a zero or nonzero value that controls behavior. For example, when set to a nonzero
value, the $hexstrings variable causes the debugger to display all strings in hexadecimal format. When set to zero, this
variable causes the debugger to display strings in character format. You can set a variable like $hexstrings to a nonzero
value as shown:
(dbx) set $hexstrings = 1
You can disable the variable using the unset command, as shown:
(dbx) unset $hexstrings
You can create a debugger variable using a name of your own. A debugger variable name you create must not conflict with the
name of any variable in the program you are debugging, and it must not begin with a dollar sign ($). For information on
existing debugger variables, see Predefined Debugger Variables. (Use the assign command to change the value of variables in
your program.)
setenv name "string"
Sets the environment variable name to string by changing the value of an existing environment variable or creating a new
one. To reset the environment variable, specify a null string. The following example shows how to reset the EDITOR environ-
ment variable:
(dbx) setenv EDITOR ""
sh [shell command]
Calls a shell from or executes the specified shell command.
tagvalue (tagname)
Returns the value of tagname, where tagname is a tag that marks a function or type definition in your program. If the tag
extends to more than one line or if it contains arguments, the debugger issues an error message. You can use tagvalue in
commands where you specify a procedure or function name.
You create tags using the command. See the reference page for information. The debugger uses the file named in the $tagfile
variable when resolving references to tags.
unalias name Removes the specified alias.
unset variable Removes the setting of a specified debugger variable.
Examining Source Code
The following commands allow you to examine your source files during a debugging session:
/regular expression
?regular expression
Searches forward or backward in the source code for the regular expression. For information on forming regular expressions,
see The Big Gray Book: The Next Step with ULTRIX.
edit [file] Invokes an editor on file or the current source file if none is specified. By default, invokes the editor. You can override
the default setting by modifying the EDITOR environment variable.
file [file] Changes the current file to file, or, if you omit file, displays the name of the current file.
func [expression]
func [procedure/function]
Changes the current procedure or function to the one you specify. If you omit expression and procedure/function, the debug-
ger displays the name of the current procedure or function.
Changing the current function implicitly changes the current source file to the one that contains the procedure or function;
it also changes the current scope used for name resolution.
list [source-line-number[:integer]]
list [source-line-number[, source-line-number]]
list [procedure/function]
Lists the lines in the current source file.
If you specify a source line number and an integer, lists beginning from source-line-number and continuing for integer num-
ber of lines. If you omit integer, the debugger displays 10 lines, by default.
If you specify two source line numbers separated by a comma, the debugger begins the display at the first source line number
and continues through the second source line number. If you omit the second source line number, the debugger displays 10
lines, by default.
If you specify a procedure or function name, the debugger displays lines in that procedure or function. The debugger dis-
plays 10 lines be default.
If you omit all arguments, the debugger begins the display at the current line and displays 10 lines, by default.
The $listwindow debugger variable controls how many lines the debugger displays. The default value for $listwindow is 10.
tag tagname Sets the current source file or source line to the location specified by tagname.
You create tags using the command. See the reference page for more information. The debugger uses the tag file named in the
$tagfile debugger variable to resolve references to tags.
use [directory...]
Displays or sets the list of directories that uses when searching for source files. If you issue the use command without
arguments, the debugger displays the list of directories it searches for source files. To change the directory list, specify
the names of the directories you want on the list as arguments to the use command. The directories you specify replace any
existing directory list.
whatis variable
Displays the type declaration for variable.
whereis variable
Displays the fully qualified name of each occurrence of variable. The order in which the debugger displays the qualified
names is not meaningful.
which variable Displays the fully qualified name of variable.
Preparing for Program Execution
Before you execute your program under control, you might want to perform setup tasks, such as changing the value of program variables,
specifying what signals your program should recognize or ignore, and setting breakpoints. The following list describes the commands you
use to perform these tasks:
assign variable = expression
Assigns the value of the specified expression to the specified program variable. (Use the set command to set the value of
debugger variables.)
catch [signal] Lists all signals that catches, or, if you supply an argument, causes to catch that signal. The signal you specify is added
to the list of signals catches, so the debugger continues to catch any signals that were already on its list. Some signals
cannot be caught by any process. For a list of signals and information on which signals can be caught, see the reference
page.
ignore [signal]
Lists all signals that ignores. If you specify a signal, this command adds the signal to the list of signals the debugger
ignores. Some signals cannot be ignored by any process. For a list of signals and information on which signals can be
ignored, see the reference page.
stop variable
stop [variable] at source-line [if condition]
stop [variable] in procedure/function [if condition]
stop [variable] if condition
Stops execution when the specified variable changes value, the specified source line is reached, the specified procedure or
function is called, or the specified condition is true. The condition must be a Boolean expression.
If you specify variable with a source line number, the debugger stops execution when the source line number is reached and
the variable changes value. If you specify variable with in procedure/function, the debugger stops execution when it is
executing in the named procedure or function and the named variable changes value. With if condition, the debugger stops
execution when the condition is met and the variable changes value.
If you specify a condition with at source-line or in procedure/function, the debugger stops only if the condition is true.
The debugger associates an event number with each stop command you issue. You use the event number to remove the break-
point, as described with the delete command.
trace [at] source-line
trace procedure/function
trace variable [at source-line] [if condition]
trace variable [in procedure/function] [if condition]
Displays tracing information during program execution. The debugger associates an event number with each trace command you
issue. You use the event number to turn off tracing, as described with the delete command.
The first argument to the trace command specifies what the debugger traces. You can specify a source line number, a proce-
dure name, or a variable name.
If you specify a source line number, displays the source line immediately prior to executing it. You can specify a source
line number in a source file that is not the current one. To do so, precede the source line number with the source file name
in quotation marks (" ") followed by a colon (:), as shown in the following example:
(dbx) trace at "source_file.c":17
The example specifies tracing line 17 in
Specifying a procedure or function name causes to display the name of the calling routine, the source line that contains the
call, and the parameters that are passed to the called routine. In addition, notes the return of the named procedure or
function and displays the return value, if any. The debugger displays this information each time the procedure or function
is called.
Specifying a variable name causes to display the name and value of the variable each time it changes. Program execution is
substantially slower during this form of tracing.
If you specify the in procedure/function clause, displays tracing information only while executing the specified procedure
or function.
The condition is a Boolean expression that evaluates prior to displaying any tracing information. The debugger displays
tracing information only if the condition is true.
when [variable] [at line] {command_list}
when [variable] [in procedure/function] {command_list}
Executes the specified command list. You can separate the commands by commas (,) or semi-colons (;).
If you specify variable, the debugger executes the command list when the value of the variable changes. Specify at line or
in procedure to control which occurrence of the variable causes the debugger to execute the command list.
Initiating Program Execution
The following commands allow you to control program execution:
call procedure/function ([parameters])
Executes the object code associated with the named procedure or function. This command passes the specified parameters to
the procedure or function.
[n] cont [signal]
cont [signal] to source-line
cont [signal] in procedure/function
Continues execution from where it stopped. If you specify an integer n, the debugger ignores that number of stops after it
resumes program execution. If you specify signal, the process continues as though it received the signal.
If you specify to source-line, the debugger continues execution until it reaches the specified source line.
If you specify in procedure/function, the debugger resumes execution in the named procedure or function.
goto source-line
Begins execution at the specified source line.
next [integer] Executes up to the next source line. If the source line that is executed contains a call to a procedure or function, the
next command executes the entire procedure or function. Program execution stops following the return from the procedure or
function; that is, execution stops prior to the source line that follows the call.
If you specify integer, the debugger performs the specified number of next commands.
rerun [arg1, arg2,...] [<file1][>file2]
rerun [arg1, arg2,...] [<file1][>&file2]
Reruns the program, using the same arguments that were specified with the run command. If you specify new arguments, rerun
uses those arguments.
You can use angle brackets (< or >) to redirect input or output in the usual manner.
run [arg1,arg2,...] [<file1] [>file2]
run [arg1,arg2,...] [<file1] [>&file2]
Runs the program, passing it the specified arguments.
You can use angle brackets (< or >) to redirect input or output in the usual manner.
return [procedure/function]
Executes until a return to procedure/function is executed or until the current procedure or function returns if you omit
procedure/function.
step [integer] Executes one source line. If the source line contains a call to a procedure or function, the step command stops at the first
line of the procedure or function. (The debugger does not stop at the first line of a procedure or function if you compiled
your program without using the -g option.)
If you specify integer, the debugger performs the specified number of step commands.
Examining Program State
The following commands help you determine the state of your program:
dump [procedure/function] [.]
Displays variable information about the named procedure or function, or the current procedure or function if you do not
specify one. If you specify dot (.), the debugger displays information on all procedures or functions in the stack and
their variables.
down [expression]
Moves the current function down count activation levels in the stack. The default is one level.
up [expression]
Moves the current function up count activation levels on the stack. The default is one level.
print expression1,expression2,...
Displays the value of the specified expression.
printf "format", arg1,arg2,...
Formats a complex structure for display as specified. You use the same format specifiers for this command as for the subrou-
tine. For information on specifying the format, see (The conversion specification is not supported.)
printregs Displays all register values.
where [n] Displays a list of the active procedures and functions. If you specify n, the debugger displays only procedures and func-
tions in the top n levels of the stack.
Debugging at the Machine Level
You can use machine level commands to debug any program, regardless of whether the program object file contains extended symbol table
information.
You can specify symbolic addresses by preceding the name with an ampersand (&). You denote registers by $rN, where N is the number of the
register. Addresses may be expressions made up of other addresses and the operators plus (+), minus (-), and indirection (unary asterisk,
*).
The following describes the machine level commands:
address/count mode
address?count mode
Searches forward (or backward, if you specify ?) and displays the contents of address or disassembles the code for the
instruction address. The count argument specifies the number of items that the debugger displays at the specified address.
The mode determines how displays memory; if you omit it, the debugger uses the previous mode. The initial mode is X. You
can specify the following modes:
b Displays a byte in octal.
c Displays a byte as a character.
d Displays a short word in decimal.
D Displays a long word in decimal.
f Displays a single precision real number.
g Displays a double precision real number.
i Displays machine instructions.
n Displays data in typed format.
o Displays a short word in octal.
O Displays a long word in octal.
s Displays a string of characters that ends in a null.
x Displays a short word in hexadecimal.
X Displays a long word in hexadecimal.
The debugger maintains the next address to be displayed in dot (.). To display the next address, you can use the following
command:
(dbx) ./
The debugger will display the next count locations in the mode specified in the previous command.
address/countL value mask
Searches for a 32-bit word that satisfies the mask. The debugger starts searching at the specified address. The count argu-
ment specifies the number of words the debugger processes during the search.
The debugger masks the word stored at address using the value specified in mask. If the masked value equals value, the
debugger displays the address of the masked value. Otherwise, the debugger increments address and continues to search.
[n] conti [signal]
conti [signal] to address
conti [signal] in procedure/function
Continues execution of assembly code from where it stopped. If you specify an integer n, the debugger ignores that number
of stops after it resumes program execution. If you specify signal, the process continues as though it received the signal.
If you specify to address, the debugger continues execution until it reaches the specified address.
If you specify in procedure/function, the debugger resumes execution in the named procedure or function.
nexti [integer]
Executes up to the next machine instruction. If the machine instruction that executes contains a call to a procedure or
function, the debugger executes the entire procedure or function. Program execution stops following the return from the pro-
cedure; that is, execution stops prior to execution of the machine instruction that follows the call.
If you specify an integer, the debugger performs integer nexti instructions.
stepi [integer]
Executes the specified number of machine instructions. If one of the machine instructions contains a call to a procedure or
function, the debugger stops at the first line of the procedure or function. The default is to execute one instruction.
stopi variable
stopi [variable] [at address] [if condition]
stopi [variable] [in procedure/function] [if condition]
Stops when the specified variable changes value, the specified address is reached, the specified condition is true, or the
specified procedure or function is reached.
By combining the arguments, you can cause the debugger to stop, for example, only when the occurrence of variable at the
specified address changes value and condition is true.
tracei variable [at address] [if expression]
tracei variable [in procedure/function] [at address] [if expression]
tracei address [if condition]
Traces the value of variable or the execution of a particular address.
When you trace the value of a variable, you can use at address, in procedure/function, and if condition to control the spe-
cific variable that is traced.
You can specify a condition when you trace the execution of an address. The debugger displays tracing information only when
the condition is true.
wheni [variable] [at address] {command_list}
wheni [variable] [in procedure/function] {command_list}
Executes the specified machine command list. You can separate the commands by commas (,) or semi-colons (;).
If you specify variable, the debugger executes the command list when the value of the variable changes. Specify at address
or in procedure to control which occurrence of the variable causes the debugger to execute the command list.
Predefined dbx Variables
The debugger contains variables that control certain aspects of its operations. Some debugger variables are used internally by You must not
change the value of those variables. The debugger allows you to change the values of other variables using the set and unset commands. The
following list describes the debugger variables you can control:
$addrfmt Specifies the format for addresses. You can set this variable to any format that you can use with the function, except %s
because the conversion specification is not supported by See the reference page for information on valid formats. By
default, this variable is set to which specifies hexadecimal format.
$casesense When set to a nonzero value, specifies that uppercase and lowercase letters be treated as different characters during a
search. When set to zero, ignores the case of letters. The default is zero.
$datacache Caches information from the data space so that must access the data space only once. If this variable is set to zero, the
debugger does not cache data space. If your program contains any data declared as automatically sets this variable to zero.
To debug the operating system, set this variable to zero; otherwise, set it to a nonzero value. The default is a nonzero
value.
$dispix Causes the debugger to be in the correct mode to debug pixie code. When set to zero, the debugger displays machine code
while debugging. When set to a nonzero value, the debugger displays pixie code. The default is zero.
$hexchars When set to a nonzero value, causes the debugger to display characters in hexadecimal format.
$hexin When set to a nonzero value, causes the debugger to interpret input constants as hexadecimal. When set, this variable over-
rides the $octin variable.
$hexints When set to a nonzero value, changes the default output constants to hexadecimal. When set, this variable overrides the
$octints variable.
$hexstrings When set to a nonzero value, causes the debugger to display all strings in hexadecimal format. When set to zero, causes the
debugger to display strings in character format.
$historyevent Stores the current history line.
$lines Determines how many lines the debugger stores in its history list. The default is 20 lines.
$listwindow Specifies how many lines the list command displays.
$main Specifies the name of the procedure or function that begins when running the process. The debugger can begin a process at
any procedure or function. By default, the debugger begins a process at a procedure named main.
$maxstrlen Specifies how many characters of a string displays for pointers to strings. The default is 128 characters.
$octin When set to a nonzero value, changes the default input constants to octal. When set, the $hexin variable overrides this
variable.
$octints When set to a nonzero value, causes to display integers in octal format. When set, the $hexints variable overrides this
variable.
$page Specifies whether to page long information. A nonzero value turns on paging; a zero turns it off. The default is one.
$pagewindow Specifies how many lines the debugger displays when information runs longer than one screen. You can change this variable
to match the number of lines on any terminal. If set to zero, this variable assumes one line. The default is 22, leaving
space for a continuation query.
$printwhilestep
Determines whether the debugger displays source lines or instructions when executing the step[n] and stepi[n] commands.
When set to a nonzero value, causes to display all n lines or instructions. When set to zero, causes to display only the
last line or instruction. The default is zero.
$pimode Displays input when used with the playback input command. The default is zero.
$printdata When set to a nonzero value, causes the debugger to display the contents of registers next to each instruction it displays.
The debugger displays the registers used by the instruction. The default is zero.
$printwide When set to a nonzero value, causes the debugger to display the contents of variables in a horizontal format. The default
is zero.
$prompt Sets the prompt for
$readtextfile When set to a nonzero value, causes to read instructions from the object file rather than the process. This variable should
always be set to zero when the process being debugged copies in code during the debugging process. The default is a nonzero
value.
$regstyle When set to a nonzero value, causes the debugger to display registers during disassembly in their normal r format
(r0,r1,...r31). When set to zero, causes the debugger to display registers in a special format (zero, at, v0, v1,...),
which is commonly used in debugging programs written in assembly language. The default is a nonzero value.
Setting this variable does not affect how the debugger displays the names of register when you issue the printregs command.
This variable affects the debugger's machine level commands.
$repeatmode When set to a nonzero value, causes to repeat the previous command if you press the Return key at the prompt. The default
is a nonzero value.
$rimode When set to a nonzero value, causes the debugger to record input while recording output. The default is zero.
$sigvec Tells the name of the code called by the system to invoke user signal handlers. This variable is set to sigvec on ULTRIX
systems.
$symtotal Stores the number of symbols that loads for the process you are debugging.
$tagfile Names the file that contains tags for the current program. The tag and tagvalue commands search the named file to resolve
references to tags. For more information on using tag files, see
Restrictions
The printf debugger command does not support the conversion specification.
The debugger does not allow you to run a program you do not own unless you are logged in as root. If you are not root, the following mes-
sage might be displayed on your screen when you issue the run command:
cannot write to address address in process proc-number
In the message it displays, the debugger replaces address with the address to which it could not write and proc-number with the number of
the process that contains that address. This message is displayed when the debugger tries to set breakpoints because of restrictions on
the system call. The debugger always tries to set a breakpoint on exit. If you repeat the command, your program runs without breakpoints.
Files
Object file
Core dump file
Initialization file
See Also
ac(1), cc(1), ctags(1), f77(1), pc(1), pcc(1), pixie(1), vi(1), signal(3), printf(3s)
Guide to Languages and Programming
RISC dbx(1)