dbx(1)dbx(1)Namedbx - debugger
Syntaxdbx [-r] [-i] [-k] [-I dir] [-c file] [objfile[coredump]]
Description
The debugger is a tool for source level debugging and execution of pro‐
grams running under the ULTRIX operating system. Once you invoke you
can issue commands that control and trace program execution, print
variable and expression values, and display and edit source files.
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 objfile 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 an option, -g , that produces the symbol table information in the
object file.
The extended symbol table contains information that makes your debug‐
ging session more convenient. For example, the extended symbol table
contains the names 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.
If your object file does not contain the extended symbol table, use the
commands described in Machine Level Commands to debug your program.
If you omit the objfile 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, issues another prompt to
allow you to enter a file name. If you press the Return key, exits.
The coredump argument names a core dump file. You can examine the core
dump file to determine the state of your program. If you omit coredump
and a core file exists in the current directory, reads in a file named
Initialization File
During its startup, reads and executes the commands in an initializa‐
tion 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 initializa‐
tion file to automatically issue setup commands when you begin a ses‐
sion.
You can rename the debugger. If you rename the debugger, you must also
rename its initialization file. The debugger expects the initialization
file's name to be a period (.), followed by the first eight characters
in the debugger's name, followed by the string For example, if you
rename to the debugger searches for an initialization file named
Options-cfile Executes the commands in the specified file before reading from
standard input.
-i Forces to act as though standard input is a terminal.
-Idir Adds the specified directory to the list of directories that
searches for source files. Normally, searches for source files
in the current directory and in the directory where objfile is
located. You can also issue the command to set the directory
search path.
-k Maps memory addresses. This option is useful for kernel debug‐
ging.
-r Executes objfile immediately. If the program executes success‐
fully, exits. 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 stan‐
dard input is not a terminal.
Execution and Tracing Commands
Using commands, you can execute your program under control of the
debugger. You can trace its execution and control whether your program
traps certain signals. The following list describes the commands that
allow you to execute and trace your program:
call procedure[(parameters)]
Executes the object code associated with the named procedure or
function and passes any parameters you specify to the procedure.
catch integer
catch signal-name
ignore integer
ignore signal-name
Starts or stops trapping a signal before it is sent to the pro‐
gram. These commands are useful when you are debugging a pro‐
gram that 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, traps all signals except SIGCONT,
SIGCHILD, SIGALRM, and SIGKILL.
cont [integer]
cont [signal-name]
Continues execution from where it stopped. If you specify a
signal name or number, the process continues as though it
received the signal. If you omit the signal name or number,
program execution continues as if a signal had not been encoun‐
tered. For information about signal names and numbers, see
Execution cannot be continued if the process has called the
standard exit procedure. The debugger does not allow the
process to exit, so you can examine the program state.
delete command-number ...
delete all
Removes the trace or stop event that corresponds to the speci‐
fied number or removes all traces and stops. Trace and stop
event numbers are assigned by You can display them using the
status command.
The command delete all removes all existing traces and stops at
once. The command delete * has the same effect.
next Executes 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 exe‐
cution stops following the return from the procedure; that is,
execution stops prior to the source line that follows the call.
reread Reads the object file before beginning program execution. The
debugger reads the object file directly before executing the
program in response to a run or rerun command. Reading the
object file directly before executing the program ensures that
the execution is unaffected by any corruption that might have
occurred during a previous run.
return [procedure]
Executes until a return to procedure is executed or until the
current procedure returns if none is specified.
run [args] [< filename] [> filename]
rerun [args] [< filename] [> filename]
Starts executing objfile, passing args as command line argu‐
ments. You can use angle brackets (< or >) to redirect input or
output in the usual manner. If you issue the rerun command
without any arguments, passes the previous argument list to the
program. Otherwise, the rerun command is identical to run. If
you recompiled your program since the last time read symbolic
information, it reads in the new information.
status [> filename]
Displays the currently active trace and stop events.
step 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.
stop if condition
stop at source-line-number [if condition]
stop in procedure/function [if condition]
stop variable [if condition]
Stops execution when the specified condition is true, the speci‐
fied line number is reached, the specified procedure or function
is called, or the specified variable changes value.
If you specify a condition with the source-line-number, proce‐
dure/function, or variable argument, execution stops only when
the condition is true. For example, suppose you specified that
execution should stop at line 14 if variable a is greater in
value than variable b. The debugger continues execution if vari‐
able a equals variable b when it reaches line 14.
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]
Displays tracing information during program execution. The
debugger associates a number with the source line that contains
the trace. You use the number to turn off tracing, as described
with the delete command.
The first argument to the trace command describes what is to be
traced. You can specify a procedure or function name, a source
line number, an expression, or a variable name.
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.
If you specify the in procedure/function clause, displays trac‐
ing information only while executing the specified procedure or
function.
If you specify 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, as shown:
(dbx) trace "source_file.c":17
The example specifies tracing line 17 in
If you specify an expression at a source line number, displays
the value of the expression when it executes the source line.
Specifying a variable name causes to display the name and value
of the variable each time it changes. Program execution is sub‐
stantially slower during this form of tracing.
The condition argument is a Boolean expression that evaluates
prior to displaying any tracing information; if the condition is
false, does not display the information.
If you omit the arguments to the trace command, displays each
source line before executing it. Program execution is substan‐
tially slower during this form of tracing.
Printing Variables and Expressions
The debugger allows you to display the value of your program's vari‐
ables and expressions. This section describes how the debugger
resolves ambiguous names, how you specify expressions, and the commands
that you use to display the value of variables and expressions.
The debugger resolves names by first searching for the name in the
static scope of the current procedure or 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 arbi‐
trary symbol and displays 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 identi‐
fiers with a block name, as in module.variable. For the C language,
the debugger treats a source file as a module named for the filename
without the suffix.
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, the debugger 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 refer‐
ence operator (.) with pointers as well as records or structures, mak‐
ing the C operator (->) unnecessary (although it is supported). To
specify a hexadecimal value, precede the value with the "0x" charac‐
ters.
You must enclose array expressions in brackets ([ ]).
The debugger checks the type of each expression; you can override the
type of an expression by using (expression)\type-name.
You can also specify a register name in an expression. You denote reg‐
isters by $rN where N is the number of the register. You denote vector
registers as follows:
$vN[K] Denotes a vector data register where N is the register number
and K is an index. The debugger treats each data register as a
double-precision floating point array of 64 elements, indexed
from 0 to 63.
$vaer Denotes the vector arithmetic error register, which treats as a
longword.
$vcr Denotes the longword vector count register.
$vlr Denotes the longword vector length register
$vmr Denotes the vector mask register. The debugger treats the $vmr
as a Boolean array of 64 elements, indexed from 0 to 63.
For more information about VAX registers, see the VAX Architecture Man‐
ual.
The following list describes the debugger commands for printing vari‐
ables and expressions:
assign variable = expression
assign vector-register = "value [,value]"
Assigns the value of the expression to the variable or stores
the specified value in the specified vector register.
The assign command allows you to assign a value to one element
of a vector register. (You cannot use the command to assign a
value to a nonvector register.) You can change only one element
in a register in a single command. If you omit the second value,
decodes the first value into the first half of the register. If
you specify both values, the debugger decodes the first value
into the first half of the register and the second value into
the second half of the register.
The value can be an integer, floating point, or hexadecimal
value.
dump [procedure] [> filename]
Displays the names and values of variables in the given proce‐
dure or the current one if none is specified. If you specify
the dot (.), the debugger prints the values of all active vari‐
ables.
print expression [, expression ...]
Displays the values of the specified expressions.
whatis name
Displays the declaration of the given name, which you can qual‐
ify using a block name.
up [count]
down [count]
Moves the current procedure or function, which is used for
resolving names, up or down the stack count levels. The default
for count is 1.
where Displays a list of the active procedures and functions.
whereis identifier
Displays the full qualification of all the symbols whose name
matches the given identifier. The order in which displays the
symbols is not meaningful.
which identifier
Displays the full qualification of the given identifier; that
is, display the outer blocks that are associated with the iden‐
tifier.
Accessing Source Files
You can use the following commands to access source files during a
debugging session:
/regular expression[/]
?regular expression[?]
Searches forward or backward in the current source file for the
given pattern. For information on specifying a regular expres‐
sion, see The Big Gray Book: The Next Step with ULTRIX.
cd [dirname]
Changes the current directory to the directory you specify. If
you omit the dirname argument, uses the directory specified in
the HOME environment variable as the current directory.
edit [filename]
edit procedure/function
Invokes an editor on filename or the current source file if none
is specified. If you specify a procedure or function name, the
editor reads in the file that contains that procedure or func‐
tion. Which editor is invoked by default depends on the instal‐
lation. You can override the default setting by modifying the
EDITOR environment variable.
file [filename]
Changes the current source file name to filename. If you omit
filename, displays the name of the current source file.
func [procedure/function]
Changes the current procedure or function. If you omit proce‐
dure/function, displays the current procedure or function.
Changing the current procedure or 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 [, source-line-number]]
list [source-line-number : integer]
list [procedure/function]
Lists the lines in the current source file from the first line
number you specify to the second one you specify, inclusive. If
you omit the second source-line-number argument, begins at the
first line number and displays the next 10 lines. If you omit
both arguments, begins the display at the current source line
and displays 10 lines.
If you specify a source line number, a colon, and an integer,
lists lines in the current source file starting from source-
line-number and continuing for integer number of lines.
If you specify the name of a procedure or function, lines n-k to
n+k are listed, where n is the first statement in the procedure
or function and k is equal to the $listwindow variable. The
default value of $listwindow is 10.
pwd Displays the pathname of the current directory.
use pathname pathname...
Sets the list of directories that searches when looking for
source files. You can specify either a full or relative pathname
for pathname.
Command Aliases and Variables
The debugger allows you to define aliases and set variables to make
your debugging sessions more efficient. The following list describes
the commands you use to perform these tasks:
alias name command
alias name [(parameters)] string
Lists existing aliases or defines an alias for a command or a
string. Specify the alias name in the name argument and the com‐
mand or string in the command or string argument. You can define
an alias that accepts parameters by specifying the parameters
argument. For example, to define an alias rr for the command
rerun, enter the following command:
(dbx) alias rr rerun
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
as equivalent:
(dbx) halt(12)
(dbx) stop at 12
Both commands create a stop event at line 12.
getenv name
Displays the value of the environment variable, name.
setenv name value
Sets the environment variable name to value by changing the
value of an existing environment variable or creating a new one.
set [name [= expression]]
Lists existing debugger variables and their values or defines a
value for the named 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, the vari‐
able causes the debugger to display strings in character format.
You can set a variable like the $hexstrings variable to a
nonzero value as shown:
(dbx) set $hexstrings
You can disable the variable using the unset command, as shown:
(dbx) unset $hexstrings
You can use the set command to create variables using a name of
your own. Variables you create must not begin with a dollar sign
($), and the name of the variable must not conflict with names
in the program you are debugging. When you create a variable,
the set command treats expression as an address and creates a
variable at the specified address. You can use the variable name
in trace and stop commands to control program execution.
The following list describes the debugger variables:
$frame If you set this variable to an address, uses the stack
frame at that address for stack traces and for accessing
local variables. This variable is particularly useful
for kernel debugging.
$hexchars
$hexints
$hexoffsets
$hexstrings
You can set these variables to cause to display character
strings, integers, offsets from registers, or character
pointers, respectively, in hexadecimal format.
$historywindow
The value of this variable determines the number of com‐
mands stores in the history list. By default, the his‐
tory list contains 20 commands.
$listwindow
The value of this variable determines the number of lines
lists around a procedure or function or displays when you
issue the list command without arguments. The default
value for this variable is 10.
$mapaddrs
Setting (unsetting) this variable causes to start (stop)
mapping addresses. This variable is useful for kernel
debugging.
$unsafecall
$unsafeassign
If you set one of these variables, does not perform
strict type checking. When the $unsafecall variable is
set, strict type checking is turned off for arguments to
procedure or function calls (for example, in the call
command). When the $unsafeassign variable is set, strict
type checking between the two sides of an assign command
is turned off. Use these variables with care, because
they severely limit the debugger's usefulness for detect‐
ing errors.
unalias name
Removes the alias with the specified name.
unset name
Deletes the debugger variable associated with the name you
specify.
Vector Environment Commands
The debugger provides some special commands that you can use to debug a
program that uses vectors. The following list explains these commands:
callv procedure/function[(parameters)]
Executes the object code associated with the named procedure or
function. The callv command causes to save the vector environ‐
ment before it executes the procedure. The debugger restores the
vector environment after the procedure exits.
fmask[/"hex constant"] vector_register
tmask[/"hex constant"] vector_register
Displays the contents of the specified vector data register
using the vector mask register ($vmr) or the hexadecimal con‐
stant you specify as a mask value. Replace vector_register with
the name of a vector register to specify which vector data reg‐
ister the debugger displays.
The fmask command causes the debugger to apply a false mask to
the register value. The tmask command causes the debugger to
apply a true mask to the register value.
nextv Executes to the next vector instruction at the current or higher
procedure level. The debugger ignores vector instructions at
lower procedure levels when executing this command. Thus, execu‐
tion continues through lower level procedures, but stops prior
to the next instruction at the current or higher procedure
level.
stepv Executes the next vector instruction. The debugger stops execu‐
tion prior to the next vector instruction regardless of the pro‐
cedure level of that instruction.
Machine Level Commands
You can use machine level commands to debug any program, regardless of
whether the program object file contains extended symbol table informa‐
tion.
You can specify symbolic addresses by preceding the name with an amper‐
sand (&). You denote registers by $rN where N is the number of the
register. You denote vector registers by $vN 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 , address/ [mode]
address / [count] [mode]
at source-line-number / [count] [mode]
Display the contents of memory starting at the first address and
continuing up to the second address.
The second form causes to display the contents of memory start‐
ing at address and continuing until count items are displayed.
If you type a period (.) in the address field, uses the address
following the one it most recently displayed.
If you specify at source-line-number, displays the contents of
memory associated with the specified source line. You can spec‐
ify how many items the debugger displays using the count argu‐
ment.
The mode on each format specifies 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 the machine instruction
o Displays a short word in octal
O Displays a long word in octal
s Displays a string of characters terminated by a null byte
x Displays a short word in hexadecimal
X Displays a long word in hexadecimal
nexti Executes 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 func‐
tion. 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.
stepi Executes one machine instruction. If the machine instruction
contains a call to a procedure or function, the debugger stops
at the first line of the procedure or function.
stopi [at] [address] [if condition]
Stops at the specified machine address or when the specified
condition is met. If you specify both address and condition, the
debugger stops at the specified address only when the specified
condition is true.
tracei [address] [if condition]
tracei [variable] [at address] [if condition]
Displays tracing information during program execution. The first
argument specifies an address at which tracing begins or the
name of a variable to trace.
If you specify tracing a variable at a specific address, dis‐
plays the value of that variable when it reaches the address you
specify.
The condition argument is a Boolean expression that evaluates
prior to displaying any tracing information. If the condition is
false, does not display the information.
Miscellaneous Commands
Use the following to get help about exit from the debugger, issue shell
commands, and read commands from a file:
!string
!integer
Executes a command from the history list. You can specify the
command name in the string argument. If you specify an integer,
executes the command having that number in the history list. For
example, the following executes the third command in the history
list:
dbx> !3
reread
The debugger echoes the command before execution.
help Displays a synopsis of commands.
hi[story]
Displays a list of the previous commands you issued. By default,
displays the previous 20 commands. You can change the number of
commands keeps in the history list by modifying the $historywin‐
dow debugger variable. (For information on changing debugger
variables, see Command Aliases And Variables.)
printf format, arg1, arg2,...
Formats a complex structure for display as specified. You use
the same format characters for this command as for the subrou‐
tine. For information on specifying the format, see
quit Exits from
record input [filename]
Records all commands you enter at the prompt. The debugger
stores the commands in the specified file. You can replay the
commands by naming the file on the source command line.
If you omit filename, the debugger terminates the existing
recording session. If recording is not active, ignores the com‐
mand.
sh command-line
Passes the command line to the shell for execution. The SHELL
environment variable determines which shell is used.
source filename
Reads commands from the specified file.
Restrictions
If you have a program consisting of several object files and each is
built from source files that include header files, the symbolic infor‐
mation for the header files is reproduced in each object code file.
Since one debugger startup usually is done for each link, having the
linker reorganize the symbol information will not save much time,
although it will reduce some of the disk space used.
This problem results from the unrestricted semantics of statements in
C. For example, an include file can contain static declarations that
are separate entities for each file in which they are included. If
your image is too large for to run, compile with the -g option only
those files that you are interested in debugging. However, even with
Modula-2, there is a substantial amount of duplication of symbol infor‐
mation necessary for inter-module type checking.
The following restrictions apply to debugging FORTRAN programs:
· Inability to assign values to logical*2, complex, and double com‐
plex variables.
· Inability to represent parameter constants that are not type inte‐
ger or real.
· Peculiar representations of 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
an ampersand (&) to use the address of the variable.)
The debugger does not allow you to run a program you do not own unless
you are root. If you are not root, the following message might be dis‐
played on your screen when you issue the command:
can't-write-to-process
This message is displayed when the debugger tries to set breakpoints
because of restrictions on the system call. The debugger always tries
set a breakpoint on exit. If you repeat the command, your program runs
without breakpoints.
The printf debugger command does not support the conversion specifica‐
tion.
If you press Ctrl/C while inside the system call, a breakpoint is set.
When the command is entered, tries to continue from the breakpoint set
in for which it does not have source. This causes an error condition.
An error condition occurs when the command is used to print variables
with reserved words embedded in them. For example, printing fails
because "in" is a reserved word.
When debugging programs that contain variables beginning with the sym‐
bol becomes confused between register variables that begin with the
symbol and the variables defined in the C program.
The command reports a trace message for an event set using the command.
The command allows debugging of system files such as
When the command is applied against a pascal program, ignores the trace
even though a command displays a trace point has been set.
The current version of is not able to perform a (change directory)
function from within.
Files
Object file
Initialization file
See Alsocc(1), pc(1), ptrace(2), vcc(1), signal(3), printf(3s)
VAX dbx(1)
