DBX(1) BSD DBX(1)
NAME
dbx - source code debugger
SYNOPSIS
dbx [ -r ] [ -i ] [ -k ] [ -I dir ] [ -no_src ] [ -no_frame ] [ -c file ]
[ objfile ]
DESCRIPTION
dbx is a tool for source-level debugging and execution of programs under
BSD. The objfile is an object file produced by a compiler, with the
appropriate flag (usually -g) specified to produce symbol information in
the object file. Currently, cc(1), and f77(1) produce the appropriate
source information. You can use the machine-level facilities of dbx on
any program. All compilers and assemblers produce debugging information
usable by dbx.
The object file contains a symbol table that includes the name of the all
the source files translated by the compiler to create it. These files
are available for perusal while you use the debugger.
If the file .dbxinit exists in the current directory, the debugger
commands in it are executed. dbx also checks for a .dbxinit in your home
directory if there isn't one in the current directory.
dbx creates a separate transcript pad for debugger interactions unless
you specify the -no_frame option. dbx also creates a window to display
source code unless you specify the -no_src.
OPTIONS
-r Execute objfile immediately. If it terminates successfully,
dbx exits. Otherwise the reason for termination is reported
and you are offered the choice of entering the debugger or
letting the program fault. dbx reads from /dev/tty when you
specify -r and standard input is not a terminal.
-i Force dbx to act as though standard input is a terminal.
-k Map memory addresses. This option is useful for kernel
debugging.
-I dir Add dir to the list of directories that are searched when
looking for a source file. Normally dbx looks for source files
in the current directory and in the directory where objfile is
located. You can can also use the use command to set the
directory search path.
-c file Execute the dbx commands in the file before reading from
standard input.
-no_src Disable source display.
-no_frame Do not create a separate debugger transcript pad.
Unless you specify -r, dbx just prompts and waits for a command.
Execution and Tracing Commands
run [args] [< filename] [> filename]
rerun [args] [< filename] [> filename]
Start executing objfile, passing args as command line arguments; you
can use < or > to redirect input or output in the usual manner.
When you use rerun without any arguments, the previous argument list
is passed to the program; otherwise it is identical to run. If
objfile was written since the last time the symbolic information was
read in, dbx reads in the new information.
trace [in procedure/function] [if condition]
trace source-line-number [if condition]
trace procedure/function [in procedure/function] [if condition]
trace expression at source-line-number [if condition]
trace variable [in procedure/function] [if condition]
Have tracing information printed when the program is executed. A
number is associated with the command that is used to turn the
tracing off (see the delete command).
The first argument describes what is to be traced. If it is a
source-line-number, the line is printed immediately before being
executed. You must precede source-line numbers in a file other than
the current one by the name of the file in quotation marks and a
colon, for example, "mumble.p":17.
If the argument is a procedure or function name, then every time it
is called, information is printed telling what routine called it,
from what source line it was called, and what parameters were passed
to it. In addition, its return is noted, and if it's a function,
the value it is returning is also printed.
If the argument is an expression with an at clause, the value of the
expression is printed whenever the identified source line is
reached.
If the argument is a variable, the name and value of the variable is
printed whenever it changes. Execution is substantially slower
during this form of tracing.
If no argument is specified, all source lines are printed before
they are executed. Execution is substantially slower during this
form of tracing.
The clause "in procedure/function" specifies that tracing
information is printed only while dbx is executing inside the given
procedure or function.
condition is a Boolean expression and dbx evaluates it before it
prints the tracing information; if condition is false, dbx does not
print the information.
stop if condition
stop at source-line-number [if condition]
stop in procedure/function [if condition]
stop variable [if condition]
Stop execution when the given line is reached; procedure or function
called; variable changed; or condition true.
status [> filename]
Print the currently active trace and stop commands.
delete command-number ...
Remove the traces or stops corresponding to the given numbers. The
status command prints the numbers associated with traces and stops.
catch number
catch signal-name
ignore number
ignore signal-name
Start or stop trapping a signal before it is sent to the program.
This is useful when a program being debugged handles signals such as
interrupts. You can specify a signal by number or by a name (for
example, SIGINT). Signal names are case-insensitive and the "SIG"
prefix is optional. By default all signals are trapped except
SIGCONT, SIGCHILD, SIGALRM and SIGKILL.
cont integer
cont signal-name
Continue execution from where it stopped. If a signal is specified,
the process continues as though it received the signal. Otherwise,
the process is continued as though it had not been stopped.
You cannot continue to execute a process if it has "finished", that is,
called the standard procedure exit(). dbx does not allow the process to
exit, thereby letting you examine the program state.
step Execute one source line.
next Execute up to the next source line. The difference between this and
step is that if the line contains a call to a procedure or function
the step command stops at the beginning of that block, while the
next command does not.
return [procedure]
Continue until a return to procedure is executed, or, if you do not
specify a procedure, until the current procedure returns.
call procedure(parameters)
Execute the object code associated with the named procedure or
function.
Printing Variables and Expressions
Names are resolved first using the static scope of the current function,
then using the dynamic scope if the name is not defined in the static
scope. If static and dynamic searches do not yield a result, an
arbitrary symbol is chosen and the message "[using qualified name]" is
printed. The name-resolution procedure may be overridden by qualifying
an identifier with a block name, for example, "module.variable". For C,
source files are treated as modules named by the filename without ".c".
Expressions are specified with an approximately common subset of C and
Pascal (or equivalently Modula-2) syntax. Indirection can be denoted
using either a prefix "*" or a postfix "^" and array expressions are
subscripted by brackets ("[ ]"). The field reference operator (".") can
be used with pointers as well as records, making the C operator "->"
unnecessary (although it is supported).
dbx checks types of expressions; use "type-name(expression)" to override
the type of an expression. When there is no corresponding named type,
you can use the special constructs "&type-name" and "$$tag-name" to
represent a pointer to a named type or C-structure tag.
assign variable = expression
Assign the value of the expression to the variable.
dump [procedure] [> filename]
Print the names and values of variables in the given procedure, or
the current procedure if you did not specify one. If you specify
".", for procedure, dbx dumps all active variables.
print expression [, expression ...]
Print out the values of the expressions.
whatis name
Print the declaration of the given name, which you can qualify with
block names as above.
which identifier
Print the full qualification of the given identifer, that is, the
outer blocks that the identifier is associated with.
up [count]
down [count]
Move the current function, which is used for resolving names, up or
down the stack count levels. The default count is 1.
where
Print a list of the active procedures and function.
whereis identifier
Print the full qualification of all the symbols whose name matches
the given identifier. The order in which the symbols are printed is
not meaningful.
Accessing Source Files
/regular expression[/]
?regular expression[?]
Search forward or backward in the current source file for the given
pattern.
edit [filename]
edit procedure/function-name
Invoke an editor on filename or the current source file if you did
not specify one. If you specify a procedure or function name, dbx
invokes the editor on the file that contains it. Which editor is
invoked by default depends on the installation. Set the environment
variable EDITOR to the name of the desired editor to override the
default.
file [filename]
Change the current source filename to filename. If you do not
specify one, dbx prints the current source filename.
func [procedure/function]
Change the current function. If you do not specify one, dbx prints
the current function. Changing the current function implicitly
changes the current source file to the one that contains the
function; it also changes the current scope used for name
resolution.
list [source-line-number [, source-line-number]]
list procedure/function
List the lines in the current source file from the first line number
to the second, inclusive. If no lines are specified, dbx lists the
next 10 lines. If the name of a procedure or function is given, dbx
lists lines n-k to n+k, where n is the first statement in the
procedure or function and k is small.
use directory-list
Set the list of directories to be searched when looking for source
files.
Command Aliases and Variables
alias name name
alias name "string"
alias name (parameters) "string"
When commands are processed, dbx first checks to see if the word is
an alias for either a command or a string. If it is an alias, dbx
treats the input as though the corresponding string (with values
substituted for any parameters) were entered. For example, to
define an alias rr for the command rerun, you can specify
alias rr rerun
To define an alias b that sets a stop at a particular line you can
specify
alias b(x) "stop at x"
Subsequently, the command b(12) expands to stop at 12.
set name [= expression]
The set command defines values for debugger variables. The names of
these variables cannot conflict with names in the program being
debugged, and are expanded to the corresponding expression within
other commands. The following variables have a special meaning:
$frame
Setting this variable to an address causes dbx to use the
stack frame pointed to by the address for doing stack traces
and accessing local variables. (This variable is not
supported by Domain/OS BSD).
$hexchars
$hexints
$hexoffsets
$hexstrings
When these variables are set, dbx prints characters,
integers, offsets from registers, or character pointers,
respectively, in hexadecimal.
$listwindow
The value of this variable specifies the number of lines to
list around a function or when you specify the list command
without any parameters. This value is also used when
displaying source in the source window. The current line is
positioned so that as much of the listwindow as possible is
visible. Its default value is 10.
$mapaddrs
Setting (unsetting) this variable causes dbx to start (stop)
mapping addresses. As with $frame, this is useful for
kernel debugging.
$unsafecall
$unsafeassign
When the $unsafecall variable is set, strict type checking
is turned off for arguments to subroutine or function calls
(for example, in the call statement). When unsafeassign is
set, strict type-checking between the two sides of an assign
statement is turned off. These variables should be used
only with great care, because they severely limit dbx's
usefulness for detecting errors.
unalias name
Remove the alias with the given name.
unset name
Delete the debugger variable associated with name.
Machine Level Commands
tracei [address] [if cond]
tracei [variable] [at address] [if cond]
stopi [address] [if cond]
stopi [at] [address] [if cond]
Turn on tracing or set a stop using a machine instruction address.
stepi
nexti
Single step as in step or next, but do a single instruction rather
than source line.
address ,address/ [mode]
address / [count] [mode]
Print the contents of memory starting at the first address and
continuing up to the second address or until count items are
printed. If the address is ".", dbx uses the address following the
one printed most recently. The mode specifies how memory is to be
printed; if you omit it, dbx uses the previous mode specified. The
initial mode is "X". The following modes are supported:
i Print the machine instruction.
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 terminated by a null byte.
f Print a single precision real number.
g Print a double precision real number.
Specify symbolic addresses by preceding the name with an "&". Specify
$rn, where n is the number of the register, to denote registers.
Addresses can be expressions made up of other addresses and the operators
"+", "-", and indirection (unary "*").
Miscellaneous Commands
gripe
Invoke a mail program to send a message to the person in charge of
dbx. (This command is not supported by Domain/OS BSD).
help Print a synopsis of dbx commands.
quit Exit dbx.
sh command-line
Pass the command line to the shell for execution. The SHELL
environment variable determines which shell is used.
source filename
Read dbx commands from the given filename.
BUGS
dbx suffers from the same "multiple include" malady as did sdb. If you
have a program consisting of a number of object files and each is built
from source files that include header files, the symbolic information for
the header files is replicated in each object file. Since about one
debugger start-up is done for each link, having the linker (ld) re-
organize the symbol information would not save much time, though it would
reduce some of the disk space used.
This problem is an artifact of the unrestricted semantics of #includes in
C; for example an include file can contain static declarations that are
separate entities for each file in which they are included. However,
even with Modula-2 a lot of duplication of symbol information is
necessary for inter-module type checking.
Some problems remain with the support for individual languages. FORTRAN
problems include the following
⊕ Inability to assign to logical, logical*2, complex and double complex
variables
⊕ Inability to represent parameter constants that are not type integer
or real
⊕ Peculiar representation for the values of dummy procedures (the value
shown for a dummy procedure is actually the first few bytes of the
procedure text; to find the location of the procedure, use "&" to take
the address of the variable)
FILES
a.out object file
.dbxinit,~/.dbxinit initial commands
SEE ALSO
cc(1), dde(1), f77(1)