DBX(1) RISC/os Reference Manual DBX(1)
NAME
dbx - source-level debugger
SYNOPSIS
dbx [-Idirectory] [-cfile] [-i] [-r ] [object] [core]
DESCRIPTION
dbx is a source-level debugger running under RISC/os. This
enhanced version of dbx works with cc(1), pc(1), f77(1),
cobol(1), pl1(1), as(1), and MIPS machine code.
The object file used with the debugger is produced by speci-
fying an appropriate option (usually -g) to the compiler.
The resulting object file contains symbol table information,
including the names of all source files that the compiler
translated to create the object file. These source files
are accessible from the debugger. If -g is not specified,
limited debugging is possible.
If a coredump file is specified, dbx can be used to look at
the state of the program when it faulted.
dbx does not support lines greater than 511.
Running dbx
If a .dbxinit file resides in the current directory or in
the user's home directory, the commands in it are executed
when dbx is invoked.
When invoked, dbx recognizes these command line options:
-I directory or -Idirectory
Tells dbx to look in the specified directory for
source files. Multiple directories can be specified
by using multiple -I options. dbx searches for
source files in the current directory and in the
object file's directory whether or not -I is used.
-c file Selects a command file other than .dbxinit.
-i Uses interactive mode. This option does not treat
#s as comments in a file. It prompts for source
even when it reads from a file. With this option,
dbx also has extra formatting as if for a terminal.
-r Runs the object file immediately.
-pixie Uses pixie output. The executable must be
`executable.pixie', and the non-pixie executable
must be in the same directory as the pixie execut-
able.
Printed 11/19/92 Page 1
DBX(1) RISC/os Reference Manual DBX(1)
-prom Permits debugging in the standalone environment when
using the MIPS System Programmer's Package. For
more information, refer to the System Programmer's
Package Reference manual.
-sable Permits debugging programs running under the proces-
sor simulator when using the MIPS System
Programmer's Package.
The dbx monitor offers powerful command line editing. For a
full description of these emacs-style editing features, see
csh(1).
Multiple commands can be specified on the same command line
by separating them with a semicolon (;). If the user types
a string and presses the stop character (usually ^z; see
stty(1)), dbx tries to complete a symbol name from the pro-
gram that matches the string.
dbx can also run under emacs as inferior, which means under
this mode, dbx is controlled by emacs and communicates with
emacs. When in emacs, command M-x dbx starts dbx and will
prompt you for filename to be debugged. In the RISC/os
environment, the following keys are bound to commonly used
dbx commands: M-n, M-s, M-i, M-u, M-d, C-c C-f, C-x space,
representing next, step, stepi, up, down, finish, set break-
point at current line respectively. Note that in emacs, M-x
usually means esc-x, C-x means ctl-x. In emacs you can
define your own key bindings.
The Monitor
These commands control the dbx monitor:
![string] [integer] [-integer]
Specifies a command from the history list.
help Prints a list of dbx commands, using more(1) to
display the list.
history Prints the items from the history list. The default
if 20.
quit[!] Exit dbx after verification. If ! is specified,
verification isn't required.
Controlling dbx
alias [name(arg1,...argN)"string"]
Lists all existing aliases, or, if an argument is
specified, defines a new alias.
unalias alias command_name
Removes the specified alias.
Page 2 Printed 11/19/92
DBX(1) RISC/os Reference Manual DBX(1)
delete expression1, ...expressionN
delete all
Deletes the specified item from the status list.
The argument all deletes all items from the status
list.
playback input [file]
Replays commands that were saved with the record
input command in a text file.
playback output [file]
Replays debugger output that was saved with the
record output command.
record input [file]
Records all commands typed to dbx.
record output [file]
Records all dbx output.
sh [shell command]
Calls a shell from dbx or executes a shell command.
status Lists currently set stop, record, and trace com-
mands.
tagvalue (tagname)
Returns the value of tagname. If the tags extends
to more than one line, or if it contains arguments,
an error occurs. tagvalue can be used in any
expression.
set [variable = expression]
Lists existing debugger variables and their values.
This command can also be used to assign a new value
to an existing variable or to define a new variable.
unset variable
Removes the setting of a specified debugger vari-
able.
Examining Source
/regular expression
Searches ahead in the source code for the regular
expression.
?regular expression
Searches back in the source code for the regular
expression.
edit [file]
Printed 11/19/92 Page 3
DBX(1) RISC/os Reference Manual DBX(1)
Calls an editor from dbx.
file [file]
Prints the current file name, or, if a file name is
specified, this command changes the current file to
the specified file.
func [expression] [procedure]
Moves to the specified procedure (activation level),
or, if an expression or procedure isn't specified,
prints the current activation level.
list [expression:integer]
list [expression]
Lists the specified lines. The default is 10 lines.
tag tagname
Sets the current file/line to the location specified
by tagname. Operations are similar to the tag
operations in vi(1).
use [directory1 ... directoryN]
Lists source directories, or, if a directory name is
specified, this command substitutes the new direc-
tories for the previous list.
whatis variable
Prints the type declaration for the specified name.
which variable
Finds the variable name currently being used.
whereis variable
Prints all qualifications (the scopes) of the speci-
fied variable name.
Controlling Programs
assign expression1 = expression2
Assigns the specified expression to a specified pro-
gram variable.
[n] cont [signal]
cont [signal] to line
cont [signal] in procedure
Continues executing a program after a breakpoint. n
breakpoints are ignored if n is specified before
stepping; if specified, signal is delivered to the
processing being debugged.
goto line
Goes to the specified line in the source.
Page 4 Printed 11/19/92
DBX(1) RISC/os Reference Manual DBX(1)
next [integer]
Steps over the specified number of lines. The
default is one. This command does not step into
procedures.
rerun [arg1 ... argN] [<file1][>file2]
rerun [arg1 ... argN] [<file1][>&file2]
Reruns the program, using the same arguments that
were specified to the run command. If new arguments
are specified, rerun uses those arguments.
return [procedure]
Continues executing until the procedure returns. If
a procedure isn't specified, dbx assumes the next
procedure.
run [arg1 ... argN] [<file1] [>file2]
run [arg1 ... argN] [<file1] [>&file2]
Runs the program with the specified arguments.
step [integer]
Steps the specified number of lines. This command
steps into procedures. The default is one line.
Setting Breakpoints
catch [signal]
Lists all signals that dbx catches, or, if an argu-
ment is specified, adds a new signal to the catch
list.
ignore [signal]
Lists all signals that dbx does not catch. If a
signal is specified, this command adds the signal to
the ignore list.
stop [variable]
stop [variable] at line [if expression]
stop [variable] in procedure [if expression]
stop [variable] if expression
Sets a breakpoint at the specified point.
trace variable [at line] [if expression]
trace variable [in procedure] [if expression]
Traces the specified variable.
when [variable] [at line] {command_list}
when [variable] [in procedure] {command_list}
Executes the specified dbx comma separated command
list.
Examining Program State
dump [procedure] [.]
Printed 11/19/92 Page 5
DBX(1) RISC/os Reference Manual DBX(1)
Prints variable information about the procedure. If
a dot (.) is specified, this command prints global
variable information on all procedures in the stack
and the variables of those procedures.
down [expression]
Moves down the specified number of activation levels
in the stack. The default is one level.
up [expression]
Moves up the specified number of activation levels
on the stack. The default is one.
print expression1,...expressionN
Prints the value of the specified expression. If
expression is a dbx keyword, it must be enclosed
within parentheses. For example, to print out a
variable called 'output' (which is also a variable
in the playback and record commands) you must type:
print (output)
printf "string", expression1,...expressionN
Prints the value of the specified expression, using
C language string formatting. As in the print com-
mand, if expression is a dbx keyword, you must
enclose it within parentheses.
printregs
Prints all register values.
where Does a stack trace, which shows the current activa-
tion levels.
where n Prints out only the top n levels of the stack.
Debugging at the Machine Level
[n] conti [signal]
conti [signal] to address
conti [signal] in procedure
Continues executing assembly code after a break-
point. n breakpoints are ignored if n is specified
before stepping; If specified, signal is delivered
to the processing being debugged.
nexti [integer]
Steps over the specified number of machine instruc-
tions. The default is one. This command does not
step into procedures.
stepi [integer]
Page 6 Printed 11/19/92
DBX(1) RISC/os Reference Manual DBX(1)
Steps the specified number of machine instructions.
This command steps into procedures. The default is
one instruction.
stopi [variable] at address] [at address [if expression]
stopi [variable] in procedure [if expression]
stopi [variable] if expression
Sets a breakpoint in the machine code at the speci-
fied point.
tracei variable at address [at address if expression]
tracei variable in procedure [at address if expression]
Traces the specified variable in machine instruc-
tions.
wheni [variable] [at address] {command_list}
wheni [variable] [in procedure] {command_list}
Executes the specified dbx comma separated command
list.
address[?]/<count><mode>
Searching forward (or backward, if ? is specified,)
prints the contents address or disassembles the code
for the instruction address; count is the number of
items to be printed at the specified address. mode
is one of the characters in the following table pro-
ducing the indicated result:
d Print a short word in decimal
D Print a long word in decimal
o Print a short word in octal
O Print a long word in octal
x Print a short word in hexadecimal
X Print a long word in hexadecimal
b Print a byte in octal
c Print a byte as a character
s Print a string of characters that ends in a
null
f Print a single precision real number
g Print a double precision real number
i Print machine instructions
n Prints data in typed format.
address/<countL><value><mask>
Searches for a 32-bit word starting at the specified
address; count specifies the number of word to pro-
cess in the search; an address is printed when the
the word at address, after an AND operation with
mask, is equal to value.
Predefined dbx Variables
Printed 11/19/92 Page 7
DBX(1) RISC/os Reference Manual DBX(1)
The debugger has these predefined variables:
$addrfmt
Specifies the format for addresses. This can be set
any specification that a C printf statement can for-
mat. The default is zero.
$byteaccess
Same as $addrfmt.
$casesense
When set to a nonzero value, specifies that upper-
case and lowercase letters be taken into considera-
tion during a search. When set to 0, the case is
ignored. The default is 0.
$curevent
Shows the last even number as seen in the status
feature. Set only by dbx.
$curline
Specifies the current line. Set only by dbx.
$cursrcline
Shows the last line listed plus 1. Set only by dbx.
$curpc Specifies the current address. Used with the wi and
li aliases.
$datacache
Caches information from the data space so that dbx
must access data space only once. To debug the
operating system, set this variable to 0; otherwise,
set it to a nonzero value. The default is 1.
$debugflag
For internal use by dbx.
$defin For internal use by dbx.
$defout For internal use by dbx.
$dispix For use when debugging pixie code. When set to 0,
machine code is show while debugging. When set to
1, pixie code is shown. The default is 0.
$hexchars
Output characters are printed in hexadecimal format
(set, unset).
$hexin Specifies that input constants are hexadecimal.
Page 8 Printed 11/19/92
DBX(1) RISC/os Reference Manual DBX(1)
$hexints
When set to a nonzero value, changes the default
output constants to hexadecimal. Overrides
$octints.
$hexstrings
When set to 1, specifies that all strings are
printed in hexadecimal; when set to 0, strings are
printed in character format.
$historyevent
Shows the current history line.
$lines number of lines for history. The default is 20.
$listwindow
Specifies how many lines the list command prints.
$main Specifies the name of the procedure that dbx will
start with. This can be set to any procedure. The
default is "main".
$maxstrlen
Specifies how many characters of a string that dbx
prints for pointers to strings. The default is 128.
$octin When set to non-zero, changes the default input con-
stants to octal. When set, $hexint overrides this
setting.
$octints
Output integers are printed octal format (set,
unset).
$page Specifies whether to page long information. A
nonzero value turns on paging; a 0 turns it off.
The default is 1.
$pagewindow
Specifies how many lines print when information runs
longer than one screen. This can be changed to
match the number of lines on any terminal. If set
to 0, this variable assumes one line. The default
is 22, leaving space for continuation query).
$pdbxport
port name from /etc/remote[.pdbx] used to connect to
target machine for pdbx.
$printwhilestep
For use with the step[n] and stepi[n] instructions.
A non-zero integer specifies that all n lines and/or
Printed 11/19/92 Page 9
DBX(1) RISC/os Reference Manual DBX(1)
instructions should be printed out. A zero speci-
fies that only the last line and/or instruction
should be printed out. The default is zero.
$pimode Prints input when used with the playback input com-
mand. The default is 0.
$printdata
When set to a nonzero value, the contents of regis-
ters used are printed next to each instruction
displayed. The default is 0.
$printwide
When se to a nonzero value, the contents of vari-
ables are printed in a horizontal format. The
default is 0.
$prompt Sets the prompt for dbx.
$readtextfile
When set to 1, dbx tries to read instructions from
the object file rather than the process. dbx exe-
cutes faster when debugging remotely using the Sys-
tem Programmer's Package. This variable should
always be set to 0 when the process being debugged
copies in code during the debugging process. The
default is 1.
$regstyle
A zero value causes registers to be printed out in
their normal r format (r0,r1,...r31). A nonzero
value causes the registers to be printed out in a
special format (zero, at, v0, v1,...) commonly used
in debugging programs written in assembly language.
The default is 0.
$repeatmode
When set to a nonzero value, after pressing the
RETURN key (for an empty line), the last command is
repeated. The default is 1.
$rimode When set to a nonzero value, input will is recorded
while recording output. The default is 0.
$sigtramp
Tells dbx the name of the code called by the system
to invoke user signal handlers. This variable is
set to sigtramp systems running under RISC/os.
$tagfile
Contains a filename, indicating the file in which
the tag command and the tabvalue macro are to search
Page 10 Printed 11/19/92
DBX(1) RISC/os Reference Manual DBX(1)
for tags.
Predefined dbx Aliases
The debugger has these predefined aliases:
? Prints a list of all dbx commands.
a Assigns a value to a program variable.
b Sets a breakpoint at a specified line.
bp Stops in a specified procedure.
c Continues program execution after a breakpoint.
d Deletes the specified item from the status list.
e Looks at the specified file.
f Moves to the specified activation level on the
stack.
g Goes to the specified line and begins executing the
program there.
h Lists all items currently on the history list.
j Shows what items are on the status list.
l Lists the next 10 lines of source code.
li Lists the next 10 machine instructions.
n or S Step over the specified number of lines without
stepping into procedure calls.
ni or Si
Step over the specified number of assembly code
instructions without stepping into procedure calls.
p Prints the value of the specified expression or
variable.
pd Prints the value of the specified expression or
variable in decimal.
pi Replays dbx commands that were saved with the record
input command.
po Prints the value of the specified expression or
variable in octal.
Printed 11/19/92 Page 11
DBX(1) RISC/os Reference Manual DBX(1)
pr Prints values for all registers.
px Prints the value for the specified variable or
expression in hexadecimal.
q Ends the debugging session.
r Runs the program again with the same arguments that
were specified with the run command.
ri Records in a file every command typed.
ro Records all debugger output in the specified file.
s Steps the next number of specified lines.
si Steps the next number of specified lines of assembly
code instructions.
t Does a stack trace.
u Lists the previous 10 lines.
w Lists the 5 lines preceding and following the
current line.
W Lists the 10 lines preceding and following the
current line.
wi Lists the 5 machine instructions preceding and fol-
lowing the machine instruction.
SEE ALSO
RISCompiler and C Programmer's Guide.
Page 12 Printed 11/19/92