Unix Commands - OFS Man Pages
dbx Command
Purpose
Provides an environment to debug and run programs under the operating
system.
Syntax
dbx [ -a ProcessID ] [ -c CommandFile ] [ -d NestingDepth ]
[ -I Directory ] [ -k ] [ -u ] [ -f ] [ -r ] [ -x ]
[ ObjectFile [ CoreFile ] ]
Description
The dbx command provides a symbolic debug program for C, C++, Pascal,
and FORTRAN programs, allowing you to carry out operations such as
the following:
* Examine object and core files.
* Provide a controlled environment for running a program.
* Set breakpoints at selected statements or run the program
one line at a time.
* Debug using symbolic variables and display them in their correct
format.
The ObjectFile parameter is an object (executable) file produced by
a compiler. Use the -g (generate symbol table) flag when compiling
your program to produce the information the dbx command needs.
Note: The -g flag of the cc command should be used when the object
file is compiled. If the -g flag is not used or if symbol references
are removed from the xcoff file with the strip command, the symbolic
capabilities of the dbx command are limited.
If the -c flag is not specified, the dbx command checks for a .dbxinit
file in the user's $HOME directory. It then checks for a .dbxinit
file in the user's current directory. If a .dbxinit file exists in
the current directory, that file overrides the .dbxinit file in the
user's $HOME directory. If a .dbxinit file exists in the user's $HOME
directory or current directory, that file's subcommands run at the
beginning of the debug session. Use an editor to create a .dbxinit
file.
If ObjectFile is not specified, then dbx asks for the name of the
object file to be examined. The default is a.out. If the core file
exists in the current directory or a CoreFile parameter is specified,
then dbx reports the location where the program faulted. Variables,
registers, and memory held in the core image may be examined until
execution of ObjectFile begins. At that point the dbx debug program
prompts for commands.
Expression Handling
The dbx program can display a wide range of expressions. You can specify
expressions in the dbx debug program with a common subset of C and
Pascal syntax, with some FORTRAN extensions.
The following operators are valid in the debug program:
* (asterisk) or ^ (caret) Denotes indirection or pointer dereferencing.
[ ] (brackets) or ( ) (parentheses) Denotes subscript array expressions.
. (period) Use this field reference operator with pointers and structures.
This makes the C operator -> (arrow) unnecessary, although it is
allowed.
& (ampersand) Gets the address of a variable.
.. (two periods) Separates the upper and lower bounds when specifying
a subsection of an array. For example: n[1..4].
The following types of operations are valid in expressions in the
debug program:
Algebraic =, -, *, / (floating division), div (integral division),
mod, exp (exponentiation)
Bitwise -, I, bitand, xor, ~. <<, >
Logical or, and, not, II, &&
Comparison <, >, <=, >=, < > or !=, = or ==
Other (typename),sizeof
Logical and comparison expressions are allowed as conditions in stop
and trace.
Expression types are checked. You override an expression type by using
a renaming or casting operator. The three forms of type renaming are
Typename(Expression), Expression\ Typename, and (Typename) Expression.
The following is an example where the x variable is an integer with
value 97:
(dbx) print x
97
(dbx) print char (x), x \ char, (char) x, x
'a' 'a' 'a' 97
Flags
-a ProcessID Attaches the debug program to a process that is running.
To attach the debug program, you need authority to use the kill command
on this process. Use the ps command to determine the process ID. If
you have permission, the dbx program interrupts the process, determines
the full name of the object file, reads in the symbolic information,
and prompts for commands.
-c CommandFile Runs the dbx subcommands in the file before reading
from standard input. The specified file in the $HOME directory is
processed first; then the file in the current directory is processed.
The command file in the current directory overrides the command file
in the $HOME directory. If the specified file does not exist in either
the $HOME directory or the current directory, a warning message is
displayed. The source subcommand can be used once the dbx program
is started.
-d NestingDepth Sets the limit for the nesting of program blocks.
The default nesting depth limit is 25.
-f Starts the dbx command in lazy reading mode. Reads only required
symbol table information upon initiation of dbx session. This flag
can be used to speed up dbx startup (especially for debugging large
executables) and to cut down dbx memory usage (useful when page space
is low). In this mode, dbx will not read local variables and types
whose symbolic information has not been read. Therefore, commands
such as whereis i may not list all instances of the local variable
i in every function.
-I Directory (Uppercase i) Includes directory specified by the Directory
variable in the list of directories searched for source files. The
default is to look for source files in the following directories:
* The directory the source file was located in when it was compiled.
This directory is searched only if the compiler placed the source
path in the object.
* The current directory.
* The directory where the program is currently located.
-k Maps memory addresses; this is useful for kernel debugging.
-r Runs the object file immediately. If it terminates successfully,
the dbx debug program is exited. Otherwise, the debug program is entered
and the reason for termination is reported.
Note: Unless -r is specified, the dbx command prompts the user and
waits for a command.
-u Causes the dbx command to prefix file name symbols with an @ (at
sign). This flag reduces the possibility of ambiguous symbol names.
-x Prevents the dbx command from stripping _ (trailing underscore
) characters from symbols originating in FORTRAN source code. This
flag allows dbx to distinguish between symbols which are identical
except for an underscore character, such as xxx and xxx_.
Examples
1. The following example explains how to start the dbx debug program
simultaneously with a process. The example uses a program called samp.c.
This C program is first compiled with the -g flag to produce an object
file that includes symbolic table references. In this case, the program
is named samp:
$ cc -g samp.c -o samp
When the program samp is run, the operating system reports a bus error
and writes a core image to your current working directory as follows:
$ samp
Bus Error - core dumped
To determine the location where the error occurred, enter:
$ dbx samp
The system returns the following message:
dbx version 3.1
Type 'help' for help.
reading symbolic information . . . [
using memory image in core]
25 x[i] = 0;
(dbx) quit
2. This example explains how to attach dbx to a process. This example
uses the following program, looper.c:
main()
{
int i,x[10];
for (i = 0; i < 10;);
}
The program will never terminate because i is never incremented. Compile
looper.c with the -g flag to get symbolic debugging capability:
$ cc -g looper.c -o looper
Run looper from the command line and perform the following steps to
attach dbx to the program while it is running:
a. To attach dbx to looper, you must determine the process ID. If
you did not run looper as a background process, you must have another
Xwindow open. From this Xwindow, enter:
ps -u UserID
where UserID is your login ID. All active processes that belong to
you are displayed as follows:
PID TTY TIME COMMAND
68 console 0:04 sh
467 lft3 10:48 looper
In this example the process ID associated with looper is 467.
b. To attach dbx to looper, enter:
$ dbx -a 467
The system returns the following message:
Waiting to attach to process 467 . . .
Successfully attached to /tmp/looper.
dbx is initializing
Type 'help' for help.
reading symbolic information . . .
attached in main at line 5
5 for (i = 0; i < 10;);
(dbx)
You can now query and debug the process as if it had been originally
started with dbx.
3. To add directories to the list of directories to be searched for
the source file of an executable file objefile, you can enter:
$dbx -I /home/user/src -I /home/group/src objfile
The use subcommand may be used for this function once dbx is started.
The use command resets the list of directories, whereas the -I flag
adds a directory to the list.
4. To use the -r flag, enter:
$ dbx -r samp
The system returns the following message:
Entering debug program . . .
dbx version 3.1
Type 'help' for help.
reading symbolic information . . .
bus error in main at line 25
25 x[i] = 0;
(dbx) quit
The -r flag allows you to examine the state of your process in memory
even though a core image is not taken.
dbx Subcommands
Note: The subcommands can only be used while running the dbx debug
program.
/ Searches forward in the current source file for a pattern.
? Searches backward in the current source file for a pattern.
alias Creates aliases for dbx subcommands.
assign Assigns a value to a variable.
attribute Displays information about all or selected attributes objects.
call Runs the object code associated with the named procedure or function.
case Changes how the dbx debug program interprets symbols.
catch Starts trapping a signal before that signal is sent to the application
program.
clear Removes all stops at a given source line.
cleari Removes all breakpoints at an address.
condition Displays information about all or selected condition variables.
cont Continues application program execution from the current stopping
point until the program finishes or another breakpoint is encountered.
delete Removes the traces and stops corresponding to the specified
event numbers.
detach Continues execution of application and exits the debug program.
display memory Displays the contents of memory.
down Moves the current function down the stack.
dump Displays the names and values of variables in the specified procedure.
edit Starts an editor on the specified file.
file Changes the current source file to the specified file.
func Changes the current function to the specified procedure or function.
goto Causes the specified source line to be the next line run.
gotoi Changes the program counter address.
help Displays help information for dbx subcommands or topics.
ignore Stops trapping a signal before that signal is sent to the application
program.
list Displays lines of the current source file.
listi Lists instructions from the application program.
map Displays information about load characteristics of the application.
move Changes the next line to be displayed.
multproc Enables or disables multiprocess debugging.
mutex Displays information about all or selected mutexes.
next Runs the application program up to the next source line.
nexti Runs the application program up to the next machine instruction.
print Prints the value of an expression or runs a procedure and prints
the return code of that procedure.
prompt Changes the dbx command prompt.
quit Stops the dbx debug program.
registers Displays the values of all general-purpose registers, system-control
registers, floating-point registers, and the current instruction register.
rerun Begins execution of an application with the previous arguments.
return Continues running the application program until a return to
the specified procedure is reached.
run Begins running an application.
screen Opens an Xwindow for dbx command interaction.
set Defines a value for a dbx debug program variable.
sh Passes a command to the shell to be run.
skip Continues running the application program from the current stopping
point.
source Reads dbx subcommands from a file.
status Displays the active trace and stop subcommands.
step Runs one source line.
stepi Runs one machine instruction.
stop Stops running of the application program.
stopi Sets a stop at a specified location.
thread Displays and controls threads.
trace Prints tracing information.
tracei Turns on tracing.
unalias Removes an alias.
unset Deletes a variable.
up Moves the current function up the stack.
use Sets the list of directories to be searched when looking for source
files.
whatis Displays the declaration of application program components.
where Displays a list of active procedures and functions.
whereis Displays the full qualifications of all the symbols whose
names match the specified identifier.
which Displays the full qualification of the given identifier.
/ Subcommand
/ [ RegularExpression [ / ] ]
The / subcommand searches forward in the current source file for the
pattern specified by the RegularExpression parameter. Entering the
/ subcommand with no arguments causes dbx to search forward for the
previous regular expression. The search wraps around the end of the
file.
Examples
1. To search forward in the current source file for the number 12,
enter:
/ 12
2. To repeat the previous search, enter:
/
See the ? (search) subcommand and the regcmp subroutine.
? Subcommand
? [ RegularExpression [ ? ] ]
The ? subcommand searches backward in the current source file for
the pattern specified by the RegularExpression parameter. Entering
the ? subcommand with no arguments causes the dbx command to search
backwards for the previous regular expression. The search wraps around
the end of the file.
Examples
1. To search backward in the current source file for the letter z,
enter:
?z
2. To repeat the previous search, enter:
?
See the / (search) subcommand and the regcmp subroutine.
alias Subcommand
alias [ Name [ [ (Arglist) ] String | Subcommand ] ]
The alias subcommand creates aliases for dbx subcommands. The Name
parameter is the alias being created. The String parameter is a series
of dbx subcommands that, after the execution of this subcommand, can
be referred to by Name. If the alias subcommand is used without parameters,
it displays all current aliases.
Examples
1. To substitute rr for rerun, enter:
alias rr rerun
2. To run the two subcommands print n and step whenever printandstep
is typed at the command line, enter:
alias printandstep "print n; step"
3. The alias subcommand can also be used as a limited macro facility.
For example:
(dbx) alias px(n) "set $hexints; print n; unset $hexints"
(dbx) alias a(x,y) "print symname[x]*symvalue._n_n.name.Id[y]"
(dbx) px(126)
0x7e
In this example, the alias px prints a value in hexadecimal without
permanently affecting the debugging environment.
See Creating dbx Subcommand Aliases.
assign Subcommand
assign Variable=Expression
The assign subcommand assigns the value specified by the Expression
parameter to the variable specified by the Variable parameter.
Examples
1. To assign a value of 5 to the x variable, enter:
assign x = 5
2. To assign the value of the y variable to the x variable, enter:
assign x = y
3. To assign the character value 'z' to the z variable, enter:
assign z = 'z'
4. To assign the boolean value false to the logical type variable
B, enter:
assign B = false
5. To assign the "Hello World" string to a character pointer Y, enter:
assign Y = "Hello World"
6. To disable type checking, set the dbx debug program variable $unsafeassign
by entering:
set $unsafeassign
See Displaying and Modifying Variables.
attribute Subcommand
attribute [ AttributeNumber ... ]
The attribute subcommand displays information about the user thread,
mutex, or condition attributes objects defined by the AttributeNumber
parameters. If no parameters are specified, all attributes objects
are listed.
For each attributes object listed, the following information is displayed:
attr Indicates the symbolic name of the attributes object, in the
form $aAttributeNumber.
obj_addr Indicates the address of the attributes object.
type Indicates the type of the attributes object; this can be thr,
mutex, or cond for user threads, mutexes, and condition variables
respectively.
state Indicates the state of the attributes object. This can be valid
or inval.
stack Indicates the stacksize attribute of a thread attributes object.
scope Indicates the scope attribute of a thread attributes object.
This determines the contention scope of the thread, and defines the
set of threads with which it must contend for processing resources.
The value can be sys or pro for system or process contention scope.
prio Indicates the priority attribute of a thread attributes object.
sched Indicates the schedpolicy attribute of a thread attributes object.
This attribute controls scheduling policy, and can be fifo , rr (round
robin), or other.
p-shar Indicates the process-shared attribute of a mutex or condition
attribute object. A mutex or condition is process-shared if it can
be accessed by threads belonging to different processes. The value
can be yes or no.
protocol Indicates the protocol attribute of a mutex. This attribute
determines the effect of holding the mutex on a thread's priority.
The value can be no_prio, prio, or protect.
Notes:
1. The print subcommand of the dbx debug program recognizes symbolic
attribute names, and can be used to display the status of the corresponding
object.
2. The available attributes depend on the implementation of POSIX
options.
Examples
1. To list information about all attributes, enter:
attribute
The output is similar to:
attr obj_addr type state stack scope prio sched p-shar
$a1 0x200035c8 mutex valid no
$a2 0x20003628 cond valid no
$a3 0x200037c8 thr valid 57344 sys 126 other
$a4 0x200050f8 thr valid 57344 pro 126 other
2. To list information about attributes 1 and 3, enter:
attribute 1 3
The output is similar to:
attr obj_addr type state stack scope prio sched p-shar
$a1 0x200035c8 mutex valid no
$a3 0x200037c8 thr valid 57344 sys 126 other
See the condition subcommand, mutex subcommand, print subcommand,
and thread subcommand for the dbx command.
Also, see Creating Threads, Using Mutexes, and Using Condition Variables.
call Subcommand
call Procedure ( [ Parameters ] )
The call subcommand runs the procedure specified by the Procedure
parameter. The return code is not printed. If any parameters are specified,
they are passed to the procedure being run.
Example
To call a command while running dbx, enter:
(dbx) call printf("hello")
hello
printf returns successfully.
case Subcommand
case [ default | mixed | lower | upper ]
The case subcommand changes how the dbx debug program interprets symbols.
The default handling of symbols is based on the current language.
If the current language is C, C++, or undefined, the symbols are not
folded; if the current language is FORTRAN or Pascal, the symbols
are folded to lowercase. Use this subcommand if a symbol needs to
be interpreted in a way not consistent with the current language.
Entering the case subcommand with no parameters displays the current
case mode.
Flags
default Varies with the current language.
mixed Causes symbols to be interpreted as they actually appear.
lower Causes symbols to be interpreted as lowercase.
upper Causes symbols to be interpreted as uppercase.
Examples
1. To display the current case mode, enter:
case
2. To instruct dbx to interpret symbols as they actually appear, enter:
case mixed
3. To instruct dbx to interpret symbols as uppercase, enter:
case upper
See Folding Variables to Lowercase and Uppercase.
catch Subcommand
catch [ SignalNumber | SignalName ]
The catch subcommand starts the trapping of a specified signal before
that signal is sent to the application program. This subcommand is
useful when the application program being debugged handles signals
such as interrupts. The signal to be trapped can be specified by number
or by name using either the SignalNumber or the SignalName parameter,
respectively. Signal names are case insensitive, and the SIG prefix
is optional. If neither the SignalNumber nor the SignalName parameter
is specified, all signals are trapped by default except the SIGHUP,
SIGCLD, SIGALARM, and SIGKILL signals. If no arguments are specified,
the current list of signals to be caught is displayed.
Examples
1. To display a current list of signals to be caught by dbx, enter:
catch
2. To trap signal SIGALARM, enter:
catch SIGALARM
See the ignore subcommand and Handling Signals.
clear Subcommand
clear SourceLine
The clear subcommand removes all stops at a given source line. The
SourceLine parameter can be specified in two formats:
* As an integer
* As a file name string followed by a : (colon) and an integer
Examples
To remove breakpoints set at line 19, enter:
clear 19
The cleari subcommand and delete subcommand. Also, see Setting and
Deleting Breakpoints in AIX Version 4.1 General Programming Concepts:
Writing and Debugging Programs.
cleari Subcommand
cleari Address
The cleari subcommand clears all the breakpoints at the address specified
by the Address parameter.
Examples
1. To remove a breakpoint set at address 0x100001b4, enter:
cleari 0x100001b4
2. To remove a breakpoint set at the main() procedure address, enter:
cleari &main
See the clear subcommand, the delete subcommand, and Setting and Deleting
Breakpoints in AIX Version 4.1 General Programming Concepts: Writing
and Debugging Programs.
condition Subcommand
condition [ wait | nowait | ConditionNumber ... ]
The condition subcommand displays information about one or more condition
variables. If one or more ConditionNumber parameters are given, the
condition subcommand displays information about the specified condition
variables. If no flags or parameters are specified, the condition
subcommand lists all condition variables.
The information listed for each condition is as follows:
cv Indicates the symbolic name of the condition variable, in the form
$cConditionNumber.
obj_addr Indicates the memory address of the condition variable.
num_wait Indicates the number of threads waiting on the condition
variable.
waiters Lists the user threads which are waiting on the condition
variable.
Note: The print subcommand of the dbx debug program recognizes symbolic
condition variable names, and can be used to display the status of
the corresponding object.
Flags
wait Displays condition variables which have waiting threads.
nowait Displays condition variables which have no waiting threads.
Examples
1. To display information about all condition variables, enter:
condition
2. To display information about all condition variables which have
waiting threads, enter:
condition wait
3. To display information about the condition variable 3, enter:
condition 3
The output is similar to:
cv obj_addr num_wait waiters
$c3 0x20003290 0
See the attribute subcommand, mutex subcommand, print subcommand,
and thread subcommand.
Also, see Using Condition Variables.
cont Subcommand
cont [ SignalNumber | SignalName ]
The cont subcommand continues the execution of the application program
from the current stopping point until either the program finishes
or another breakpoint is reached. If a signal is specified, either
by the number specified in the SignalNumber parameter or by the name
specified in the SignalName parameter, the program continues as if
that signal had been received. Signal names are not case sensitive
and the SIG prefix is optional. If no signal is specified, the program
continues as if it had not been stopped.
Examples
1. To continue program execution from current stopping point, enter:
cont
2. To continue program execution as though it received the signal
SIGQUIT, enter:
cont SIGQUIT
See the detach subcommand for the dbx command, the goto subcommand
for the dbx command, the next subcommand for the dbx command, the
skip subcommand for the dbx command, the step subcommand for the dbx
command,
delete Subcommand
delete { Number ... | all }
The delete subcommand removes traces and stops from the application
program. The traces and stops to be removed can be specified through
the Number parameters, or all traces and stops can be removed by using
the all flag. Use the status subcommand to display the numbers associated
by the dbx debug program with a trace or stop.
Flag
all Removes all traces and stops.
Examples
1. To remove all traces and stops from the application program, enter:
delete all
2. To remove traces and stops for event number 4, enter:
delete 4
See the clear subcommand, the cleari subcommand, the status subcommand
and Setting and Deleting Breakpoints in AIX Version 4.1 General Programming
Concepts: Writing and Debugging Programs.
detach Subcommand
detach [ SignalNumber | SignalName ]
The detach subcommand continues the execution of the application program
and exits the debug program. A signal can be specified either by:
* Name, using the SignalName parameter
* Number, using the SignalNumber parameter
Signal names are not case sensitive and the SIG prefix is optional.
If a signal is specified, the program continues as if it had received
that signal. If no signal is specified, the program continues as if
no stop had occurred.
Examples
1. To continue execution of the application and exit dbx, enter:
detach
2. To exit dbx and continue execution of the application as though
it received signal SIGREQUEST, enter:
detach SIGREQUEST
See Using the dbx Debug Program
display memory Subcommand
{ Address,Address/ | Address/ [ Count ] } [ Mode ] [ >File
]
The display memory subcommand, which does not have a keyword to initiate
the command, displays a portion of memory controlled by the following
factors:
* The range of memory displayed is controlled by specifying
either:
- Two Address parameters, where all lines between those two addresses
are displayed,
OR
- One Address parameter where the display starts and a Count that
determines the number of lines displayed from Address.
Specify symbolic addresses by preceding the name with an & (ampersand).
Addresses can be expressions made up of other addresses and the operators
+ (plus sign), - (minus sign), and * (indirection). Any expression
enclosed in parentheses is interpreted as an address.
* The format in which the memory is displayed is controlled
by the Mode parameter. The default for the Mode parameter is the current
mode. The initial value of Mode is X. The possible modes include:
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.
lld Prints an 8-byte signed decimal number.
llu Prints an 8-byte unsigned decimal number.
llx Prints an 8-byte unsigned hexadecimal number.
llo Prints an 8-byte unsigned octal number.
o Prints a short word in octal
O Prints a long word in octal.
q Prints an extended-precision floating-point number.
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.
Flag
>File Redirects output to the specified file.
Examples
1. To display one long word of memory content in hexadecimal starting
at the address 0x3fffe460, enter:
0x3fffe460 / X
2. To display two bytes of memory content as characters starting at
the variable y address, enter:
&y / 2c
3. To display the sixth through the eighth elements of the FORTRAN
character string a_string, enter:
&a_string + 5, &a_string + 7/c
See Examining Memory Addresses in AIX Version 4.1 General Programming
Concepts: Writing and Debugging Programs.
down Subcommand
down [ Count ]
The down subcommand moves the current function down the stack Count
number of levels. The current function is used for resolving names.
The default for the Count parameter is one.
Examples
1. To move one level down the stack, enter:
down
2. To move three levels down the stack, enter:
down 3
See the up subcommand, the where subcommand, and Displaying a Stack
Trace in AIX Version 4.1 General Programming Concepts: Writing and
Debugging Programs.
dump Subcommand
dump [ Procedure ] [ >File ]
The dump subcommand displays the names and values of all variables
in the specified procedure. If the Procedure parameter is . (period),
then all active variables are displayed. If the Procedure parameter
is not specified, the current procedure is used. If the >File flag
is used, the output is redirected to the specified file.
Flags
>File Redirects output to the specified file.
Examples
1. To display names and values of variables in the current procedure,
enter:
dump
2. To display names and values of variables in the add_count procedure,
enter:
dump add_count
3. To redirect names and values of variables in the current procedure
to the var.list file, enter:
dump > var.list
See Displaying and Modifying Variables in AIX Version 4.1 General
Programming Concepts: Writing and Debugging Programs.
edit Subcommand
edit [ Procedure | File ]
The edit subcommand invokes an editor on the specified file. The file
may be specified through the File parameter or by specifying the Procedure
parameter, where the editor is invoked on the file containing that
procedure. If no file is specified, the editor is invoked on the current
source file. The default is the vi editor. Override the default by
resetting the EDITOR environment variable to the name of the desired
editor.
Examples
1. To start an editor on the current source file, enter:
edit
2. To start an editor on the main.c file, enter:
edit main.c
3. To start an editor on the file containing the do_count() procedure,
enter:
edit do_count
See the list subcommand, the vi or vedit command. Also, see Changing
the Current File or Procedure and Displaying the Current File in AIX
Version 4.1 General Programming Concepts: Writing and Debugging Programs.
file Subcommand
file [ File ]
The file subcommand changes the current source file to the file specified
by the File parameter; it does not write to that file. The File parameter
can specify a full path name to the file. If the File parameter does
not specify a path, the dbx program tries to find the file by searching
the use path. If the File parameter is not specified, the file subcommand
displays the name of the current source file. The file subcommand
also displays the full or relative path name of the file if the path
is known.
Examples
1. To change the current source file to the main.c file, enter:
file main.c
2. To display the name of the current source file, enter:
file
See the func subcommand. Also, see Changing the Current File or Procedure
and Displaying the Current File in AIX Version 4.1 General Programming
Concepts: Writing and Debugging Programs.
func Subcommand
func [ Procedure ]
The func subcommand changes the current function to the procedure
or function specified by the Procedure parameter. If the Procedure
parameter is not specified, the default current function is displayed.
Changing the current function implicitly changes the current source
file to the file containing the new function; the current scope used
for name resolution is also changed.
Examples
1. To change the current function to the do_count procedure, enter:
func do_count
2. To display the name of the current function, enter:
func
See the file subcommand. Also, see Changing the Current File or Procedure
in AIX Version 4.1 General Programming Concepts: Writing and Debugging
Programs.
goto Subcommand
goto SourceLine
The goto subcommand causes the specified source line to be run next.
Normally, the source line must be in the same function as the current
source line. To override this restriction, use the set subcommand
with the $unsafegoto flag.
Example
To change the next line to be executed to line 6, enter:
goto 6
See the cont subcommand, the gotoi subcommand, and the set subcommand.
gotoi Subcommand
gotoi Address
The gotoi subcommand changes the program counter address to the address
specified by the Address parameter.
Example
To change the program counter address to address 0x100002b4, enter:
gotoi 0x100002b4
See the goto subcommand.
help Subcommand
help [ Subcommand | Topic ]
The help subcommand displays help information for dbx subcommands
or topics, depending upon the parameter you specify. Entering the
help subcommand with the Subcommand parameter displays the syntax
statement and description of the specified subcommand. Entering the
help subcommand with the Topic parameter displays a detailed description
of the specified topic. The following topics are available:
startup Lists dbx startup options.
execution Lists dbx subcommands related to program execution.
breakpoints Lists dbx subcommands related to breakpoints and traces.
files Lists dbx subcommands for accessing source files.
data Lists dbx subcommands for accessing program variables and data.
machine Lists descriptions of dbx subcommands for machine-level debugging.
environment Lists dbx subcommands for setting dbx configuration and
environment.
threads Lists dbx subcommands for accessing thread-related objects.
expressions Describes dbx expression syntax and operators.
scope Describes how dbx resolves names from different scopes.
set_variables Lists dbx debug variables with a usage description.
usage Lists common dbx subcommands with brief descriptions.
Examples
1. To list all available dbx subcommands and topics, enter:
help
2. To display the description of the dbx subcommand list, enter:
help list
3. To display the description of the dbx topic set_variables, enter:
help set_variables
ignore Subcommand
ignore [ SignalNumber | SignalName ]
The ignore subcommand stops the trapping of a specified signal before
that signal is sent to the application program. This subcommand is
useful when the application program being debugged handles signals
such as interrupts.
The signal to be trapped can be specified by:
* Number, with the SignalNumber parameter
* Name, with the SignalName parameter
Signal names are not case sensitive. The SIG prefix is optional.
If neither the SignalNumber nor the SignalName parameter is specified,
all signals except the SIGHUP, SIGCLD, SIGALRM, and SIGKILL signals
are trapped by default. The dbx debug program cannot ignore the SIGTRAP
signal if it comes from a process outside of the debugee. If no arguments
are specified, the list of currently ignored signals will be displayed.
Example
To cause dbx to ignore alarm clock time-out signals sent to the application
program, enter:
ignore alrm
See the catch subcommand. Also, see Handling Signals in AIX Version
4.1 General Programming Concepts: Writing and Debugging Programs.
list Subcommand
list [ Procedure | SourceLine-Expression [ ,SourceLine-Expression
] ]
The list subcommand displays a specified number of lines of the source
file. The number of lines displayed are specified in one of two ways:
* By specifying a procedure using the Procedure parameter.
In this case, the list subcommand displays lines starting a few lines
before the beginning of the specified procedure and until the list
window is filled.
* By specifying a starting and ending source line number using
the SourceLine-Expression parameter.
The SourceLine-Expression parameter should consist of a valid line
number followed by an optional + (plus sign), or - (minus sign), and
an integer. In addition, a SourceLine of $ (dollar sign) may be used
to denote the current line number; a SourceLine of @ (at sign) may
be used to denote the next line number to be listed.
All lines from the first line number specified to the second line
number specified, inclusive, are then displayed.
If the second source line is omitted, the first line is printed only.
If the list subcommand is used without parameters, the number of lines
specified by $listwindow are printed, beginning with the current source
line.
To change the number of lines to list by default, set the special
debug program variable, $listwindow, to the number of lines you want.
Initially, $listwindow is set to 10.
Examples
1. To list the lines 1 through 10 in the current file, enter:
list 1,10
2. To list 10, or $listwindow, lines around the main procedure, enter:
list main
3. To list 11 lines around the current line, enter:
list $-5,$+5
4. You can use simple integer expressions involving addition and subtraction
in SourceLineExpression expressions. For example:
(dbx) list $
4 {
(dbx) list 5
5 char i = '4';
(dbx) list sub
23 char *sub(s,a,k)
24 int a;
25 enum status k; . . .
(dbx) move 25
(dbx) list @ -2
23 char *sub(s,a,k)
See the edit subcommand, the listi subcommand, and the move subcommand.
Also, see Displaying the Current File in AIX Version 4.1 General Programming
Concepts: Writing and Debugging Programs.
listi Subcommand
listi [ Procedure | at SourceLine | Address [ , Address ] ]
The listi subcommand displays a specified set of instructions from
the source file. The instructions displayed are specified by:
* Providing the Procedure parameter, where the listi subcommand
lists instructions from the beginning of the specified procedure until
the list window is filled.
* Using the at SourceLine flag, where the listi subcommand displays
instructions beginning at the specified source line and continuing
until the list window is filled. The SourceLine variable can be specified
as an integer or as a file-name string followed by a : (colon) and
an integer.
* Specifying a beginning and ending address using the Address
parameters, where all instructions between the two addresses, inclusive,
are displayed.
If the listi subcommand is used without flags or parameters, the next
$listwindow instructions are displayed. To change the current size
of the list window, use the set $listwindow=Value subcommand.
Disassembly Modes
The dbx program can disassemble instructions for either the POWER
or PowerPC architecture. In the default mode, the dbx program displays
the instructions for the architecture on which it is running.
The $instructionset and $mnemonics variables of the set subcommand
for the dbx command allow you to override the default disassembly
mode. For more information, see the set subcommand for the dbx command.
Flag
at SourceLine Specifies a starting source line for the listing.
Examples
1. To list the next 10, or $listwindow, instructions, enter:
listi
2. To list the machine instructions beginning at source line 10, enter:
listi at 10
3. To list the machine instructions beginning at source line 5 in
file sample.c, enter:
listi at "sample.c":5
4. To list the instructions between addresses 0x10000400 and 0x10000420,
enter:
listi 0x10000400, 0x10000420
See the list subcommand and the set subcommand. Also, see Debugging
at the Machine Level with dbx in AIX Version 4.1 General Programming
Concepts: Writing and Debugging Programs.
map Subcommand
map [ > File ]
The map subcommand displays characteristics for each loaded portion
of the application. This information includes the name, text origin,
text length, data origin, and data length for each loaded module.
Flag
> File Redirects output to the specified file.
See Debugging at the Machine Level with dbx in AIX Version 4.1 General
Programming Concepts: Writing and Debugging Programs.
move Subcommand
move SourceLine
The move subcommand changes the next line to be displayed to the line
specified by the SourceLine parameter. This subcommand changes the
value of the @ (at sign) variable.
The SourceLine variable can be specified as an integer or as a file
name string followed by a : (colon) and an integer.
Examples
1. To change the next line to be listed to line 12, enter:
move 12
2. To change the next line to be listed to line 5 in file sample.c,
enter:
move "sample.c":5
See the list subcommand. Also, see Displaying the Current File in
AIX Version 4.1 General Programming Concepts: Writing and Debugging
Programs.
multproc Subcommand
multproc [ on | parent | child | off ]
The multproc subcommand specifies the behavior of the dbx debug program
when forked and execed processes are created. The on flag is used
to specify that a new dbx session will be created to debug the child
path of a fork. The original dbx will continue to debug the parent
path. The parent and child flags are used to specify a single path
of a fork to follow. All flags except off enable dbx to follow an
execed process. The off flag disables multiprocess debugging. If no
flags are specified, the multproc subcommand returns the current status
of multiprocess debugging.
The dbx program uses Xwindows for multiprocess debugging. The dbx
program opens as many windows as needed for multiprocessing. The title
for each child window is the process ID (pid) of the child process.
To switch between processes, use Xwindows handling techniques to activate
the window where the dbx session is displayed. If the system does
not have Xwindows support, a warning message is issued when the debuggee
forks, and the dbx program continues debugging only the parent process.
Multiprocess debugging can also be unsuccessful for the following
reasons:
* The dbx program is not running in an Xwindows environment.
* Xwindows is running but the dbx global $xdisplay variable
is not set to a valid display name. The $xdisplay variable is initialized
to the shell DISPLAY environment variable. The set Name=Expression
dbx subcommand can be used to change the value of the display name.
* The /tmp directory does not allow read or write access to
the debugging program. The dbx program requires a small amount of
space in this directory when controlling an Xwindow environment.
* The system does not have enough resources to accommodate a
new Xwindow.
If $xdisplay is set to a remote display, the user may not be able
to see the newly created Xwindow. If the $xdisplay setting is not
correct, Xwindows or other system resources report the cause of the
failure.
The dbx program does not distinguish between different types of failures,
but the following message is sent when the subcommand is not successful:
Warning: dbx subcommand multiproc fails. dbx continued with multproc
disabled.
The user-defined configuration of the newly created window can be
defined under the dbx_term application name in the .Xdefaults file.
Flags
on Enables multiprocess debugging.
off Disables multiprocess debugging.
Examples
1. To check the current status of multiprocess debugging, enter:
multproc
2. To enable multiprocess debugging, enter:
multproc on
3. To disable multiprocess debugging, enter:
multproc off
See the screen subcommand and the fork subroutine. Also, see Debugging
Programs Involving Multiple Processes in AIX Version 4.1 General Programming
Concepts: Writing and Debugging Programs.
mutex Subcommand
mutex [ lock | unlock | MutexNumber ... ]
The mutex subcommand displays information about mutexes. If the MutexNumber
parameter is given, the mutex subcommand displays information about
the specified mutexes. If no flags or parameters are specified, the
mutex subcommand displays information about all mutexes.
The information listed for each mutex is as follows:
mutex Indicates the symbolic name of the mutex, in the form $mMutexNumber.
type Indicates the type of the mutex: non-rec (non recursive), recursi
(recursive) or fast.
obj_addr Indicates the memory address of the mutex.
lock Indicates the lock state of the mutex: yes if the mutex is locked,
no if not.
owner If the mutex is locked, indicates the symbolic name of the user
thread which holds the mutex.
Note: The print subcommand of the dbx debug program recognizes symbolic
mutex names, and can be used to display the status of the corresponding
object.
Flags
lock Displays information about locked mutexes.
unlock Displays information about unlocked mutexes.
Examples
1. To display information about all mutexes, enter:
mutex
2. To display information about all locked mutexes, enter:
mutex lock
3. To display information about mutexes number four, five and six
enter:
mutex 4 5 6
The output is similar to:
mutex obj_addr type lock owner
$m4 0x20003274 non-rec no
$m5 0x20003280 recursi no
$m6 0x2000328a fast no
See the attribute subcommand, the condition subcommand, the print
subcommand, and the thread subcommand.
Also, see. Using Mutexes.
next Subcommand
next [ Number ]
The next subcommand runs the application program up to the next source
line. The Number parameter specifies the number of times the next
subcommand runs. If the Number parameter is not specified, next runs
once only.
If you use the next subcommand in a multi-threaded application program,
all the user threads run during the operation, but the program continues
execution until the running thread reaches the specified source line.
If you wish to step the running thread only, use the set subcommand
to set the variable $hold_next. Setting this variable may result in
deadlock since the running thread may wait for a lock held by one
of the blocked threads.
Examples
1. To continue execution up to the next source line, enter:
next
2. To continue execution up to the third source line following the
current source line, enter:
next 3
See the cont subcommand, goto subcommand, nexti subcommand, set subcommand,
and the step subcommand.
nexti Subcommand
nexti [ Number ]
The nexti subcommand runs the application program up to the next instruction.
The Number parameter specifies the number of times the nexti subcommand
will run. If the Number parameter is not specified, nexti runs once
only.
If you use the nexti subcommand in a multi-threaded application program,
all the user threads run during the operation, but the program continues
execution until the running thread reaches the specified machine instruction.
If you wish to step the running thread only, use the set subcommand
to set the variable $hold_next. Setting this variable may result in
deadlock since the running thread may wait for a lock held by one
of the blocked threads.
Examples
1. To continue execution up to the next machine instruction, enter:
nexti
2. To continue execution up to the third machine instruction following
the current machine instruction, enter:
nexti 3
See the gotoi subcommand, next subcommand, set subcommand, and stepi
subcommand. Also, see Running a Program at the Machine Level in AIX
Version 4.1 General Programming Concepts: Writing and Debugging Programs.
print Subcommand
print Expression ...
print Procedure ( [ Parameters ] )
The print subcommand does either of the following:
* Prints the value of a list of expressions, specified by the
Expression parameters.
* Executes a procedure, specified by the Procedure parameter
and prints the return value of that procedure. Parameters that are
included are passed to the procedure.
Examples
1. To display the value of x and the value of y shifted left two bits,
enter:
print x, y << 2
2. To display the value returned by calling the sbrk routine with
an argument of 0, enter:
print sbrk(0)
See the assign subcommand, the call subcommand, and the set subcommand.
prompt Subcommand
prompt [ "String" ]
The prompt subcommand changes the dbx command prompt to the string
specified by the String parameter.
Example
To change the prompt to dbx>, enter:
prompt "dbx>"
See Defining a New dbx Prompt in AIX Version 4.1 General Programming
Concepts: Writing and Debugging Programs.
quit Subcommand
quit
The quit subcommand terminates all processes running in the dbx debugging
session.
See the detach subcommand.
registers Subcommand
registers [ >File ]
The registers subcommand displays the values of general purpose registers,
system control registers, floating-point registers, and the current
instruction register.
* General purpose registers are denoted by the $rNumber variable,
where the Number parameter indicates the number of the register.
Note: The register value may be set to the 0xdeadbeef hexadecimal
value. The 0xdeadbeef hexadecimal value is an initialization value
assigned to general-purpose registers at process initialization.
* Floating point registers are denoted by the $frNumber variable.
By default, the floating-point registers are not displayed. To display
the floating-point registers, use the unset $noflregs dbx subcommand.
Note: The registers subcommand cannot display registers if the current
thread is in kernel mode.
Flag
>File Redirects output to the specified file.
See the set subcommand and the unset subcommand. Also, see Using Machine
Registers in AIX Version 4.1 General Programming Concepts: Writing
and Debugging Programs.
rerun Subcommand
rerun [ Arguments ] [ File ] [ > >File ]
[ 2>File ] [ 2> >File ] [ >&File ] [ > >&File ]
The rerun subcommand begins execution of the object file. The Arguments
are passed as command line arguments. If the Arguments parameter is
not specified, the arguments from the last run or rerun subcommand
are reused.
Flags
File Redirects output to File.
> >File Appends redirected output to File.
2>File Redirects standard error to File.
2> >File Appends redirected standard error to File.
>&File Redirects output and standard error to File.
> >&File Appends output and standard error to File.
See the run subcommand.
return Subcommand
return [ Procedure ]
The return subcommand causes the application program to execute until
a return to the procedure specified by the Procedure parameter is
reached. If the Procedure parameter is not specified, execution ceases
when the current procedure returns.
Examples
1. To continue execution to the calling routine, enter:
return
2. To continue execution to the main procedure, enter:
return main
run Subcommand
run [ Arguments ] [ File ] [ > >File ] [ 2
>File ] [ 2> >File ] [ >&File ] [ > >&File ]
The run subcommand starts the object file. The Arguments are passed
as command line arguments.
Flags
File Redirects output to File.
2>File Redirects standard error to File.
> >File Appends redirected output to File.
2> >File Appends redirected standard error to File.
>&File Redirects output and standard error to File.
> >&File Appends output and standard error to File.
Example
To run the application with the arguments blue and 12, enter:
run blue 12
See the rerun subcommand.
screen Subcommand
screen
The screen subcommand opens an Xwindow for the dbx command interaction.
You continue to operate in the window in which the process originated.
The screen subcommand must be run while the dbx debug program is running
in an Xwindows environment. If the screen subcommand is issued in
a non-Xwindow environment, the dbx program displays a warning message
and resumes debugging as if the screen subcommand had not been given.
The screen subcommand can also be unsuccessful in the following situations:
* The dbx program is not running in an Xwindows environment.
* Xwindows is running but the dbx global $xdisplay variable
is not set to a valid display name. The $xdisplay variable is initialized
to the DISPLAY environment variable. The dbx subcommand set Name=Expression
changes the value of the display name.
* Xwindows is running, but the TERM environment variable is
not set to a valid command name to invoke a new window.
* The /tmp directory does not allow read or write access to
the program. The dbx program requires a small amount of space in this
directory when the screen command is executed.
* System does not have enough resources to accommodate a new
Xwindow.
The dbx program does not distinguish between different types of failures,
but the program does send the following message:
Warning: dbx subcommand screen fails. dbx continues.
If $xdisplay is set to a remote display, the user may not be able
to see the newly created Xwindow. If the $xdisplay setting is not
correct, Xwindows or other system resources report the problem.
The user-defined configuration of the newly created window can be
defined under the dbx_term application name in the .Xdefaults file.
Example
To open an Xwindow for dbx command interaction, enter:
screen
See Separating dbx Output From Program Output in AIX Version 4.1 General
Programming Concepts: Writing and Debugging Programs and AIXwindows
Overview.
set Subcommand
set [ Variable=Expression ]
The set subcommand defines a value for the dbx debug program variable.
The value is specified by the Expression parameter; the program variable
is specified by the Variable parameter. The name of the variable should
not conflict with names in the program being debugged. A variable
is expanded to the corresponding expression within other commands.
If the set subcommand is used without arguments, the variables currently
set are displayed.
The following variables are set with the set subcommand:
$catchbp Catches breakpoints during the execution of the next command.
$expandunions Displays values for each part of variant records or
unions.
$frame Uses the stack frame pointed to by the address designated by
the value of $frame for doing stack traces and accessing local variables.
$hexchars Prints characters as hexadecimal values.
$hexin Interprets addresses in hexadecimal.
$hexints Prints integers as hexadecimal values.
$hexstrings Prints character pointers in hexadecimal.
$hold_next Holds all threads except the running thread during the
cont, next, nexti, and step subcommands. Setting this variable may
result in deadlock since the running thread may wait for a lock held
by one of the blocked threads.
$ignoreload Does not stop when your program performs the load, unload,
or loadbind subroutine.
$instructionset Overrides the default disassembly mode. The following
list contains possible values for the Expression parameter:
"default" Specifies the architecture on which the dbx program is running.
"com" Specifies the instruction set for the common intersection mode
of the PowerPC and POWER architectures. The dbx program defaults to
PowerPC mnemonics.
"pwr" Specifies the instruction set and mnemonics for the POWER architecture.
"pwrx" Specifies the instruction set and mnemonics for the POWER2
implementation of the POWER architecture.
"601" Specifies the instruction set and mnemonics for the PowerPC
601 RISC Microprocessor.
"603" Specifies the instruction set and mnemonics for the PowerPC
603 RISC Microprocessor.
"604" Specifies the instruction set and mnemonics for the PowerPC
604 RISC Microprocessor.
"ppc" Specifies the instruction set and mnemonics defined in the PowerPC
architecture, excluding the optional instructions. These instructions
are available in all PowerPC implementations except the PowerPC 601
RISC Microprocessor.
"any" Specifies any valid PowerPC or POWER instruction. For instruction
sets that overlap, the default is the PowerPC mnemonics.
If no value is set for the Expression parameter, the dbx program
uses the default disassembly mode.
$listwindow Specifies the number of lines to list around a function
and the number to list when the list subcommand is used without parameters.
The default is 10 lines.
$mapaddrs Starts mapping addresses. Unsetting $mapaddrs stops address
mapping.
$mnemonics Changes the set of mnemonics to be used by the dbx program
when disassembling.
"default" Specifies the mnemonics that most closely match the specified
instruction set.
"pwr" Specifies the mnemonics for the POWER architecture.
"ppc" Specifies the mnemonics defined in the PowerPC architecture
book, excluding the optional instructions.
If no value is set for the Expression parameter, the dbx program
will use the mnemonics that most closely match the specified instruction
set.
$noargs Omits arguments from subcommands, such as where, up, down,
and dump.
$noflregs Omits the display of floating-point registers from the registers
subcommand.
$octin Interprets addresses in octal.
$octints Prints integers in octal.
$repeat Repeats the previous command if no command was entered.
$sigblock Blocks signals to your program.
$stepignore Controls how the dbx command behaves when the step subcommand
runs on a source line that calls another routine for which no debugging
information is available. This variable enables the step subcommand
to step over large routines for which no debugging information is
available. The following list contains possible values for the Expression
parameter:
"function" Performs the function of the next subcommand for the dbx
command. This is the default value.
"module" Performs the function of the next subcommand if the function
is in a load module for which no debug information is available (such
as a system library).
"none" Performs the function of the stepi subcommand for the dbx command
in the background until it reaches an instruction for which source
information is available. At that point dbx will display where execution
has stopped.
$unsafeassign Turns off strict type checking between the two sides
of an assign statement. Even if the $unsafeassign variable is set,
the two sides of an assign statement may not contain storage types
of different sizes.
$unsafebounds Turns off subscript checking on arrays.
$unsafecall Turns off strict type checking for arguments to subroutines
or function calls.
$unsafegoto Turns off the goto subcommand destination checking.
$vardim Specifies the dimension length to use when printing arrays
with unknown bounds. The default value is 10.
$xdisplay Specifies the display name for Xwindows, for use with the
multproc subcommand or the screen subcommand. The default is the value
of the shell DISPLAY variable.
The $unsafe variables limit the usefulness of the dbx debug program
in detecting errors.
Examples
1. To change the default number of lines to be listed to 20, enter:
set $listwindow=20
2. To disable type checking on the assign subcommand, enter:
set $unsafeassign
3. To disassemble machine instructions for the PowerPC 601 RISC Microprocessor,
enter:
set $instructionset="601"
See the unset subcommand. Also, see Changing Print Output with Special
Debug Program Variables in AIX Version 4.1 General Programming Concepts:
Writing and Debugging Programs.
sh Subcommand
sh [ Command ]
The sh subcommand passes the command specified by the Command parameter
to the shell for execution. The SHELL environment variable determines
which shell is used. The default is the sh shell. If no argument is
specified, control is transferred to the shell.
Examples
1. To run the ls command, enter:
sh ls
2. To escape to a shell, enter:
sh
3. To use the SHELL environment variable, enter:
sh echo $SHELL
See Running Shell Commands from dbx in AIX Version 4.1 General Programming
Concepts: Writing and Debugging Programs.
skip Subcommand
skip [ Number ]
The skip subcommand continues execution of the application program
from the current stopping point. A number of breakpoints equal to
the value of the Number parameter are skipped and execution then ceases
when the next breakpoint is reached or when the program finishes.
If the Number parameter is not specified, it defaults to a value of
one.
Example
To continue execution until the second breakpoint is encountered,
enter:
skip 1
Also see the cont subcommand.
source Subcommand
source File
The source subcommand reads dbx subcommands from the file specified
by the File parameter.
Example
To read the dbx subcommands in the cmdfile file, enter:
source cmdfile
See Reading dbx Subcommands from a File in AIX Version 4.1 General
Programming Concepts: Writing and Debugging Programs.
status Subcommand
status [ >File ]
The status subcommand displays the trace and stop subcommands currently
active. The > flag sends the output of the status subcommand to a
file specified in the File parameter.
Flag
>File Redirects output to File.
See the clear subcommand, the delete subcommand, the stop subcommand,
and the trace subcommand for the dbx command.
Also, see Setting and Deleting Breakpoints in AIX Version 4.1 General
Programming Concepts: Writing and Debugging Programs.
step Subcommand
step [ Number ]
The step subcommand runs source lines of the application program.
Specify the number of lines to be executed with the Number parameter.
If the Number parameter is omitted, it defaults to a value of 1.
If you use the step subcommand on a multi-threaded application program,
all the user threads run during the operation, but the program continues
execution until the running thread reaches the specified source line.
If you wish to step the running thread only, use the set subcommand
to set the variable $hold_next. Setting this variable may result in
deadlock since the running thread may wait for a lock held by one
of the blocked threads.
Note: Use the $stepignore variable of the set subcommand to control
the behavior of the step subcommand. The $stepignore variable enables
the step subcommand to step over large routines for which no debugging
information is available.
Examples
1. To continue execution for one source line, enter:
step
2. To continue execution for five source lines, enter:
step 5
3. To prevent the dbx program from single-stepping the printf function,
as illustrated in the following example code:
60 printf ("hello world \n");
enter:
set $stepignore="function"; step
See the cont subcommand, the goto subcommand , the next subcommand,
the set subcommand, and the stepi subcommand.
stepi Subcommand
stepi [ Number ]
The stepi subcommand runs instructions of the application program.
Specify the number of instructions to be executed in the Number parameter.
If the Number parameter is omitted, it defaults to one.
If used on a multi-threaded application program, the stepi subcommand
steps the running thread only. All other user threads remain stopped.
Examples
1. To continue execution for one machine instruction, enter:
stepi
2. To continue execution for 5 machine instructions, enter:
stepi 5
See the gotoi subcommand, the nexti subcommand, and the step subcommand.
stop Subcommand
stop { [Variable] [at SourceLine | in Procedure ] [ if Condition
]}
The stop subcommand halts the application program when certain conditions
are fulfilled. The program is stopped when:
* The Condition is true when the if Condition flag is used.
* The Procedure is called if the in Procedure flag is used.
* The Variable is changed if the Variable parameter is specified.
* The SourceLine line number is reached if the at SourceLine
flag is used.
The SourceLine variable can be specified as an integer or as a file
name string followed by a : (colon) and an integer.
After any of these commands, the dbx debug program responds with a
message reporting the event it has built as a result of your command.
The message includes the event ID associated with your breakpoint
along with an interpretation of your command. The syntax of the interpretation
might not be exactly the same as your command. For example:
stop in main
[1] stop in main
stop at 19 if x == 3
[2] stop at "hello.c":19 if x = 3
The numbers in brackets are the event identifiers associated with
the breakpoints. The dbx debug program associates event numbers with
each stop subcommand. When the program is halted as the result of
one of the events, the event identifier is displayed along with the
current line to show what event caused the program to stop. The events
you create coexist with internal events created by dbx, so event numbers
may not always be sequential.
Use the status subcommand to view these numbers. You can redirect
output from status to a file. Use the delete or clear subcommand to
turn the stop subcommand off.
In a multi-threaded application program, all user threads are halted
when any user thread hits a breakpoint. A breakpoint set on a source
line or function will be hit by any user thread which executes the
line or function, unless you specify conditions as shown in example
9. The following aliases specify the conditions automatically:
* bfth(Function, ThreadNumber)
* blth(SourceLine, ThreadNumber)
ThreadNumber is the number part of the symbolic thread name as reported
by the thread subcommand (for example, 5 is the ThreadNumber for the
thread name $t5). These aliases are actually macros which produce
the expanded subcommands shown below:
stopi at &Function if ($running_thread == ThreadNumber)
stop at SourceLine if ($running_thread == ThreadNumber)
Flags
at SourceLine Specifies the line number.
if Condition Specifies the condition, such as true.
in Procedure Specifies the procedure to be called.
Examples
1. To stop execution at the first statement in the main procedure,
enter:
stop in main
2. To stop execution when the value of the x variable is changed on
line 12 of the execution, enter:
stop x at 12
3. To stop execution at line 5 in file sample.c, enter:
stop at "sample.c":5
4. To check the value of x each time that dbx runs a subroutine within
func1, enter:
stop in func1 if x = 22
5. To check the value of x each time that dbx begins to run func1,
enter:
stopi at &func1 if x = 22
6. To stop the program when the value of Variable changes, enter:
stop Variable
7. To stop the program whenever Condition evaluates to true, enter:
stop if (x > y) and (x < 2000)
8. The following example shows how to display active events and remove
them:
status
[1] stop in main
[2] stop at "hello.c":19 if x = 3
delete 1
status
[2] stop at "hello.c":19 if x = 3
clear 19
status
(dbx)
The delete command eliminates events by event identifier. The clear
command deletes breakpoints by line number.
9. To place a breakpoint at the start of func1 only when executed
by thread $t5, enter one of the following equivalent commands:
stopi at &func1 if ($running_thread == 5)
or
bfth(func1, 5)
See the clear subcommand, the delete subcommand, the stopi subcommand,
and the trace subcommand. Also, see Setting and Deleting Breakpoints
in AIX Version 4.1 General Programming Concepts: Writing and Debugging
Programs.
stopi Subcommand
stopi { [Address] [at Address | in Procedure ] [ if Condition
]}
The stopi subcommand sets a stop at the specified location:
* With the if Condition flag, the program stops when the condition
true is specified.
* With the Address parameter, the program stops when the contents
of Address change.
* With the at Address flag, a stop is set at the specified address.
* With the in Procedure flag, the program stops when the Procedure
is called.
Flags
if Condition Specifies the condition, such as true.
in Procedure Specifies the procedure to be called.
at Address Specifies the machine instruction address.
Examples
1. To stop execution at address 0x100020f0, enter:
stopi at 0x100020f0
2. To stop execution when the contents of address 0x100020f0 change,
enter:
stopi 0x100020f0
3. To stop execution when the contents of address 0x100020f0 are changed
by thread $t1, enter:
stopi 0x200020f0 if ($running_thread == 1)
See the stop subcommand . Also, see Debugging at the Machine Level
with dbx in AIX Version 4.1 General Programming Concepts: Writing
and Debugging Programs.
thread Subcommand
Display Selected Threads
thread { [ info ] [ ThreadNumber ... ] } | current | run | susp
| term | wait
Select an Individual Thread
thread current ThreadNumber
Hold or Release Threads
thread { hold | unhold } [ ThreadNumber ... ]
The thread subcommand displays and controls user threads.
The first form of the thread subcommand is used to display information
about selected user threads. If no parameters are given, information
about all user threads is displayed. If one or more ThreadNumber parameters
are given, information about the corresponding user threads is displayed.
When the thread subcommand displays threads, the current thread line
is preceded by a >. If the running thread is not the same as the
current thread, its line is preceded by a *.
The information displayed by the thread subcommand is as follows:
thread Indicates the symbolic name of the user thread, in the form
$tThreadNumber.
state-k Indicates the state of the kernel thread (if the user thread
is attached to a kernel thread). This can be run, wait, susp, or term,
for running, waiting, suspended, or terminated.
wchan Indicates the event on which the kernel thread is waiting or
sleeping (if the user thread is attached to a kernel thread).
state-u Indicates the state of the user thread. Possible states are
running, blocked, or terminated.
k-tid Indicates the kernel thread identifier (if the user thread is
attached to a kernel thread).
mode Indicates the mode (kernel or user) in which the user thread
is stopped (if the user thread is attached to a kernel thread).
held Indicates whether the user thread has been held.
scope Indicates the contention scope of the user thread; this can
be sys or pro for system or process contention scope.
function Indicates the name of the user thread function.
The second form of the thread subcommand is used to select the current
thread. The print, registers, and where subcommands of the dbx debug
program all work in the context of the current thread. The registers
subcommand cannot display registers if the current thread is in kernel
mode.
The third form of the thread subcommand is used to control thread
execution. Threads can be held using the hold flag, or released using
the unhold flag. A held thread will not be resumed until it is released.
Note: The print subcommand of the dbx debug program recognizes symbolic
thread names, and can be used to display the status of the corresponding
object.
Flags
current If the ThreadNumber parameter is not given, displays the current
thread. If the ThreadNumber parameter is given, selects the specified
user thread as the current thread.
hold If the ThreadNumber parameter is not given, holds and displays
all user threads. If one or more ThreadNumber parameters are given,
holds and displays the specified user threads.
unhold If the ThreadNumber parameter is not given, releases and displays
all previously held user threads. If one or more ThreadNumber parameters
are given, releases and displays the specified user threads.
info If the ThreadNumber parameter is not given, displays a long format
listing of all user threads. If one or more ThreadNumber parameters
are given, displays a long format listing the specified user threads.
run Displays threads which are in the run state.
susp Displays threads which are in the susp state.
term Displays threads which are in the term state.
wait Displays threads which are in the wait state.
Examples
1. To display information about threads which are in the wait state,
enter:
thread wait
The output is similar to:
thread state-k wchan state-u k-tid mode held scope function
$t1 wait running 17381 u no pro main
$t3 wait running 8169 u no pro iothread
2. To display information about several given threads, enter:
thread 1 3 4
The output is similar to:
thread state-k wchan state-u k-tid mode held scope function
$t1 wait running 17381 u no pro main
$t3 wait running 8169 u no pro iothread
>$t4 run running 9669 u no pro save_thr
3. To make thread 4 the current thread, enter:
thread current 4
4. To hold thread number 2, enter:
thread hold 2
See the attribute subcommand, the condition subcommand, the mutex
subcommand, the print subcommand, the registers subcommand, and the
where subcommand.
Also, see Creating Threads.
trace Subcommand
trace [ SourceLine | Expression at SourceLine | Procedure | [ Variable
] [ at SourceLine | in Procedure ] ] [ if Condition ]
The trace subcommand prints tracing information for the specified
procedure, function, source line, expression, or variable when the
program runs. The SourceLine variable can be specified as an integer
or as a file name string followed by a : (colon) and an integer. A
condition can be specified. The dbx debug program associates a number
with each trace subcommand. Use the status subcommand to view these
numbers. Use the delete subcommand to turn tracing off.
By default, tracing is process based. In order to make a thread based
trace, specify the thread in a condition as shown in example 8.
Flags
at SourceLine Specifies the source line where the expression being
traced is found.
if Condition Specifies a condition for the beginning of the trace.
The trace begins only if Condition is true.
in Procedure Specifies the procedure to use to find the procedure
or variable being traced.
Examples
1. To trace each call to the printf procedure, enter:
trace printf
2. To trace each execution of line 22 in the hello.c file, enter:
trace "hello.c":22
3. To trace changes to the x variable within the main procedure, enter:
trace x in main
4. To trace the data address 0x2004000, enter:
set $A=0x2004000
trace $A
Note: The tracei subcommand is designed to trace addresses.
5. You can restrict the printing of source lines to when the specified
Procedure is active. You can also specify an optional Condition to
control when trace information should be produced. For example:
(dbx) trace in sub2
[1] trace in sub2
(dbx) run
trace in hellosub.c: 8 printf("%s",s);
trace in hellosub.c: 9 i = '5';
trace in hellosub.c: 10 }
6. You can display a message each time a procedure is called or returned.
When a procedure is called, the information includes passed parameters
and the name of the calling routine. On a return, the information
includes the return value from Procedure. For example:
(dbx) trace sub
[1] trace sub
(dbx) run
calling sub(s = "hello", a = -1, k = delete) from function main
returning "hello" from sub
7. You can print the value of Expression when the program reaches
the specified source line. The lines number and file are printed,
but the source line is not. For example:
(dbx) trace x*17 at "hellosub.c":8 if (x > 0)
[1] trace x*17 at "hellosub.c":8 if x > 0
(dbx) run
at line 8 in file "hellosub.c": x*17 = 51
(dbx) trace x
[1] trace x
initially (at line 4 in "hello.c"): x = 0
after line 17 in "hello.c": x = 3
8. To trace changes to the x variable made by thread $t1, enter:
(dbx) trace x if ($running_thread == 1)
Also, see the tracei subcommand.
tracei Subcommand
tracei [ [ Address ] [ at Address | in Procedure ] | Expression
at Address ] [ if Condition ]
The tracei subcommand turns on tracing when:
* The contents of the address specified by the Address parameter
change if the Address flag is included.
* The instruction at Address is run if the at Address parameter
is specified.
* The procedure specified by Procedure is active if the in Procedure
flag is included.
* The condition specified by the Condition parameter is true
if the if Condition flag is included.
Flags
at Address Specifies an address. Tracing is enabled when the instruction
at this address is run.
if Condition Specifies a condition. Tracing is enabled when this condition
is met.
in Procedure Specifies a procedure. Tracing is enabled when this procedure
is active.
Examples
1. To trace each instruction executed, enter:
tracei
2. To trace each time the instruction at address 0x100020f0 is executed,
enter:
tracei at 0x100020f0
3. To trace each time the contents of memory location 0x20004020 change
while the main procedure is active, enter:
tracei 0x20004020 in main
4. To trace each time the instruction at address 0x100020f0 is executed
by thread $t4, enter:
tracei at 0x100020f0 if ($running_thread == 4)
See the trace subcommand. Also, see Debugging at the Machine Level
with dbx in AIX Version 4.1 General Programming Concepts: Writing
and Debugging Programs.
unalias Subcommand
unalias Name
The unalias subcommand removes the alias specified by the Name parameter.
Example
To remove an alias named printx, enter:
unalias printx
See the alias subcommand. Also, see Creating Subcommand Aliases in
AIX Version 4.1 General Programming Concepts: Writing and Debugging
Programs.
unset Subcommand
unset Name
The unset subcommand deletes the dbx debug program variable associated
with the name specified by the Name parameter.
Example
To delete the variable inhibiting the display of floating-point registers,
enter:
unset $noflregs
See the set subcommand. Also, see Changing Print Output With Special
Debugging Variables in AIX Version 4.1 General Programming Concepts:
Writing and Debugging Programs.
up Subcommand
up [ Count ]
The up subcommand moves the current function up the stack Count number
of levels. The current function is used for resolving names. The default
for the Count parameter is one.
Examples
1. To move the current function up the stack 2 levels, enter:
up 2
2. To display the current function on the stack, enter:
up 0
See the down subcommand. Also, see Changing the Current File or Procedure,
Displaying a Stack Trace in AIX Version 4.1 General Programming Concepts:
Writing and Debugging Programs.
use Subcommand
use [ Directory ... ]
The use subcommand sets the list of directories to be searched when
the dbx debug program looks for source files. If the use subcommand
is specified without arguments, the current list of directories to
be searched is displayed.
The @ (at-sign) is a special symbol that directs the dbx program to
look at the full-path name information in the object file, if it exists.
If you have a relative directory called @ to search, you should use
./@ in the search path.
The use subcommand uses the + (plus-sign) to add more directories
to the list of directories to be searched. If you have a directory
named +, specify the full-path name for the directory (for example,
./+ or /tmp/+).
Examples
1. To change the list of directories to be searched to the current
directory (.), the parent directory (..), and the /tmp directory,
enter:
use . .. /tmp
2. To change the list of directories to be searched to the current
directory (.), the directory the source file was located in at compilation
time (@), and the ../source directory, enter:
use . @ ../source
3. To add the /tmp2 directory to the list of directories to be searched,
enter:
use + /tmp2
Also, see the edit subcommand and the list subcommand.
whatis Subcommand
whatis Name
The whatis subcommand displays the declaration of Name, where the
Name parameter designates a variable, procedure, or function name,
optionally qualified with a block name.
Note: Use the whatis subcommand only while running the dbx debug program.
Examples
1. To display the declaration of the x variable, enter:
whatis x
2. To display the declaration of the main procedure, enter:
whatis main
3. To display the declaration of the x variable within the main function,
enter:
whatis main.x
4. To print the declaration of an enumeration, structure, or union
tag (or the equivalent in Pascal), use $$TagName:
(dbx) whatis $$status
enum $$status { run, create, delete, suspend };
where Subcommand
where [ >File ]
The where subcommand displays a list of active procedures and functions.
By using the >File flag, the output of this subcommand can be redirected
to the specified file.
Flag
>File Redirects output to the specified file.
See the up subcommand and the down subcommand. Also, see Displaying
a Stack Trace in AIX Version 4.1 General Programming Concepts: Writing
and Debugging Programs.
whereis Subcommand
whereis Identifier
The whereis subcommand displays the full qualifications of all the
symbols whose names match the specified identifier. The order in which
the symbols print is not significant.
Examples
To display the qualified names of all symbols named x, enter:
whereis x
Also, see the which subcommand.
which Subcommand
which Identifier
The which subcommand displays the full qualification of the given
identifier. The full qualification consists of a list of the outer
blocks with which the identifier is associated.
Examples
To display the full qualification of the x symbol, enter:
which x
See the whereis subcommand. Also. seeScoping of Names in AIX Version
4.1 General Programming Concepts: Writing and Debugging Programs.
Files
a.out Object file; contains object code.
core Contains core dump.
.dbxinit Contains initial commands.
Implementation Specifics
Software Product/Option:
Standards Compliance: BSD 4.3
Related Information
The adb command, cc command.
The a.out file, core file.
The dbx Symbolic Debug Program Overview and Using the dbx Debug Program
© CNS Electronic
HelpDesk, University of Alberta.
Questions or Comments please e-mail http://www.ualberta.ca/CNS/PUBS/helpform.html.
Last
updated: January 1999