DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
-------------------------------------------------------------------------------
dbx, mdbx
PURPOSE
Provides a tool to debug and run programs under the AIX operating System.
SYNTAX
+-------------------------------------------------------------+
dbx, mdbx ---| +--------------------------+ +--------------------------+ |--|
+-| +----------------------+ |---| +------------+ |-+
+-| -c file |-+ +- objfile -| |-+
^| -I dir || +- corefile -+
|| -r ||
|| -x dbx.name ||
|| -X in,out,error,pipe ||
|+----------------------+|
+------------------------+
Note: This command does not have MBCS support.
DESCRIPTION
The dbx command is the debugger for the C Language compiler. The mdbx command
is the debugger for the Extended C Language compilers. The debuggers function
the same, but must be used on the correct files. Unless otherwise specified,
the following information about dbx refers to both debuggers.
Note: AIX assemblers are intended to support the compilers and may not have
the full functionality of other assemblers specifically used for
assembler language programming. Although dbx can disassemble
compiler-generated code properly, it uses the as assembler, so some
restrictions apply to code not generated by a compiler.
The dbx command provides a symbolic debugger to be used with AIX Operating
System C, VS Pascal, and VS FORTRAN programs. With this command, you can
examine object and core files and provide a controlled environment for running
a program. You can set breakpoints at selected statements or run the program
one line at a time. You can debug using symbolic variables and instruct the
dbx command to display them in their correct format.
The objfile is an object (executable) file produced by a compiler. Use the -g
(generate symbolic information) flag when you compile your program to produce
the information the dbx command needs. The symbolic information is stored in
the object file along with the executable code. If you have not compiled the
object file using the -g flag or if it is not executable (because of compiler
Processed November 8, 1990 DBX, MDBX(1,C) 1
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
or loader errors), the symbolic capabilities of the dbx command are severely
limited.
When the dbx command is started, it checks for the file .dbxinit in the user's
current directory. If it cannot find the file there, it checks the user's
$HOME directory. If the file .dbxinit exists, the subcommands in it are run at
the beginning of the debug session. Use an editor to create a .dbxinit file.
If the file core exists in the current directory or a corefile is specified,
you can use the dbx command to examine the state of the program when it
faulted.
When printing variables and expressions, the static scope of the current
function is first used to resolve names. If the name is not defined in the
first scope, the dynamic scope is then used. If static and dynamic searches do
not yield a result, an arbitrary symbol by that name is chosen, and dbx prints
the message "[*.using module.variable]", where module.variable is the name of
an identifier qualified with a block name. You can override the name
resolution procedure by qualifying an identifier with a block name. Source
files are treated as modules named by the file name without the language suffix
(such as the .f suffix on a FORTRAN program, the .p suffix on a Pascal program,
or the .c suffix on a C Language program).
Expressions are specified with a subset of C and Pascal syntax. Indirection
can be denoted by using either a prefix "*" (asterisk) or a postfix "^"
(circumflex). Array expressions are subscripted by "[ ]" (brackets) or "( )"
(parentheses). The field reference operator "." (period) 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 can be overridden
by using type-name (expression). When there is no corresponding named type,
the special construct &type-name can be used to represent a pointer to the
named type and the construct .$$tagname can be used to represent a pointer to
a C language enum, struct, or union tag.
The following operators are valid in expressions:
Algebraic +, -, *, / (floating), div (integral), mod, exp
(exponentiation)
Bitwise |, bitand, xor, ~, <<, >>
Logical or, and, not
Comparison <, >, <=, >=, <> or !=, = or ==
Other sizeof
FLAGS
-c file Runs the dbx commands in the file before reading from standard
input.
Processed November 8, 1990 DBX, MDBX(1,C) 2
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
-I dir Includes dir in the list of directories that are searched for
source files. The default is to look for source files in the
current directory and in the directory where the object file is
located. The search path can also be set with the use
subcommand.
-r Runs the object file immediately. If it ends successfully, exit
the dbx command. Otherwise, enter the debugger and report the
reason for termination.
-x dbxname Name of this dbx executable.
-X in, out, error, pipe
File descriptor for in, out, error, and pipe for an X-window
environment.
Note: Unless the -r flag is specified, the dbx command prompts the user and
waits for a command.
PARAMETERS
Run and Trace Subcommands
call proc (params) Executes the object code associated with the
named procedure or function. You can use the
print proc (params) subcommand to perform the
same function, but with a return code of the
function printed.
catch
catch signum
catch signame
ignore
ignore signum
ignore signame Starts or stops trapping a signal before it is
sent to the program. These subcommands are
useful when a program being debugged handles
signals such as interrupts. A signal may be
specified by number or by a name. Signal
names are case insensitive and the SIG prefix
in names is optional. By default all signals
are trapped except SIGHUP, SIGCLD, SIGALRM,
and SIGKILL.
clear sline Removes all stops at a given source line. The
sline can be either an integer or a file name
string followed by a ":" (colon) and an
integer.
cont
cont signum
cont signame Continues execution from the current stopping
point until the program finishes or another
until break point is encountered. If a signal
is specified, the process continues as though
Processed November 8, 1990 DBX, MDBX(1,C) 3
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
it received the signal. Otherwise, the
process is continued as though it had not been
stopped.
delete num ... Removes the traces and stops corresponding to
the specified numbers. The numbers associated
by the dbx command with a trace or stop can be
displayed with the status subcommand.
delete all Removes all active traces and stops.
goto sline Makes the specified source line the next line
to be executed. The sline must be in the same
function as the current source line. To
override this restriction, set $unsafegoto.
goto "filename":num Makes the source line specified by num in
"filename" the next line to be executed.
next [num] Runs the program up to the next source line.
The difference between this and the step
subcommand 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 executes the call and stops
at the source line following the call. The
next command ignores the breakpoints set in
the called procedure or function. If a number
is specified, that number of next commands is
executed.
print proc (params) Executes the object code associated with the
named procedure or function. You can use call
proc (params) subcommand to perform the same
function, but without a return code of
function called.
return [proc] Continues until a return to proc is executed,
or until the current procedure returns if none
is specified.
run [args] [< infile] [> outfile]
[>> outfile] [2> errfile] [2>> errfile]
[>& outerrfile] [>>& outerrfile]
rerun [args] [< infile] [> outfile]
[>> outfile] [2> errfile] [2>> errfile]
[>& outerrfile] [>>& outerrfile]
Starts running the object file, passing args
as command line arguments. The "<", ">", or
"2>" redirects input, output, or standard
error, respectively. The ">>" appends
redirected output and "2>>" appends redirected
standard error. The ">&" redirects both
output and standard error to the same file.
The ">>&" appends the redirected output and
Processed November 8, 1990 DBX, MDBX(1,C) 4
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
standard error to the same file. When the
rerun command is used without any arguments,
the previous argument list is passed.
skip num Continues execution from the current stopping
point until num+1 breakpoints are encountered
or the program finishes.
status [> file] Displays the currently active trace and stop
commands.
step [num] Runs one source line. If a number is
specified, that number of source lines are
executed.
stop if cond
stop at sline [if cond]
stop in proc [if cond]
stop var [in proc] [if cond] Stops the program when the condition is true,
when the source line number is reached, when
the procedure (or function) is called, or when
the variable is changed. A condition can also
be specified for the source line, procedure,
or variable stops in which case, the program
only stops if the specified condition is true.
You may need to use the qualified name to get
the actual variable stop. Use the whereis
command to display the qualified name.
The debugger associates numbers with each stop
subcommand. Use the status subcommand to
display these numbers. Use the delete or
clear subcommand to turn stopping off.
trace
trace in proc [if cond]
trace sline [if cond]
trace proc [in proc] [if cond]
trace expr at sline [if cond]
trace var [in proc] [if cond] Prints the tracing information for the
specified procedure (or function), source
line, expression, or variable when the program
runs. A condition may be specified. The
debugger associates numbers with each trace
subcommand. Use the status subcommand to
display these numbers. Use the delete
subcommand to turn tracing off.
Subcommands for Examining Program Data
assign var = expr Assigns the value of expr to var.
assign addr = expr Loads the value of expr into memory at
address addr.
case [default]
case [mixed]
case [lower]
Processed November 8, 1990 DBX, MDBX(1,C) 5
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
case [upper] Changes the way in which the debugger
interprets symbols. The default handling of
symbols is based upon the current language.
Symbols are folded to lowercase unless C is
the current language. This command should be
used if a symbol needs to be interpreted in a
way not consistent with the current language.
Entering this command with no parameters
displays the current case mode.
dump [proc] [> file] Displays or puts in a file the names and
values of variables in proc. If the
procedure specified is "." (period), all
active variables are dumped. The default is
the current procedure.
dump module_name Displays the names and values of all
variables in module_name.
print expr [,expr...] Displays the values of the expressions.
whatis name Prints the declaration of name, where name is
a variable, procedure, or function name. In
the case of multiple symbol occurrences, full
qualifiers may be necessary.
where [> file] Displays a list of the active procedures and
functions.
whereis identifier Prints the full qualification of all the
symbols whose name matches identifier. The
order in which the symbols are printed is not
significant.
which identifier Prints the full qualification of identifier
(the outer blocks with which the identifier
is associated).
up [count]
down [count] Moves the current function, which is used for
resolving names, up or down the stack count
levels. The default is 1.
Subcommands for Accessing Source Files
/regular expression[/] Searches forward in the current source file for
the specified pattern.
?regular expression[?] Searches backward in the current source file for
the specified pattern.
edit [file]
edit proc Invokes an editor with file or the current source
file if none is specified. If a procedure (or
function) proc is specified, the editor is invoked
on the file that contains it. The default editor
is vi. The default can be overridden by resetting
the environment variable EDITOR to the name of the
desired editor.
Processed November 8, 1990 DBX, MDBX(1,C) 6
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
Note: If the procedure has the same name as any
other file in the same directory, the
editor invokes the other file, not the file
that contains the procedure.
file [file] Changes the current source file to file. If none
is specified, prints the name of the current
source file.
func [proc] Changes the current function to the specified
procedure or function. If none is specified,
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 [proc] If the name of a procedure or function is given,
lists lines f-n to f+m where f is the first
statement in the procedure or function, n is a
small number, and m is the number of lines
remaining that fit in the default list window.
Use set $listwindow=value to set or change the
number of lines displayed in the list window.
list [sline [, sline]] Lists the source lines in the current source file
from the first line number to the second
inclusive. If no lines are specified, lists the
next 10 lines or $listwindow lines. An sline of
"$" specifies the current line of execution. An
sline of "@" specifies the next line to be listed.
Each source line can also be specified as
sline+num or sline-num.
move sline Changes the next line to be displayed to sline.
listi [proc] Lists instructions from the specified procedure or
function. The number of instructions displayed is
controlled by the $listwindow value.
listi at sline Lists instructions beginning with the source line
specified.
listi [address [, address]] Lists instructions from the first address to the
second address inclusive. If no lines are
specified, the next $listwindow instructions are
listed.
use dir [dir ...] Sets the list of directories to be searched when
looking for source files.
Processed November 8, 1990 DBX, MDBX(1,C) 7
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
Machine Level Subcommands
address,address/[mode][>file]
address/[count][mode][>file]
Prints the contents of memory starting at the first address
and continuing up to the second address or until count
items are printed. If address is "." (period), the address
following the one printed most recently is used. The mode
specifies how memory is to be printed; if it is omitted,
the previous mode specified is used. The initial mode is
X. The following modes are supported:
b Prints a byte in octal.
c Prints a byte as a character.
d Prints a short word in decimal.
D Prints a long word in decimal.
f Prints a single-precision real number.
g Prints a double-precision real number.
h Prints a byte in hexadecimal.
i Prints the machine instruction.
o Prints a short word in octal.
O Prints a long word in octal.
s Prints a string of characters terminated by a null byte.
x Prints a short word in hexadecimal.
X Prints a long word in hexadecimal.
Symbolic addresses are specified by preceding the name with
an "&". Addresses can be expressions made up of other
addresses and the operators "+", "-", and "*"
(indirection). Also, any expression enclosed in
parentheses is interpreted as an address.
cleari addr Removes all breakpoints at a specified address.
gotoi addr Changes the program counter to addr.
registers [>file] Displays the values of all general-purpose registers,
system-control registers, floating-point registers, and the
current instruction register. General-purpose registers
are denoted by $name, where name is the extended register
name. Floating point registers are denoted by $frn.
stepi [num]
nexti [num] Runs a single step as in step or next, but runs a single
instruction rather than source line. If num is specified,
a single step is run that number of times.
Processed November 8, 1990 DBX, MDBX(1,C) 8
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
tracei [ addr | var ][if cond]
stopi [addr | var ][if cond]
Traces or sets a stop when the contents of addr change.
tracei [at addr][if cond]
stopi at addr [if cond]
Turns on tracing or sets a stop at a machine instruction
address.
stopi if cond [at addr]
Turns on tracing or sets a stop if cond is true.
Subcommand Aliases and Variables
alias Displays aliases for subcommands.
alias name name
alias name "string"
alias name (params) "string" When subcommands are processed, the dbx command
first checks to see if the word is an alias for
either a subcommand or a string. If it is an
alias, the dbx command treats the input as though
the corresponding string (with values substituted
for any parameters) had been entered.
set var [= expr] The set subcommand defines a value (expression)
for a debugger variable. The name of the
variable cannot conflict with names in the
program being debugged. A variable is expanded
to the corresponding expression within other
commands. The following variables have a special
meaning:
$frame [=address ]
Setting this variable to
address causes dbx to use the
stack frame pointed to by
address for doing stack traces
and accessing local variables.
This facility is of particular
use for kernel debugging.
$expandunions Setting this variable causes
the dbx command to display
values of each part of unions
or variant records.
Processed November 8, 1990 DBX, MDBX(1,C) 9
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
$hexchars
$hexints
$hexstrings When set, the dbx command
prints characters, integers, or
character pointers,
respectively, in hexadecimal.
$hexin When set, the dbx command
interprets integers as
hexadecimal.
$listwindow[=n ] The value of this variable
specifies the number of lines,
n, 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 the dbx command
to start (stop) mapping
addresses. As with $frame,
this variable is useful for
kernel debugging.
$octin When set, the dbx command
interprets integers as octal.
$octints When set, the dbx command
displays integers in octal.
$noargs When set, the dbx command omits
the arguments from commands
that walk the stack (where, up,
down, dump).
$noflargs When set, the dbx command does
not display floating-point
registers from the registers
command.
Note: The following variables should be used
only with great care because they severely
limit the usefulness of the dbx command
for detecting errors.
Processed November 8, 1990 DBX, MDBX(1,C) 10
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
$unsafeassign When $unsafeassign is set,
strict type checking between the
two sides of an assign statement
is turned off.
$unsafebounds When set, subscript checking on
arrays is disabled.
$unsafecall When $unsafecall is set, strict
type checking is turned off for
arguments to subroutine or
function calls.
$unsafegoto When set, goto destination
checking is disabled.
unalias name Removes the alias with the given name.
unset name Deletes the debugger variable associated with
name.
Vector Subcommands (mdbx Only)
vregisters [<vreg number>] Prints the contents of all vector registers or the
register designated by <vreg number>. The format
of the display is controlled by internal debugger
variables, as follows:
o If the $intvectors variable is set, the
contents of the vector elements are displayed
as integers.
o If the $doublevectors variable is set, the
contents of the vector elements are displayed
as double-precision floating point numbers.
When specifying vregisters with a single
register, the <vreg number> parameter must be
even.
These debugger variables are mutually exclusive.
If one is set, the other is automatically cleared.
vstate Prints the contents of the vector status register,
vector mask register, and vector activity-count
register.
Debugger Variables (mdbx Only)
The variables below are special variables known to the debugger. They may be
displayed with the print subcommand or modified with the assign subcommand.
vrN References vector register N (where 0 <= N <= 31) as an integer.
The reference must be further qualified to specify a particular
component of the register. For example, "$vr5[13]" references the
Processed November 8, 1990 DBX, MDBX(1,C) 11
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
fourteenth word of the sixth vector register (vector registers and
components within registers are numbered starting with 0).
$vfrN References vector register N (where 0 <= N <= 31) as a
single-precision floating point number. A particular component
within the register must be specified.
$vdrN References vector register N (where 0 <= N <= 30, even) as a
double-precision floating point number. A particular component
within the register must be specified.
$vstatus References the vector status register. The display appears as two
32-bit words in hexadecimal format. The two halves of the register
can be referenced separately using the subscript notation.
$vac References the vector activity-count register. The display appears
as two 32-bit words in hexadecimal format. The two halves of the
register can be referenced separately using the subscript notation.
$vmask References the vector mask register. The display appears as a
number of 32-bit words displayed in hexadecimal format. Individual
words can be referenced separately using the subscript notation.
The number of words displayed depends on the current section size.
For example, if the section size is 128, four 32-bit words are
displayed to show 128 bits, one bit per vector element.
vcount Displays the vector count field of the vector status register in
decimal. The field is a 16-bit unsigned binary integer.
$vmaskflag Displays the vector mask mode bit of the vector status register.
$vstate Controls whether status information from the vector processor is
displayed as part of the output of the registers subcommand. If
$vstate is set, the contents of the vector status register, the
vector activity-count register, and the vector mask register (in
addition to the normal output of the registers command) is
displayed in hexadecimal. (The registers subcommand should not be
confused with the vregistsers subcommand, which applies strictly to
the vector processor. The registers subcommand displays the values
of general purpose registers and system control registers.)
Other Useful Subcommands
help Prints a synopsis of common dbx commands.
prompt [string] Changes the dbx command prompt to string. Without the
string argument, the prompt subcommand displays the
current prompt.
quit Quits the dbx command.
Processed November 8, 1990 DBX, MDBX(1,C) 12
DBX, MDBX(1,C) AIX Commands Reference DBX, MDBX(1,C)
screen Opens a virtual terminal for dbx command interaction. The
user continues to operate in the window in which the
process originated. Also, the user must be using a
console that supports virtual terminals.
sh command Passes the command line to the shell for execution. The
SHELL environment variable determines which shell is used.
source file Reads dbx commands from the given file.
FILES
a.out Contains object code; object file.
core Contains core dump information.
.dbxinit Contains initial commands.
RELATED INFORMATION
See the following command: "cc."
See the a.out and core files in AIX Operating System Technical Reference.
See "Debugging Programs" in AIX Operating System Programming Tools and
Interfaces.
See the compiler chapters in AIX Operating System VS FORTRAN, VS Pascal and C
User's Guides.
Processed November 8, 1990 DBX, MDBX(1,C) 13