Provides an environment to debug and run programs.
dbx [ -a ProcessID ] [ -B DebugFile ] [ -c CommandFile ] [ -I Directory ] [ -E DebugEnvironment ] [ -p oldpath=newpath:...| pathfile ] [ -u ] [ -F ] [ -L ] [ -r ] [ -x ] [ -v ] [ -C CoreFile | ObjectFile [ CoreFile ] ]
The dbx command provides a symbolic debug program for C, C++, and Fortran programs, allowing you to carry out the following operations:
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.
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 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 might be examined until execution of ObjectFile begins. At that point the dbx debug program prompts for commands.
The -B flag is used to specify an alternative object file or a separate .stab file containing debug information about startup. The alternative object file can be specified only while attaching to a process. The debug information is read from this alternate object file or the .stab debug file instead of the disk copy of the running process. This alternate object file must be the unstripped copy of the original object file; otherwise, it will be ignored. Use the -B flag when the size of the debug section is large. Use the stripped copy of the object file while running and an unstripped copy while debugging. The .stab debug file can be generated through the –bstabsplit linker option. If the -B flag is not specified for a stabsplit executable the dbx command will try to acquire the corresponding .stab file from the executable directory.
Expression Handling
The dbx program can display a wide range of expressions. You can specify expressions in the dbx debug program with C syntax, with some Fortran extensions.
The following operators are valid in the debug program:
Item | Description |
---|---|
* (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 operator 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:
Item | Description |
---|---|
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
Command Line Editing
The dbx command provides a command line editing feature similar to the features provided by Korn Shell. vi mode provides vi-like editing features, while emacs mode gives you controls similar to emacs.
These features can be turned on by using dbx subcommand set -o or set edit. To turn on vi-style command line editing, you would type the subcommand set edit vi or set -o vi.
You can also use the EDITOR environment variable to set the editing mode.
The dbx command saves commands that are entered into the .dbxhist history file. If the DBXHISTFILE environment variable is not set, the history file that is used is $HOME/.dbxhist.
By default, dbx saves the text of the last 128 commands entered. The DBXHISTSIZE environment variable can be used to increase this limit.
Item | Description |
---|---|
-a ProcessID | Attaches the debug program to a process that is running. To attach the debug program, you need authority to send signals to this process. Use the ps command to determine the process ID. If you have permission, the dbx program interrupts the process using the ptrace system call to send a SIGTRAP signal to the process, which cannot ignore the SIGTRAP signal. It then determines the full name of the object file, reads in the symbolic information, and prompts for commands. |
-BDebugFile | This flag allows you to specify an alternative debug file on startup. |
-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. |
-C CoreFile | Analyzes the core file without specifying the object file. In this case, the dbx command uses the object file mentioned in the core file if it exists in the current directory and matches with the core file. Otherwise, it proceeds further without the object file. This flag is ignored if you use it after the -r flag or the -a flag. |
-E DebugEnvironment | Specifies the environment variable for the debug program. |
-p oldpath=newpath:...| pathfile | Specifies a substitution for library paths when examining core files or attaching to a process, in the format oldpath=newpath. The oldpath variable specifies the value to be substituted (as stored in the core file or the loader section of the process when attaching). The newpath variable specifies what it is to be replaced with. The oldpath variable and newpath variable can be complete paths, partial paths, relative paths, or absolute paths. Multiple substitutions are separated by colons. Alternatively, the -p flag might specify the name of a file from which mappings in the previously described format are to be read. Only one mapping per line is allowed when mappings are read from a file. If you use the -p flag when attaching to a process, the debug information is read from the substituted path files. The path files must match the running copy of the library. |
-F | Can be used to turn off the lazy read mode and make the dbx command read all symbols at startup time. By default, lazy reading mode is on: it reads only required symbol table information about initiation of dbx session. In this mode, dbx does not read local variables and types whose symbolic information is not read. Therefore, commands such as whereis i might not list all instances of the local variable i in every function. |
-L | Keep linkage symbols. |
-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:
|
-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. |
-v | Causes the dbx command to skip the validity checking of the core file. This flag allows you to analyze the valid sections of the core file even if some sections are not valid. |
-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_. |
$ 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
main()
{
int i,x[10];
for (i = 0; i < 10;);
}
The program never terminates 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: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.
$ 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 was originally started with dbx.
$dbx -I /home/user/src -I /home/group/src
objfile
The use subcommand might 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.
$ 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 -E LIBPATH=/home/user/lib -E LANG=Ja_JP objfile
dbx –a 467 –B debug_samp –p /usr/lib/=./dir/debug_libs/
dbx –B /usr/debug_samp.stab debug_samp
Note: The subcommands can be used only while running the dbx debug program.
Item | Description |
---|---|
/ | Searches forward in the current source file for a pattern. |
? | Searches backward in the current source file for a pattern. |
addcmd | Adds dbx subcommands to the specified event numbers. |
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 particular 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. |
corefile | Displays high-level data about a core file. |
coremap | Displays the mapping of a particular address space region. |
delcmd | Deletes dbx subcommands associated with the specified event number. |
delete | Removes the traces and stops corresponding to the specified event numbers and tskip counts for a thread. |
detach | Continues execution of application and exits the debug program. |
disable | Disables the traces and stops corresponding to the specified event numbers. |
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. |
enable | Enables the traces and stops corresponding to the specified event numbers. |
fd | Displays file descriptor information. |
file | Changes the current source file to the specified file. |
frame | Changes the current function to the function corresponding to the specified stack frame number. |
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. |
handler | Displays information about pthreads atfork or cancelation cleanup handlers. |
help | Displays help information for dbx subcommands or topics. |
ignore | Stops trapping a signal before that signal is sent to the application program. |
kthread | Displays information about kernel threads. |
limitbp | Limits the number of times that a breakpoint can be run. |
list | Displays lines of the current source file. |
listi | Lists instructions from the application program. |
malloc | Displays information about the program usage of the malloc subsystem. |
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. |
onceblock | Displays information about once blocks. |
plugin | Invokes a plug-in subcommand or displays the names of available plug-ins. |
pluginload | Loads a plug-in. |
pluginunload | Unloads a plug-in. |
Prints the value of an expression or runs a procedure and prints the return code of that procedure. | |
printbp | Prints the number of times that a breakpoint is run. |
proc | Displays information about the process. |
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. |
resource | Displays information about resources owned or waited on by pthreads. |
return | Continues running the application program until a return to the specified procedure is reached. |
rwlock | Displays information about the rwlocks. |
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 | Prints the details about a breakpoint. It also displays the active trace, stop subcommands, and the remaining thread tskip counts. |
step | Runs one source line. |
stepi | Runs one machine instruction. |
stophwp | Sets a hardware watchpoint stop. |
stop | Stops running the application program. |
stopi | Sets a stop at a specified location. |
thdata | Displays thread-specific data. |
thread | Displays and controls threads. |
tls | Displays TLS initialization template information. |
tnext | Runs a thread up to the next source line. |
tnexti | Runs a thread up to the next machine instruction. |
trace | Prints tracing information. |
tracehwp | Sets a hardware watchpoint trace. |
tracei | Turns on tracing. |
tskip | Skips breakpoints for a thread. |
tstep | Runs a thread for one source line. |
tstepi | Runs a thread for one machine instruction. |
tstop | Sets a source-level breakpoint stop for a thread. |
tstophwp | Sets a thread-level hardware watchpoint stop. |
tstopi | Sets an instruction-level breakpoint stop for a thread. |
ttrace | Sets a source-level trace for a thread. |
ttracehwp | Sets a thread-level hardware watchpoint trace. |
ttracei | Sets an instruction-level trace for a thread. |
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 specified 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
/ 12
/
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
?z
?
See the / (search) subcommand and the regcmp subroutine.
addcmd Subcommand
addcmd { Number... | all } "commands_string"
The addcmd subcommand adds dbx subcommands to the specified event, which is run whenever the breakpoint, tracepoint, or watchpoint corresponding to the event is executed. The dbx subcommands can be specified through the "commands_string" parameter, which is a group of dbx subcommands separated by a semicolon (;). The event to which the dbx subcommands are to be added can be specified through the Number parameter, or the dbx subcommands can be added to all events by using the all flag.
Flags
Item | Description |
---|---|
all | Adds dbx subcommands to all the events. |
Examples
addcmd 1 "where"
addcmd 2 "registers"
addcmd 3 "where;registers"
See clear subcommand, the delcmd subcommand, the delete subcommand, disable subcommand, enable subcommand, the stop subcommand, the status subcommand, and the trace subcommand. Also see Setting and Deleting Breakpoints in in AIX® Version 7.1 General Programming Concepts: Writing and Debugging Programs.
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
alias rr rerun
alias printandstep "print n; step"
(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.
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
assign x = 5
assign x = y
assign z = 'z'
assign B = false
assign Y = "Hello World"
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:
Item | Description |
---|---|
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 value can be thr, mutex, or cond for user threads, mutexes, and condition variables respectively. |
state | Indicates the state of the attributes object. This value 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 value 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 threads priority. The value can be no_prio, prio, or protect. |
clock | Indicates the clock attribute of a condition attribute object. This attribute determines which clock must be used when a thread that waits for the condition variable as specified a timeout. The value can be realtime or monotonic. |
Examples
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
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 in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
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, 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
Item | Description |
---|---|
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
case
case mixed
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 the SignalNumber and the SignalName parameters are not 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
catch
catch SIGALARM
See the ignore subcommand and Handling Signals.
clear Subcommand
clear SourceLine
The clear subcommand removes all stops at a particular source line. The SourceLine parameter can be specified in two formats:
Examples
To remove breakpoints set at line 19, enter:
clear 19
The cleari subcommand and delete subcommand. Also, see Setting and Deleting Breakpoints in in AIX Version 7.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
cleari 0x100001b4
cleari &main
See the clear subcommand, the delete subcommand, and Setting and Deleting Breakpoints in in AIX Version 7.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:
Item | Description |
---|---|
cv | Indicates the symbolic name of the condition variable, in the form $cConditionNumber. |
obj_addr | Indicates the memory address of the condition variable. |
clock | Indicates the clock attribute 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
Item | Description |
---|---|
wait | Displays condition variables which have waiting threads. |
nowait | Displays condition variables which have no waiting threads. |
Examples
condition
condition wait
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 in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
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 is received. Signal names are not case-sensitive and the SIG prefix is optional. If no signal is specified, the program continues as if it was not stopped.
Examples
cont
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.
corefile Subcommand
The corefile subcommand displays information from the header of a core file, including the executable name, core file format version information, flags indicating which data is available, the signal that caused the crash, and the execution mode of the process that dumped core.
coremap Subcommand
coremap [ stack | data | sdata | mmap | shm | loader ]
The coremap subcommand displays the mapping of a particular address space region. If you do not specify the region name, the coremap subcommand displays all available mappings.
Examples
coremap shm
coremap mmap
coremap loader
coremap
See the corefile subcommand.
delcmd Subcommand
delcmd EventNumber { Number... | all }
The delcmd subcommand removes the dbx subcommands associated with the specified event. The dbx subcommands to be removed can be specified through Number parameters, or all dbx subcommands associated with the specified event can be removed by using the all flag. The EventNumber parameter specifies the event from which the dbx subcommands are to be removed.
Flags
Item | Description |
---|---|
all | Removes all the dbx subcommands associated with the specified event. |
Examples
delcmd 2 all
delcmd 3 1
delcmd 2 1 2
See the addcmd subcommand, clear subcommand, the delete subcommand, disable subcommand, enable subcommand, the stop subcommand, the status subcommand, and the trace subcommand. Also see Setting and Deleting Breakpoints in in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
delete Subcommand
delete { Number ... | all | tskip [for $tthreadnumber]}
The delete subcommand removes traces and stops from the application program and tskip counts for a thread. 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.
The remaining tskip count, which was set using the tskip subcommand for a thread, can be deleted using the tskip flag. Use the status subcommand to display the remaining thread tskip counts. If no thread is specified, the current thread is used.
Flag
Item | Description |
---|---|
all | Removes all traces and stops. |
for $t threadnumber | Specifies the thread number. |
Examples
delete all
delete 4
delete tskip for $t3
delete tskip
See the clear subcommand, the cleari subcommand, the status subcommand, the tskip subcommand, and Setting and Deleting Breakpoints in in AIX Version 7.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:
Signal names are not case-sensitive and the SIG prefix is optional.
If a signal is specified, the program continues as if it received that signal. If no signal is specified, the program continues as if no stop occurred.
Examples
detach
detach SIGREQUEST
See Using the dbx Debug Program.
disable Subcommand
disable { Number ... all }
The disable subcommand disables traces and stops associated with debug events. The traces and stops to be disabled can be specified through the Number parameters, or all traces and stops can be disabled by using the all flag. Use the status subcommand to display the event numbers associated by the dbx debug program with a trace or stop.
Flags
Item | Description |
---|---|
all | Removes all traces and stops. |
Examples
disable all
disable 4
For more information, see enable subcommand, delete subcommand, and status subcommand.
Also, see Setting and Deleting Breakpoints in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
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:
OR
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.
Item | Description |
---|---|
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. |
Df | Prints a double-precision decimal float number. |
DDf | Prints a quadruple-precision decimal float number. |
f | Prints a single-precision real number. |
g | Prints a double-precision real number. |
h | Prints a byte in hexadecimal. |
Hf | Prints a single-precision decimal float number. |
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. |
p | Prints the address/pointer in hexadecimal. |
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
Item | Description |
---|---|
>File | Redirects output to the specified file. |
Examples
0x3fffe460 / X
&y / 2c
&a_string + 5, &a_string + 7/c
See Examining Memory Addresses in AIX Version 7.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
down
down 3
See the up subcommand, the where subcommand, and Displaying a Stack Trace in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
dump Subcommand
dump [ Procedure | "PATTERN" ] [ >File ]
The dump subcommand displays the names and values of all variables in the specified procedure or those variables that match with the specified pattern. If the Procedure parameter is a period (.), then all active variables are displayed. If the Procedure nor "PATTERN" parameter is specified, the current procedure is used. The "PATTERN" parameter is a wildcard expression with the *, ?, and [] meta-characters. When "PATTERN" is used, it displays all the matching symbols in the global space (from all the procedures). If the >File flag is used, the output is redirected to the specified file.
Flags
Item | Description |
---|---|
>File | Redirects output to the specified file. |
Examples
dump
dump add_count
dump "s*"
dump > var.list
See Displaying and Modifying Variables in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
edit Subcommand
edit [ Procedure | File ]
The edit subcommand starts an editor on the specified file. The file might be specified through the File parameter or by specifying the Procedure parameter, where the editor is started on the file containing that procedure. If no file is specified, the editor is started 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 required editor.
Examples
edit
edit main.c
edit do_count
See the list subcommand, the vi or vedit command.
enable Subcommand
enable { Number ... all }
The enable subcommand enables traces and stops associated with debug events. The traces and stops to be enabled can be specified through the Number parameters, or all traces and stops can be enabled by using the all flag. Use the status subcommand to display the event numbers associated by the dbx debug program with a trace or stop.
Flags
Item | Description |
---|---|
all | Removes all traces and stops. |
Examples
enable all
enable 4
For more information, see disable subcommand, delete subcommand, status subcommand.
Also, see Setting and Deleting Breakpoints in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
fd Subcommand
fd [ raw ] [ start [ end ] ]
The fd subcommand displays file descriptor information. Using the raw option causes output to be displayed in raw hex format. Other optional arguments include start and end indices. If no index is given, then information about all available file descriptors is displayed. Use of one index displays a single file descriptor; two an inclusive range.
Examples
fd raw
fd 3 5
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
file main.c
file
See the func subcommand. Also, see Changing the Current File or Procedure and Displaying the Current File in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
frame Subcommand
frame [ num ]
The frame subcommand changes the current function to the function corresponding to the specified stack frame number num. The current function is used for resolving names. The numbering of the stack frames starts from the currently active function stack frame (the function frame that is currently active is always numbered 0). If there are n frames, the frame of the main function is numbered n-1. When no frame number is specified, information about the function associated with the current frame is displayed.
Examples
frame 2
frame
See the up and down subcommands. Also, see Changing the Current File or Procedure and Displaying a Stack Trace in AIX Version 7.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
func do_count
func
See the file subcommand. Also, see Changing the Current File or Procedure in AIX Version 7.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.
handler Subcommand
handler { atfork | cancel_cleanup [ all | pthread id ] }
The handler subcommand displays information about atfork or cancelation cleanup handlers registered using pthread_atfork, and pthread_cleanup_push, respectively. Using the atfork option, the names of routines registered as pre, parent and child atfork handlers are displayed (with their respective arguments in the case of non-posix compliant atfork handlers). The cancel_cleanup option causes display of all registered cancelation cleanup handlers, with an optional pthread id parameter specifying a particular pthread, or all specifying all pthreads. If none is given, then the cancelation cleanup handlers for the current pthread are displayed, if there are any.
Examples
handler atfork
handler cancel_cleanup
handler cancel_cleanup 2
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. You do not need to provide the entire topic string with the help subcommand. The dbx program can recognize the topic if you provide a substring starting from the beginning of the topic. The following topics are available:
Item | Description |
---|---|
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
help
help list
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:
Signal names are not case-sensitive. The SIG prefix is optional.
If the SignalNumber and the SignalName parameters are 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 debugger. If no arguments are specified, the list of currently ignored signals are 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 7.1 General Programming Concepts: Writing and Debugging Programs.
kthread Subcommand
kthread [ raw ] [ info | ru ] [ tid ]
The kthread subcommand displays information about kernel threads. Using the raw option causes all output to be displayed in hex, regardless of whether it can be displayed in a more human-readable format. Using no arguments, summary information about all kernel threads is printed. Supplying a numeric thread ID causes dbx to show information about a single thread. The info option produces more detailed output about a thread, from the user thread structure. Use of the ru option displays the ti_ru data member, which contains resource usage information.
For more information about user threads, see thread subcommand.
Examples
kthread
Threads
that were running (or runnable) just before dbx stopped the process
are marked with an asterisk. Choose the correct thread ID based on
the output and type: kthread info tid
kthread raw ru
limitbp Subcommand
limitbp ( bp1, Limit ) [ ( bp2, [ + ] Limit ) … ]
The limitbp subcommand instructs the dbx command to stop running the debug program only when the breakpoint is executed a specified number of times. If the '+' character precedes the limit, the limit of that event is changed to the sum of the limit that is specified in the subcommand and the count of the number of times that the event is already executed. That is, the dbx command stops running the debug program when the breakpoint is about to be executed for the specified Limit after the limitbp subcommand is already run.
Examples
limitbp (1, 10)
limitbp (1, 15) (2, 20)
limitbp (1, +20)
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:
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.
The SourceLine-Expression parameter must 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) might be used to denote the current line number; a SourceLine of @ (at sign) might 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
list 1,10
list main
list $-5,$+5
(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 7.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:
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® family 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
Item | Description |
---|---|
at SourceLine | Specifies a starting source line for the listing. |
Examples
listi
listi at 10
listi at "sample.c":5
listi 0x10000400, 0x10000420
See the list subcommand and the set subcommand. Also, see Debugging at the Machine Level with dbx in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
malloc Subcommand
malloc [ > File ]
The malloc subcommand with no options prints out a list of enabled options and allocation policies as well as a statistical summary of malloc usage since process startup.
malloc [ allocation [ { address | size | heap | pid | tid | time } { "<" | "==" | ">" "!=" | “~=” ]} Value ] ] [ > File ]
The allocation option to the malloc subcommand displays a sorted list of all the allocations currently held by the process. Using an optional attribute RELOP value argument allows for a more narrow selection of active allocations.
malloc [ freespace [ { address | size | heap } { "<" | "==" | ">" | "!=" | “~=”]} Value ] ] [ > File ]
The freespace option to the malloc subcommand displays a sorted list of all the free space available in the process heap. Using an optional attribute RELOP value argument allows for a more narrow selection of free space nodes.
malloc address
The malloc subcommand with address displays the nodes details of the address, the address need not be a starting address of an allocated or free node.
Flags
Item | Description |
---|---|
> File | Redirects output to the specified file. |
For more information, see System Memory Allocation Using the malloc Subsystem in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
map Subcommand
map { [Format] [ entry ModuleNumber [ , ModuleNumber ] | Address | SymbolName ] [for $tthreadnumber] [ > File ] }
When called without one of the above specifications, the map subcommand displays information for all loaded portions of the application.
Item | Description |
---|---|
abbr | Specifies the abbreviated output mode, which consists of a single line for each loaded module containing the entry number, module name, and optional member name for that module. |
normal | Specifies the normal output mode, which consists of the entry number, module name, member name, text origin, text length, data origin, data length, and file descriptor for each loaded module. If the loaded module has TLS data, the TLS data origin and TLS data length are also displayed. |
raw | Specifies the raw output mode, which consists of a single unformatted line for each module containing the following space-separated fields: entry number, module name with optional member name, text origin, text end, text length, data origin, data end, data length, and file descriptor. If the loaded module has TLS data, the TLS data origin, TLS data end, and TLS data length are also displayed. |
verbose | Specifies the verbose output mode, which consists of the entry number, module name, member name, text origin, text end, text length, data origin, data end, data length, and file descriptor for each loaded module. If the loaded module has TLS data, the TLS data origin, TLS data end, and TLS data length are also displayed. |
If no Format parameter is specified, DBX uses the value of the $mapformat internal variable. If no Format parameter is specified and $mapformat is unset, DBX displays loaded module information in normal mode.
The TLS data information of the specified thread is displayed if the loaded module has TLS data. If no thread is specified, the current thread is used.
Flags
Item | Description |
---|---|
> File | Redirects output to the specified file. |
entry ModuleNumber [ , ModuleNumber ] | Specifies the module or range of modules to be displayed. |
for $t threadnumber | Specifies the thread number. |
Examples
map abbr
map verbose entry 3,5
map 0x20001000
map example
map normal for $t2
For more information, see the $mapformat internal variable. See also, Debugging at the Machine Level with dbx in AIX Version 7.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
move 12
move "sample.c":5
See the list subcommand. Also, see Displaying the Current File in AIX Version 7.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 exceed processes are created. The on flag is used to specify that a new dbx session is created to debug the child path of a fork. The original dbx continues 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 exceed process. The off flag disables multiprocess debugging. If no flags are specified, the multproc subcommand returns the status of multiprocess debugging.
The dbx program uses the X Window System 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 the X Window System handling techniques to activate the window where the dbx session is displayed. If the system does not have the X Window System support, a warning message is issued when the debugger forks, and the dbx program continues debugging only the parent process. Multiprocess debugging can also be unsuccessful for the following reasons:
If $xdisplay is set to a remote display, the user might not be able to see the newly created Xwindow. If the $xdisplay setting is not correct, the X Window System 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
Item | Description |
---|---|
on | Enables multiprocess debugging. |
off | Disables multiprocess debugging. |
Examples
multproc
multproc on
multproc off
See the screen subcommand and the fork subroutine. Also, see Debugging Programs Involving Multiple Processes in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
mutex Subcommand
mutex [ lock | unlock | thnum | utid | 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:
Item | Description |
---|---|
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. |
blockers | List the user threads which are blocked on this mutex variable. |
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
Item | Description |
---|---|
lock | Displays information about locked mutexes. |
unlock | Displays information about unlocked mutexes. |
thnum | Displays information about all the mutexes held by a particular thread. |
utid | Displays information about all the mutexes held by a user thread whose user thread id matches the user thread id. |
Examples
mutex
mutex lock
mutex 4 5 6
The output is similar
to: mutex obj_addr type lock owner blockers
$m4 0x20003274 non-rec no
$m5 0x20003280 recursi no
$m6 0x2000328a fast no
mutex thnum 1
mutex utid 0x0001
See the attribute subcommand, the condition subcommand, the print subcommand, and the thread subcommand.
Also, see. Using Mutexes AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
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 multithreaded 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 want to step the running thread only, use the set subcommand to set the variable $hold_next. Setting this variable might result in deadlock since the running thread might wait for a lock held by one of the blocked threads.
Examples
next
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 runs. If the Number parameter is not specified, nexti runs once only.
If you use the nexti subcommand in a multithreaded 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 want to step the running thread only, use the set subcommand to set the variable $hold_next. Setting this variable might result in deadlock since the running thread might wait for a lock held by one of the blocked threads.
Examples
nexti
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 7.1 General Programming Concepts: Writing and Debugging Programs.
onceblock Subcommand
onceblock [ uninit | done ]
The onceblock subcommand displays information about blocks of initialization code registered using the pthread_once routine. With no arguments, information about all registered once blocks are shown. The optional uninit and done flags display only the once blocks that either have not, or have already executed, respectively, while supplying a numeric once ID displays information for a single once block.
Examples
onceblock uninit
plugin Subcommand
plugin [ Name [ Command ] ]
The plugin subcommand passes the command specified by the Command parameter to the plug-in specified by the Name parameter. If no parameters are specified, the names of all available plug-ins are displayed.
Examples
plugin
plugin sample help
plugin xyz interpret 0x20000688
See the pluginload subcommand and pluginunload subcommand. Also see Developing for the dbx Plug-in Framework in AIX Version 7.1 General Programming Concepts.
pluginload Subcommand
pluginload File
Examples
pluginload /home/user/dbx_plugins/libdbx_sample.so
See the plugin subcommand and pluginunload subcommand. Also see Developing for the dbx Plug-in Framework in AIX Version 7.1 General Programming Concepts.
pluginunload Subcommand
pluginunload Name
The pluginunload subcommand unloads the plug-in specified by the Name parameter.
Examples
pluginunload sample
See the plugin subcommand and pluginload subcommand. Also see Developing for the dbx Plug-in Framework in AIX Version 7.1 General Programming Concepts.
print Subcommand
print Expression ...
print Procedure ( [ Parameters ] )
The print subcommand does either of the following operations:
Examples
print x, y << 2
print sbrk(0)
See the assign subcommand, the call subcommand, and the set subcommand.
printbp Subcommand
printbp [ bp1 ] [ bp2 ] ... | all
The printbp subcommand instructs the dbx command to print the number of times that each of the breakpoints or all the subcommands were run and the details of the limit on the breakpoint, if a limit was set on it.
Examples
printbp 1
printbp 1, 2
printbp all
proc Subcommand
proc [ raw ] [ cred | cru | ru | sigflags | signal ]
The proc subcommand displays information about the process. Usage of the raw option causes output to be displayed in raw hex, rather than interpreting values in a more human-readable fashion. Using the proc subcommand with no additional arguments outputs general information about the process, as is stored in the user process data structure. The cred option displays contents of the pi_cred data member, which describes the credentials of the process. The cru and ru options display data members pi_cru and pi_ru respectively, which contain resource usage information. The sigflags and signal options display information relating to the current signal status and registered signal handlers, as contained within the pi_sigflags and pi_signal data members.
Examples
proc raw ru
proc signal
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 7.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 [ ALL | $tthreadnumber … ] [ >File ]
The registers subcommand displays the values of general-purpose registers, system control registers, floating-point registers, vector registers, and the current instruction register.
Note: The register value might be set to the 0xdeadbeef hexadecimal value. The 0xdeadbeef hexadecimal value is an initialization value assigned to general-purpose registers at process initialization.
Flag
Item | Description |
---|---|
>File | Redirects output to the specified file. |
See the set subcommand and the unset subcommand. Also, see Using Machine Registers in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
Example
registers $t1 $t2 $t3
See the set subcommand and the unset subcommand. Also, see Using Machine Registers in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
rerun Subcommand
rerun [ Arguments ] [ < File ] [ > 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
Item | Description |
---|---|
<File | Redirects input so that input is received from File. |
>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.
resource Subcommand
resource { owner | waiter } [ all | pthread id ]
The resource subcommand displays information about which resources pthreads currently hold or are waiting on. The first argument, which is required, indicates whether you are interested in viewing pthreads that own resources or are waiting for them. The second argument can be used to indicate all pthreads, or a specific one. If none is given, then only information relevant to the current pthread is displayed, if applicable.
Examples
resource owner
resource waiter all
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
return
return main
rwlock Subcommand
rwlock [read | write | RwlockNumber....]
The rwlock subcommand displays information about rwlocks. If the RwlockNumber parameter is given, the rwlock subcommand displays information about the specified rwlocks. If no flags or parameters are specified, the rwlock subcommand displays information about all rwlocks.
The information for each rwlock is as follows:
Item | Description |
---|---|
rwl | Indicates the symbolic name of the rwlock, in the form $rw RwlockNumber. |
flag_value | Indicates the flag value. |
owner | Indicates the owner of the rwlock |
status | Indicates who is holding the rwlock. The values are read (if held by reader), write (if held by writer), free (if free). |
wsleep[#] | Indicates threads blocking in write. # indicates the total number of threads blocking in write. |
rsleep[#] | Indicates threads blocking in read. # indicates the total number of threads blocking in read. |
Note: The print subcommand of the dbx debug program recognizes symbolic rwlock names, and can be used to display the status of the corresponding object
Flags
Item | Description |
---|---|
read | Displays information about all rwlocks whose status is in read mode. |
write | Displays information about all rwlocks whose status is in write mode. |
Examples
rwlock
The output is similar to:
rwl flag_value owner status
$rwl 1 $t1 write
rsleeps[ 0]:
wsleeps[ 0]:
rwlock write
The output is similar to:
rwl flag_value owner status
$rwl 1 $t1 write
rsleeps[ 0]:
wsleeps[ 0]:
See the attribute subcommand, the condition subcommand, mutex subcommand, the print subcommand, and the thread subcommand
run Subcommand
run [ Arguments ] [ <File ] [ >File ] [ > >File ] [ 2>File ] [ 2> >File ] [ >&File ] [ > >&File ]
The run subcommand starts the object file. The Arguments are passed as command-line arguments.
Flags
Item | Description |
---|---|
<File | Redirects input so that input is received from File. |
>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 the X Window System 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 was not given. The screen subcommand can also be unsuccessful in the following situations:
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, you might not be able to see the newly created Xwindow. If the $xdisplay setting is not correct, the X Window System 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 7.1 General Programming Concepts: Writing and Debugging Programs and AIXwindows Overview, in AIX Version 6.1 AIXwindows Programming Guide.
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 must 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:
Item | Description |
---|---|
$catchbp | Catches breakpoints during the execution of the next command. |
$codepage | Specifies the code set to use for interpreting characters within the program. When specified with a valid code page, all characters are read from the specified code set and converted to the code set in use by the current environment. |
$deferevents | Turns on the deferred events feature. |
$display_address_name | Displays the member variable identifiers and the memory address that it occupies when examining a set of memory addresses that are using the dbx 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 might result in deadlock since the running thread mgiht wait for a lock held by one of the blocked threads. |
$ignoreifhandler | Does not stop when your program receives a signal which has a registered handler. |
$ignoreload | Does not stop when your program performs the load, unload, or loadbind subroutine. |
$ignorenonbptrap | Does not stop when your program encounters a non-breakpoint trap instruction and has a registered SIGTRAP handler. |
$instructionset | Overrides the default disassembly mode. The following list
contains possible values for the Expression parameter:
If no value is set for the Expression parameter, the dbx program uses the default disassembly mode. |
$java | When set, also sets the following variables, placing dbx in
a mode to debug Java applications.
When unset, also unsets the following variables:
|
$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. |
$mapformat | Specifies the default output mode for the map subcommand.
|
$mnemonics | Changes the set of mnemonics to be used by the dbx program
when disassembling.
If no value is set for the Expression parameter, the dbx program uses 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. |
$novregs | Omits the display of vector registers from the registers subcommand. |
$novsregs | Omits the display of vector scalar registers from the registers subcommand |
$octint | Interprets addresses in octal. |
$octints | Prints integers in octal. |
$pretty | Displays complex C and C++ data structure (struts, unions,
arrays) values in a pretty printed format with the print subcommand.
|
$print_dynamic | Displays the dynamic type of the C++ objects with print / dump command. By default this variable is not set. |
$repeat | Repeats the previous command if no command was entered. |
$sigblock | Blocks signals to your program. |
$show_vft | Displays Virtual Function Table while printing C++ objects with print / dump command. By default it is not set. |
$stack_details | Displays the frame number and the register set for each active function or procedure displayed by the where subcommand. |
$stepignore | Controls how the dbx command behaves when the step/tstep subcommand
runs on a source line that calls another routine for which no debugging
information is available. This variable enables the step/tstep subcommand
to step over large routines for which no debugging information is
available. The following list contains possible values for the Expression parameter:
|
Item | Description |
---|---|
$thcomp | When $thcomp is set, the information displayed by the thread command th- is shown in a compressed format. |
$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 might 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 the X Window System, 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
set $listwindow=20
set $unsafeassign
set $instructionset="601"
set $codepage="IBM-eucCN"
See the unset subcommand. Also, see Changing Print Output with Special Debug Program Variables in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
set edit [vi, emacs] or set -o [vi, emacs] Subcommand
The set subcommand with the -o or edit option might be used to turn on one of the line edit modes. If the set-o vi or set edit vi command is given, you are placed in the input mode of the vi line editor. If the set -o emacs or set edit emacs command is given, you are placed in the input mode of the emacs line editor.
Example
set-o vi
or
set edit vi
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
sh ls
sh
sh echo $SHELL
See Running Shell Commands from dbx in AIX Version 7.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 7.1 General Programming Concepts: Writing and Debugging Programs.
status Subcommand
status [ more ] [ >File ]
The status subcommand displays all user-defined breakpoints, tracepoints, and watchpoints, in addition to the remaining thread tskip counts (set by using the tskip subcommand). If the more parameter is specified, the status subcommand also displays the dbx subcommands associated with the breakpoints, tracepoints, and watchpoints. The status subcommand lists enabled events with square brackets ([]) surrounding the event number, disabled events with periods (..) surrounding the event number, and deferred events with angle brackets (<>) surrounding the event number.
The > flag sends the output of the status subcommand to a file specified in the File parameter.
Flag
Item | Description |
---|---|
>File | Redirects output to File. |
Examples
status
The output is similar to: [1] stop at 13
[2] stop at 14
.3. stop at 15
.4. stop at 16
[5] stop at 17 ( count = 0, limit = 3 )
<6> stop at 18 if g > 10
<7> stop in func
Remaining tskip counts:
tskip 2 for $t1
tskip 1 for $t5
In the example output, events 3 and 4
are disabled, and events 6 and 7 are deferred.status more
The
output is similar to: [1] stop at 13
[1] where
.2. stop at 14
[1] where
[2] registers
<3> stop at 15 if g > 10
[1] where; registers
See the addcmd subcommand, the clear subcommand, the delete subcommand, the delcmd subcommand, the tskip subcommand, the stop subcommand, and the trace subcommand for the dbx command.
Also, see Setting and Deleting Breakpoints in AIX Version 7.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 multithreaded 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 want to step the running thread only, use the set subcommand to set the variable $hold_next. Setting this variable might result in deadlock since the running thread might wait for a lock held by one of the blocked threads.
Examples
step
step 5
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 multithreaded application program, the stepi subcommand steps the running thread only. All other user threads remain stopped.
Examples
stepi
stepi 5
See the gotoi subcommand, the nexti subcommand, and the step subcommand.
stop Subcommand
stop { [Variable ] [ at SourceLine | in Procedure | on load ["ModuleName"] ] [ if Condition ]} [ "{ "Limit" }" ]
The stop subcommand halts the application program when certain conditions are fulfilled. The program is stopped when:
The SourceLine variable can be specified as an integer or as a file name string followed by a : (colon) and an integer.
ModuleName(MemberName)
You can set the Limit parameter to instruct the dbx command to ignore a condition for a specified number of times. In other words, the Limit parameter specifies the number of times that the specified condition must be fulfilled before the debug program execution is stopped.
After any of these commands, the dbx debug program responds with a message reporting the event it 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 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
stop in func
<3> stop in func
stop g
<4> stop g
stop in getdata {3}
[5] stop in getdata ( count = 0, limit = 3 )
The numbers in square 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 which event caused the program to stop. The numbers in angle brackets (<>) are the event identifiers for the deferred events. A deferred event is an event without having any breakpoint, tracepoint, or watchpoint associated with it, and is created whenever the input command involves the symbols that are not currently loaded in the memory. A normal event displayed in square brackets ([]) is also converted into a deferred event whenever the corresponding module is unloaded. Whenever the module corresponding to the deferred event is loaded into the memory, the deferred event is converted into the normal event, and the corresponding breakpoint, tracepoint, or watchpoint is created. The events that you create coexist with internal events that are created by the dbx command, so the event numbers might not always be sequential.
A limit can be associated with an event after its creation by using the limitbp subcommand. To view the limit associated with an event, the printbp subcommand can be used.
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, or use the enable or disable subcommands. Use the addcmd subcommand to add dbx subcommands to the specified event number and delcmd to delete the associated dbx subcommands from the specified event number.
In a multithreaded application program, all user threads are halted when any user thread hits a breakpoint. A breakpoint set on a source line or function is hit by any user thread which executes the line or function, unless you specify conditions as shown in example 9 below. The following aliases specify the conditions automatically:
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 in the following example:
stopi at &Function if ($running_thread == ThreadNumber)
stop at SourceLine if ($running_thread == ThreadNumber)
Flags
Item | Description |
---|---|
at SourceLine | Specifies the line number. |
if Condition | Specifies the condition, such as true. |
in Procedure | Specifies the procedure to be called. |
on load ModuleName | Specifies the loaded module to be monitored. |
Examples
stop in main
stop x at 12
stop at "sample.c":5
stop in func1 if x = 22
stopi at &func1 if x = 22
stop Variable
stop if (x > y) and (x < 2000)
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.stopi at &func1 if ($running_thread == 5)
or
bfth(func1, 5)
stop on load
stop on load "Module"
stop on load "Module(Member)"
stop in getdata {3}
See the addcmd subcommand, the clear subcommand, the delete subcommand, the delcmd subcommand, disable subcommand, enable subcommand, the limitbp subcommand, the printbp subcommand, the status subcommand, the stopi subcommand, and the trace subcommand. Also, see Setting and Deleting Breakpoints in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
stophwp Subcommand
stophwp Address Size
Example
stophwp 0x200004e8 4
See the tracehwp subcommand.
stopi Subcommand
stopi { [Address] [ at Address | in Procedure ] [ if Condition ]}
The stopi subcommand sets a stop at the specified location:
Flags
Item | Description |
---|---|
if Condition | Specifies the condition, such as true. |
in Procedure | Specifies the procedure to be called. |
at Address | Specifies the machine instruction address. |
Examples
stopi at 0x100020f0
stopi 0x100020f0
stopi 0x200020f0 if ($running_thread == 1)
See the stop subcommand. Also, see Debugging at the Machine Level with dbx in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
thdata Subcommand
thdata [ $tthreadnumber [ all | key1 … ] … ] | [ all ]
Command | Action |
---|---|
thdata [ all ] | Prints the thread-specific data that is associated with all the keys for all the available threads. |
thdata $t1 [ all ] | Prints the thread-specific data that is associated with all the keys for the $t1 thread. |
thdata $t1 key1 key2 | Prints the thread-specific data that is associated with the keys key1 and key2 for the $t1 thread. |
thdata $t1 key1 key2 $t2 key1 | Prints the thread-specific data that is associated with the keys key1 and key2 for the $t1 thread, and the thread-specific data that is associated with the key key1 for the $t2 thread. |
Examples
(dbx) thdata $t1
Thread : 1
Key : 1 Data pointer : 0x200f7a28
Key : 2 Data pointer : 0x200f7aa8
Key : 3 Data pointer : 0x200f7ac4
(dbx)
(dbx) thdata $t1 2 3 $t2
Thread : 1
Key : 2 Data pointer : 0x200f7aa8
Key : 3 Data pointer : 0x200f7ac4
Thread : 2
Key : 2 Data pointer : 0x200f7b24
Key : 3 Data pointer : 0x200f7ba4
(dbx)
See Thread-Specific Data in 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 ... ]
Help for the options displayed
thread { help}
The thread subcommand displays and controls user threads.
The first form of the thread subcommand can display information in two formats. If the thread subcommand is th, then the information displayed is in the first format. If the thread subcommand is th -, then the information displayed is in the second format. 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 in both the formats is described below.
The information displayed by the thread subcommand in the first format is as follows:
Item | Description |
---|---|
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 information displayed by the thread subcommand in the second format is given below. By default, for the thread subcommand th -, the information is displayed in the long form.
Item | Description |
---|---|
thread | Indicates the symbolic name of the user thread, in the form $tThreadNumber. |
Kernel thread-related information
Item | Description |
---|---|
tid | Indicates the user thread identifier (if the user thread is attached to a kernel thread). |
pri | Indicates the priority of the kernel thread. |
sched | Indicates the scheduling policy of the kernel thread. This value can be fif, oth, rr, for fifo, other, or round robin scheduling policies. |
state | Indicates the state of the kernel thread (if the user thread is attached to a kernel thread). This value can be run, wait, susp, or zomb, for running, waiting, suspended, or zombie. |
User thread-related information
Item | Description |
---|---|
tid | Indicates the user thread identifier. |
pri | Indicates the priority of the userl thread. |
sched | Indicates the scheduling policy of the user thread. This value can be fif, oth, rr, for fifo, other, or round-robin scheduling policies. |
state | Indicates the state of the user thread. This value can be running, creating, suspended, blocked, runnable, or terminated. |
state | Indicates the user state in hex. |
flags | Indicates the values for pthread flags in hex. |
wchan | Indicates the event on which the kernel thread is waiting or sleeping (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 is held. |
scope | Indicates the contention scope of the user thread; this value can be sys or pro for system or process contention scope. |
cancelation |
|
Item | Description |
---|---|
joinable | Indicates whether the thread can be joined or not. |
boosted | Indicates the boosted value of the thread. |
function | Indicates the name of the user thread function. |
cursig | Indicates the current signal value. |
If the option set $thcomp is set, then the information is displayed in the compressed form as shown in the following example.
m mode (k)ernel (u)ser
k k-state (r)unning (w)aiting (s)uspended (z)ombie
u u-state (r)unning (R)unnable (s)uspended (t)erminated
(b)locked (c)reating
h held (yes) (n)o
s scope (s)ystem (p)rocess
c cancellation not pending: (e)nabled & (d)eferred,
(e)nabled & (a)sync, (d)isabled
pending : (E)nabled & (D)eferred,
(E)nabled & (A)sync, (D)isabled
j joinable (yes) (n)o
b boosted value of boosted field in pthread structure
plk kernel thread (oth)er (fif)o (rr)-> round-robin
policy
plu user thread (oth)er (fif)o (rr)-> round-robin
policy
prk kernel thread hex number
policy
pru user thread hex number
policy
k-tid kernel thread id in hex
u-tid pthread id in hex
fl value of flags field in pthread structure in hex
sta value of state field in pthread structure in hex
cs value of the current signal
wchan event for which thread is waiting
function function name
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 is not 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
Item | Description |
---|---|
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. |
help | Displays all the information about the thread options that are shown when th - command is used. |
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.
All the previous flags take [-] option. If this option is given, then the thread information displayed is in the second format and in the long form unless the set $thcomp option is set. |
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
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
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
thread current 4
thread hold 2
thread wait -
The output is similar to:
thread m k u h s c j b kpl upl kpr upr k_tid u_tid fl sta wchan function
*$t1 u r w n p ed y 0 oth oth 61 1 0043e5 000001 51 004 main
$t3 u r w n p ed y 0 oth oth 61 1 001fe9 000102 51 004 iothread
>$t4 u r r n p ed y 0 oth oth 61 1 0025c5 000203 50 064 save_thr
thread - 1 2 3
The output is similar to:
thread m k u h s c j b kpl upl kpr upr k_tid u_tid fl sta wchan function
*$t1 u r w n p ed y 0 oth oth 61 1 0043e5 000001 51 004 main
$t3 u r w n p ed y 0 oth oth 61 1 00fe9 000102 51 004 iothread
>$t4 u r r n p ed y 0 oth oth 61 1 0025c5 000203 50 064 save_thr
See the attribute subcommand, the condition subcommand, the mutex subcommand, the print subcommand, the registers subcommand, and the where subcommand.
Also, see Creating Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
tls Subcommand
tls map
The tls subcommand takes only one flag that it uses to display the TLS initialization template origin and length for each loaded TLS module.
tnext Subcommand
tnext [Number]
The tnext subcommand runs the running thread up to the next source line. The Number parameter specifies the number of times the tnext subcommand runs. If the Number parameter is not specified, tnext runs once only. This subcommand can be started only on system-scope threads.
All the threads are run during this operation. To catch breakpoints during this operation, set the $catchbp dbx variable. If the $catchbp variable is set and a breakpoint is reached for another thread, the tnext subcommand is not repeated for the remaining number of times.
Examples
tnext
tnext 3
See the tnexti subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
tnexti Subcommand
tnexti [Number]
The tnexti subcommand runs the running thread up to the next instruction. The Number parameter specifies the number of times the tnexti subcommand runs. If the Number parameter is not specified, tnexti runs once only. This subcommand can be started only on system-scope threads.
All the threads are run during this operation. To catch breakpoints during this operation, set the $catchbp dbx variable. If the $catchbp variable is set and a breakpoint is reached for another thread, the tnexti subcommand is not repeated for the remaining number of times.
Examples
tnexti
tnexti 3
See the tnext subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
trace Subcommand
trace [ SourceLine | Expression at SourceLine | Procedure | [ Variable ] [ at SourceLine | in Procedure ] | on load ModuleName ] [ 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. You can enable and disable traces using the enable and disable subcommands, respectively.
ModuleName(MemberName)
If the on load flag is used without the ModuleName parameter, dbx traces the load and unload of all modules.
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 below.
Flags
Item | Description |
---|---|
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. |
on load ModuleName | Specifies the load module to be monitored. |
Examples
trace printf
trace "hello.c":22
trace x in main
set $A=0x2004000
trace $A
Note: The tracei subcommand is designed to trace addresses.
(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 }
(dbx) trace sub
[1] trace sub
(dbx) run
calling sub(s = "hello", a = -1, k = delete) from function main
returning "hello" from sub
(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
(dbx) trace x if ($running_thread == 1)
trace on load
trace on load "Module"
trace on load "Module(Member)"
Also, see the tracei subcommand.
tracehwp Subcommand
tracehwp Address Size
Examples
tracehwp 0x200004e8 4
See the stophwp subcommand.
tracei Subcommand
tracei [ [ Address ] [ at Address | in Procedure ] | Expression at Address ] [ if Condition ]
The tracei subcommand turns on tracing when:
Flags
Item | Description |
---|---|
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
tracei
tracei at 0x100020f0
tracei 0x20004020 in main
tracei at 0x100020f0 if ($running_thread == 4)
See the trace subcommand. Also, see Debugging at the Machine Level with dbx in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
tskip Subcommand
tskip [Number]
The tskip subcommand continues the execution of the running thread from the current stopping point. The number of thread-level breakpoints specified by the Number parameter is skipped for the running thread. This subcommand can be started for system-scope threads only.
All the other threads are run during this operation, and all breakpoints and watchpoints specified by the user are caught. The execution can cease when any thread hits a breakpoint or watchpoint. Even though the execution started by tskip subcommand can stop because of an event for another thread, the tskip count specified for the previous thread is still active and the number of thread-level breakpoints specified by the tskip count is ignored for that thread when the process continues. When the thread ends, the tskip count associated with it is deleted.
Use the status subcommand to view the remaining tskip count for the threads. Use the delete subcommand to delete the remaining tskip count for the threads.
Example
tskip 1
See the cont subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
tstep Subcommand
tstep [Number]
The tstep subcommand runs the specified number of source lines from the current source line for the running thread. The Number parameter specifies the number of times the tstep subcommand runs. If the Number parameter is not specified, tstep runs once only. This subcommand can be started only on system-scope threads.
Examples
tstep
tstep 5
60 printf ("hello world /n");
enter:
set $stepignore="function"; step
See the cont subcommand, the goto subcommand, tnext subcommand, the set subcommand, and the tstepi subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
tstepi Subcommand
tstepi [Number]
The tstepi subcommand runs the specified number of instructions from the current instruction for the running thread. The Number parameter specifies the number of times the tstepi subcommand runs. If the Number parameter is not specified, tstepi runs once only. This subcommand can be started only on system-scope threads.
All the threads are run during this operation. If $hold_next is set, all the threads except the running thread is held.
Examples
tstepi
tstepi 5
See the gotoi subcommand, tnexti subcommand, and the tstep subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
tstop Subcommand
tstop { in Procedure | [Variable] at SourceLine [ if Condition ] } [for $tthreadnumber]
Thread-level breakpoints can be set on system scope threads only. When a thread-level and a process-level breakpoint are hit at the same time, both the breakpoints are processed and the thread-level breakpoint is ported. When the thread terminates, the events associated with it are deleted.
Flags
Item | Description |
---|---|
at SourceLine | Specifies the line number. |
for $t threadnumber | Specifies the thread number. |
if Condition | Specifies the condition (for example, true). |
in Procedure | Specifies the procedure to be called. |
Examples
tstop in func for $t2
tstop x at 12
See the ttrace subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
tstophwp Subcommand
tstophwp address size [for $tthreadnumber]
The tstophwp subcommand sets a thread-level hardware watchpoint stop for the specified memory region. The program stops when the contents of the region changes while running the specified thread. The thread specified must exist at the same time as the creation of the event. The current thread is used if no thread is specified. The thread-level watchpoint events can be set only for system-scope threads. When the thread terminates, the events associated with it are deleted.
Flags
Item | Description |
---|---|
for $t threadnumber | Specifies the thread number. |
Example
To stop the program when thread 2 is running and the contents of the 4-byte memory region starting at address 0x200004e8 change, enter:
tstophwp 0x200004e8 4 for $t2
See the ttracehwp subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
tstopi Subcommand
tstopi { in Procedure | [Address] at Address [ if Condition ] } [for $tthreadnumber]
Thread-level breakpoints can be set on system scope threads only. When a thread-level and a process-level breakpoint are hit at the same time, both the breakpoints are processed and the thread-level breakpoint is reported. When the thread terminates, the events associated with it are deleted.
Flags
Item | Description |
---|---|
at Address | Specifies the machine instruction address. |
for $t threadnumber | Specifies the thread number. |
if Condition | Specifies the condition. |
in Procedure | Specifies the procedure to be called. |
Example
tstopi at 0x100020f0 for $t2
tstopi in func
See the ttracei subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
ttrace Subcommand
ttrace { [Variable] at SourceLine | Procedure } [ if Condition ] [for $tthreadnumber]
The ttrace subcommand prints tracing information when the specified thread runs for the specified procedure, function, source line, and variable. The SourceLine variable can be specified as an integer or as a file name string followed by a colon (:) and an integer. The dbx debug program associates a number with each ttrace subcommand. Use the status subcommand to view these numbers. Use the delete subcommand to turn tracing off. You can enable and disable traces using the enable and disable subcommands, respectively.
The current thread is used if no thread is specified. Thread-level trace can be set only for system-scope threads. The thread specified must exist at the same time as the creation of the event. When the thread ends, the events associated with it are deleted.
Flags
Item | Description |
---|---|
at SourceLine | Specifies the source line where the expression being traced is found. |
for $t threadnumber | Specifies the thread number. |
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 find the procedure or variable being traced. |
Examples
ttrace printf for $t2
ttrace "hello.c":22
See the ttracei subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
ttracei Subcommand
ttracei [Address] at Address [ if Condition ] } [for $tthreadnumber]
The current thread is used if no thread is specified. Thread-level trace can be set only for system-scope threads. The thread specified must exist at the time as the creation of the event. When the thread ends, the events associated with it are deleted.
Flags
Item | Description |
---|---|
at Address | Specifies an address. Tracing is enabled when the instruction at this address is run. |
for $t threadnumber | Specifies the thread number. |
if Condition | Specifies a condition. Tracing is enabled when this condition is met. |
Example
tracei at 0x100020f0 for $t3
tracei at 0x100020f0
See the ttrace subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
ttracehwp Subcommand
ttracehwp address size [for $tthreadnumber]
The ttracehwp subcommand sets a thread-level hardware watchpoint trace for the specified memory region. The dbx debug program prints tracing information when the contents of the region change while running the specified thread. The thread specified must exist at the same time as the creation of the event. The current thread is used if no thread is specified. The thread-level watchpoint events can be set only for system-scope threads. When the thread terminates, the events associated with it are deleted.
Flags
Item | Description |
---|---|
for $t threadnumber | Specifies the thread number. |
Example
To trace each time the contents of the 4-byte memory region starting at address 0x200004e8 change while running thread 2, enter:
ttracehwp 0x200004e8 4 for $t2
See the tstophwp subcommand. Also, see Debugging Programs Involving Multiple Threads in AIX Version 7.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 7.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 7.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
up 2
up 0
See the down subcommand. Also, see Changing the Current File or Procedure, Displaying a Stack Trace in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
use Subcommand
use [ { + | Directory | '['RegularExpression = NewPath']' } ... ]
The use subcommand sets the list of directories to be searched and path mappings to be applied 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 and path mappings to be applied are displayed.
The @ (at-sign) is a special directory 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 must use ./@ in the search path.
The use subcommand uses the + (plus-sign) to add more directories or mappings to the list of directories to be searched. The + represents the current list of directories and mappings when specified as input to the use subcommand. To append a directory or mapping to the end of the current list, the + must be specified before the new directory or mapping. To add a directory to the beginning of the current list, the + must be specified after the new directory or mapping. If you have a directory named +, specify the full-path name for the directory (for example, ./+ or /tmp/+).
The use subcommand interprets strings enclosed in [ and ] (square brackets) which contain an = (equal-sign) as path mappings. These path mappings are used with the special @ directory. They make it easier for the user to express source file locations in the case that entire directory structures of source files are relocated after compilation.
Examples
use . .. /tmp
use . @ ../source
use + /tmp2
use /tmp3 +
use + [/home/developer=/mnt]
use + [/home/developer=/latest] [/home/developer=/stable]
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
whatis x
whatis main
whatis main.x
(dbx) whatis $$status
enum $$status { run, create, delete, suspend };
where Subcommand
where [ all | $tthreadumber [(startframe endframe)] …] [ startframe endframe ] [ >File ]
The where subcommand displays a list of active procedures and functions associated with the frame numbers startframe to endframe. The numbering of the stack frame starts from the currently active function stack frame (which is always numbered 0). If there are n frames, the frame of the main function is numbered n-1. By using the >File flag, the output of this subcommand can be redirected to the specified file.
In the multithreaded environment option all displays the stack details for all available threads. The stack details of individual threads are displayed by specifying the thread number along with where subcommand. If start and end frames for individual threads are not specified, stack frames are displayed by the global start and end frame numbers. Command with no options displays the stack frames of current thread.
Flag
Item | Description |
---|---|
>File | Redirects output to the specified file. |
See the frame subcommand, up subcommand, and down subcommand. Also, see Displaying a Stack Trace in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
Example
where all
where $t1 $t2 $t3
where $t1 $t2(2 3) $t3 1 4
See the frame subcommand, up subcommand, and down subcommand. Also, see Displaying a Stack Trace in AIX Version 7.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 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. see Scoping of Names in in AIX Version 7.1 General Programming Concepts: Writing and Debugging Programs.
Item | Description |
---|---|
a.out | Object file; contains object code. |
core | Contains core dump. |
.dbxinit | Contains initial commands. |