4.3BSD-UWisc/man/cat1/dbx.1
DBX(1) UNIX Programmer's Manual DBX(1)
NAME
dbx - debugger
SYNOPSIS
dbx [ -r ] [ -i ] [ -k ] [ -I _d_i_r ] [ -c _f_i_l_e ] [ _o_b_j_f_i_l_e [
_c_o_r_e_d_u_m_p ]]
DESCRIPTION
_D_b_x is a tool for source level debugging and execution of
programs under UNIX. The _o_b_j_f_i_l_e is an object file produced
by a compiler with the appropriate flag (usually ``-g'')
specified to produce symbol information in the object file.
Currently, _c_c(1), _f_7_7(1), _p_c(1), and the DEC Western
Research Laboratory Modula-2 compiler, _m_o_d(l), produce the
appropriate source information. The machine level facili-
ties of _d_b_x can be used on any program.
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
using the debugger.
If a file named ``core'' exists in the current directory or
a _c_o_r_e_d_u_m_p file is specified, _d_b_x can be used to examine the
state of the program when it faulted.
If the file ``.dbxinit'' exists in the current directory
then the debugger commands in it are executed. _D_b_x also
checks for a ``.dbxinit'' in the user's home directory if
there isn't one in the current directory.
The command line options and their meanings are:
-r Execute _o_b_j_f_i_l_e immediately. If it terminates suc-
cessfully _d_b_x exits. Otherwise the reason for ter-
mination will be reported and the user offered the
option of entering the debugger or letting the pro-
gram fault. _D_b_x will read from ``/dev/tty'' when -r
is specified and standard input is not a terminal.
-i Force _d_b_x to act as though standard input is a ter-
minal.
-k Map memory addresses, useful for kernel debugging.
-I _d_i_r Add _d_i_r to the list of directories that are searched
when looking for a source file. Normally _d_b_x looks
for source files in the current directory and in the
directory where _o_b_j_f_i_l_e is located. The directory
search path can also be set with the use command.
-c _f_i_l_e Execute the _d_b_x commands in the _f_i_l_e before reading
Printed 12/27/86 January 12, 1986 1
DBX(1) UNIX Programmer's Manual DBX(1)
from standard input.
Unless -r is specified, _d_b_x just prompts and waits for a
command.
Execution and Tracing Commands
run [_a_r_g_s] [< _f_i_l_e_n_a_m_e] [> _f_i_l_e_n_a_m_e]
rerun [_a_r_g_s] [< _f_i_l_e_n_a_m_e] [> _f_i_l_e_n_a_m_e]
Start executing _o_b_j_f_i_l_e, passing _a_r_g_s as command line
arguments; < or > can be used to redirect input or out-
put in the usual manner. When rerun is used without
any arguments the previous argument list is passed to
the program; otherwise it is identical to run. If
_o_b_j_f_i_l_e has been written since the last time the sym-
bolic information was read in, _d_b_x will read in the new
information.
trace [in _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n] [if _c_o_n_d_i_t_i_o_n]
trace _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [if _c_o_n_d_i_t_i_o_n]
trace _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n [in _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n] [if _c_o_n_d_i_t_i_o_n]
trace _e_x_p_r_e_s_s_i_o_n at _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [if _c_o_n_d_i_t_i_o_n]
trace _v_a_r_i_a_b_l_e [in _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n] [if _c_o_n_d_i_t_i_o_n]
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 com-
mand).
The first argument describes what is to be traced. If
it is a _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r, then the line is printed
immediately prior to being executed. Source line
numbers in a file other than the current one must be
preceded by the name of the file in quotes and a colon,
e.g. "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
then the value it is returning is also printed.
If the argument is an _e_x_p_r_e_s_s_i_o_n with an at clause then
the value of the expression is printed whenever the
identified source line is reached.
If the argument is a variable then the name and value
of the variable is printed whenever it changes. Execu-
tion is substantially slower during this form of trac-
ing.
Printed 12/27/86 January 12, 1986 2
DBX(1) UNIX Programmer's Manual DBX(1)
If no argument is specified then all source lines are
printed before they are executed. Execution is sub-
stantially slower during this form of tracing.
The clause ``in _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n'' restricts tracing
information to be printed only while executing inside
the given procedure or function.
_C_o_n_d_i_t_i_o_n is a boolean expression and is evaluated
prior to printing the tracing information; if it is
false then the information is not printed.
stop if _c_o_n_d_i_t_i_o_n
stop at _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [if _c_o_n_d_i_t_i_o_n]
stop in _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n [if _c_o_n_d_i_t_i_o_n]
stop _v_a_r_i_a_b_l_e [if _c_o_n_d_i_t_i_o_n]
Stop execution when the given line is reached, pro-
cedure or function called, variable changed, or condi-
tion true.
status [> _f_i_l_e_n_a_m_e]
Print out the currently active trace and stop commands.
delete _c_o_m_m_a_n_d-_n_u_m_b_e_r ...
The traces or stops corresponding to the given numbers
are removed. The numbers associated with traces and
stops are printed by the status command.
catch _n_u_m_b_e_r
catch _s_i_g_n_a_l-_n_a_m_e
ignore _n_u_m_b_e_r
ignore _s_i_g_n_a_l-_n_a_m_e
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. A signal
may be specified by number or by a name (e.g., SIGINT).
Signal names are case insensitive and the ``SIG'' pre-
fix is optional. By default all signals are trapped
except SIGCONT, SIGCHILD, SIGALRM and SIGKILL.
cont _i_n_t_e_g_e_r
cont _s_i_g_n_a_l-_n_a_m_e
Continue execution from where it stopped. If a signal
is specified, the process continues as though it
received the signal. Otherwise, the process is contin-
ued as though it had not been stopped.
Execution cannot be continued if the process has ``fin-
ished'', that is, called the standard procedure ``exit''.
_D_b_x does not allow the process to exit, thereby letting the
user to examine the program state.
Printed 12/27/86 January 12, 1986 3
DBX(1) UNIX Programmer's Manual DBX(1)
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 will
stop at the beginning of that block, while the next
command will not.
return [_p_r_o_c_e_d_u_r_e]
Continue until a return to _p_r_o_c_e_d_u_r_e is executed, or
until the current procedure returns if none is speci-
fied.
call _p_r_o_c_e_d_u_r_e(_p_a_r_a_m_e_t_e_r_s)
Execute the object code associated with the named pro-
cedure 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 _q_u_a_l_i_f_i_e_d _n_a_m_e]'' is
printed. The name resolution procedure may be overridden by
qualifying an identifier with a block name, e.g.,
``_m_o_d_u_l_e._v_a_r_i_a_b_l_e''. For C, source files are treated as
modules named by the file name without ``.c''.
Expressions are specified with an approximately common sub-
set 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).
Types of expressions are checked; the type of an expression
may be overridden by using ``_t_y_p_e-_n_a_m_e(_e_x_p_r_e_s_s_i_o_n)''. When
there is no corresponding named type the special constructs
``&_t_y_p_e-_n_a_m_e'' and ``$$_t_a_g-_n_a_m_e'' can be used to represent a
pointer to a named type or C structure tag.
assign _v_a_r_i_a_b_l_e = _e_x_p_r_e_s_s_i_o_n
Assign the value of the expression to the variable.
dump [_p_r_o_c_e_d_u_r_e] [> _f_i_l_e_n_a_m_e]
Print the names and values of variables in the given
procedure, or the current one if none is specified. If
Printed 12/27/86 January 12, 1986 4
DBX(1) UNIX Programmer's Manual DBX(1)
the procedure given is ``.'', then the all active vari-
ables are dumped.
print _e_x_p_r_e_s_s_i_o_n [, _e_x_p_r_e_s_s_i_o_n ...]
Print out the values of the expressions.
whatis _n_a_m_e
Print the declaration of the given name, which may be
qualified with block names as above.
which _i_d_e_n_t_i_f_i_e_r
Print the full qualification of the given identifer,
i.e. the outer blocks that the identifier is associ-
ated with.
up [_c_o_u_n_t]
down [_c_o_u_n_t]
Move the current function, which is used for resolving
names, up or down the stack _c_o_u_n_t levels. The default
_c_o_u_n_t is 1.
where
Print out a list of the active procedures and function.
whereis _i_d_e_n_t_i_f_i_e_r
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
/_r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n[/]
?_r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n[?]
Search forward or backward in the current source file
for the given pattern.
edit [_f_i_l_e_n_a_m_e]
edit _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n-_n_a_m_e
Invoke an editor on _f_i_l_e_n_a_m_e or the current source file
if none is specified. If a _p_r_o_c_e_d_u_r_e or _f_u_n_c_t_i_o_n name
is specified, the editor is invoked on the file that
contains it. Which editor is invoked by default
depends on the installation. The default can be over-
ridden by setting the environment variable EDITOR to
the name of the desired editor.
file [_f_i_l_e_n_a_m_e]
Change the current source file name to _f_i_l_e_n_a_m_e. If
none is specified then the current source file name is
printed.
Printed 12/27/86 January 12, 1986 5
DBX(1) UNIX Programmer's Manual DBX(1)
func [_p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n]
Change the current function. If none is specified then
print the current function. Changing the current func-
tion implicitly changes the current source file to the
one that contains the function; it also changes the
current scope used for name resolution.
list [_s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [, _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r]]
list _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n
List the lines in the current source file from the
first line number to the second inclusive. If no lines
are specified, the next 10 lines are listed. If the
name of a procedure or function is given lines _n-_k to
_n+_k are listed where _n is the first statement in the
procedure or function and _k is small.
use _d_i_r_e_c_t_o_r_y-_l_i_s_t
Set the list of directories to be searched when looking
for source files.
Command Aliases and Variables
alias _n_a_m_e _n_a_m_e
alias _n_a_m_e ``_s_t_r_i_n_g''
alias _n_a_m_e (_p_a_r_a_m_e_t_e_r_s) ``_s_t_r_i_n_g''
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, then dbx treats the input as though
the corresponding string (with values substituted for
any parameters) had been entered. For example, to
define an alias ``rr'' for the command ``rerun'', one
can say
alias rr rerun
To define an alias called ``b'' that sets a stop at a
particular line one can say
alias b(x) ``stop at x''
Subsequently, the command ``b(12)'' will expand to
``stop at 12''.
set _n_a_m_e [= _e_x_p_r_e_s_s_i_o_n]
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:
Printed 12/27/86 January 12, 1986 6
DBX(1) UNIX Programmer's Manual DBX(1)
$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 facility is of particu-
lar use for kernel debugging.
$hexchars
$hexints
$hexoffsets
$hexstrings
When set, dbx prints out out 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 the
list command is given without any parameters.
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 debug-
ging.
$unsafecall
$unsafeassign
When ``$unsafecall'' is set, strict type check-
ing is turned off for arguments to subroutine
or function calls (_e._g. 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 _n_a_m_e
Remove the alias with the given name.
unset _n_a_m_e
Delete the debugger variable associated with _n_a_m_e.
Printed 12/27/86 January 12, 1986 7
DBX(1) UNIX Programmer's Manual DBX(1)
Machine Level Commands
tracei [_a_d_d_r_e_s_s] [if _c_o_n_d]
tracei [_v_a_r_i_a_b_l_e] [at _a_d_d_r_e_s_s] [if _c_o_n_d]
stopi [_a_d_d_r_e_s_s] [if _c_o_n_d]
stopi [at] [_a_d_d_r_e_s_s] [if _c_o_n_d]
Turn on tracing or set a stop using a machine instruc-
tion address.
stepi
nexti
Single step as in step or next, but do a single
instruction rather than source line.
_a_d_d_r_e_s_s ,_a_d_d_r_e_s_s/ [_m_o_d_e]
_a_d_d_r_e_s_s / [_c_o_u_n_t] [_m_o_d_e]
Print the contents of memory starting at the first
_a_d_d_r_e_s_s and continuing up to the second _a_d_d_r_e_s_s or
until _c_o_u_n_t items are printed. If the address is
``.'', the address following the one printed most
recently is used. The _m_o_d_e specifies how memory is to
be printed; if it is omitted the previous mode speci-
fied is used. The initial mode is ``X''. The follow-
ing 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
Symbolic addresses are specified by preceding the name with
an ``&''. Registers are denoted by ``$rN'' where N is the
number of the register. Addresses may be expressions made
up of other addresses and the operators ``+'', ``-'', and
indirection (unary ``*'').
Printed 12/27/86 January 12, 1986 8
DBX(1) UNIX Programmer's Manual DBX(1)
Miscellaneous Commands
gripe
Invoke a mail program to send a message to the person
in charge of _d_b_x.
help Print out a synopsis of _d_b_x commands.
quit Exit _d_b_x.
sh _c_o_m_m_a_n_d-_l_i_n_e
Pass the command line to the shell for execution. The
SHELL environment variable determines which shell is
used.
source _f_i_l_e_n_a_m_e
Read _d_b_x commands from the given _f_i_l_e_n_a_m_e.
FILES
a.out object file
.dbxinit initial commands
SEE ALSO
cc(1), f77(1), pc(1), mod(l)
COMMENTS
_D_b_x suffers from the same ``multiple include'' malady as did
_s_d_b. 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
#include's 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
there is a substantial amount of duplication of symbol
information necessary for inter-module type checking.
Some problems remain with the support for individual
languages. Fortran problems include: inability to assign to
logical, logical*2, complex and double complex variables;
inability to represent parameter constants which 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).
Printed 12/27/86 January 12, 1986 9