Provides an environment to debug and run programs under the operating system.
dbx [ -a ProcessID ] [ -c CommandFile ] [ -d NestingDepth ] [ -I Directory ] [ -E DebugEnvironment ] [ -k ] [ -u ] [ -F ] [ -r ] [ -x ] [ ObjectFile [ CoreFile ] ]
The dbx command provides a symbolic debug program for C, C++, Pascal, and FORTRAN programs, allowing you to carry out operations such as the following:
The ObjectFile parameter is an object (executable) file produced by a compiler. Use the -g (generate symbol table) flag when compiling your program to produce the information the dbx command needs.
Note: The -g flag of the cc command should be used when the object file is compiled. If the -g flag is not used or if symbol references are removed from the xcoff file with the strip command, the symbolic capabilities of the dbx command are limited.
If the -c flag is not specified, the dbx command checks for a .dbxinit file in the user's $HOME directory. It then checks for a .dbxinit file in the user's current directory. If a .dbxinit file exists in the current directory, that file overrides the .dbxinit file in the user's $HOME directory. If a .dbxinit file exists in the user's $HOME directory or current directory, that file's subcommands run at the beginning of the debug session. Use an editor to create a .dbxinit file.
If ObjectFile is not specified, then dbx asks for the name of the object file to be examined. The default is a.out. If the core file exists in the current directory or a CoreFile parameter is specified, then dbx reports the location where the program faulted. Variables, registers, and memory held in the core image may be examined until execution of ObjectFile begins. At that point the dbx debug program prompts for commands.
The dbx program can display a wide range of expressions. You can specify expressions in the dbx debug program with a common subset of C and Pascal syntax, with some FORTRAN extensions.
The following operators are valid in the debug program:
The following types of operations are valid in expressions in the debug program:
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
The dbx commands provides a command line editing feature similar to those provide 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 entered to a history file .dbxhistory. If the DBXHISTFILE environment variable is not set, the history file used is $HOME/.dbxhistory.
By default, dbx saves the text of the last 128 commands entered. The DBXHISTSIZE environment variable can be used to increase this limit.
-a ProcessID | Attaches the debug program to a process that is running. To attach the debug program, you need authority to use the kill command on this process. Use the ps command to determine the process ID. If you have permission, the dbx program interrupts the process, determines the full name of the object file, reads in the symbolic information, and prompts for commands. |
-c CommandFile | Runs the dbx subcommands in the file before reading from standard input. The specified file in the $HOME directory is processed first; then the file in the current directory is processed. The command file in the current directory overrides the command file in the $HOME directory. If the specified file does not exist in either the $HOME directory or the current directory, a warning message is displayed. The source subcommand can be used once the dbx program is started. |
-d NestingDepth | Sets the limit for the nesting of program blocks. The default nesting depth limit is 25. |
-F | 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 on initiation of dbx session. In this mode, dbx will not read local variables and types whose symbolic information has not been read. Therefore, commands such as whereis i may not list all instances of the local variable i in every function. |
-I Directory | (Uppercase i) Includes directory specified by the Directory variable in the list of directories searched for source files. The default is to look for source files in the following directories: |
-E DebugEnvironment | Specifies the environment variable for the debug program. |
-k | Maps memory addresses; this is useful for kernel debugging. |
-r | Runs the object file immediately. If it terminates successfully, the
dbx debug program is exited. Otherwise, the debug program is entered and the
reason for termination is reported.
Note: Unless -r is specified, the dbx command prompts the user and waits for a command. |
-u | Causes the dbx command to prefix file name symbols with an @ (at sign). This flag reduces the possibility of ambiguous symbol names. |
-x | Prevents the dbx command from stripping _ (trailing underscore ) characters from symbols originating in FORTRAN source code. This flag allows dbx to distinguish between symbols which are identical except for an underscore character, such as xxx and xxx_ . |
$ cc -g samp.c -o sampWhen 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 dumpedTo determine the location where the error occurred, enter:
$ dbx sampThe 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 will never terminate because i is never incremented. Compile looper.c with the -g flag to get symbolic debugging capability:
$ cc -g looper.c -o looperRun looper from the command line and perform the following steps to attach dbx to the program while it is running:
ps -u UserIDwhere 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 had been originally started with dbx.
$dbx -I /home/user/src -I /home/group/src objfile
The use subcommand may be used for this function once dbx is started. The use command resets the list of directories, whereas the -I flag adds a directory to the list.
$ dbx -r sampThe 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
Note: The subcommands can only be used while running the dbx debug program.
/ | Searches forward in the current source file for a pattern. |
? | Searches backward in the current source file for a pattern. |
alias | Creates aliases for dbx subcommands. |
assign | Assigns a value to a variable. |
attribute | Displays information about all or selected attributes objects. |
call | Runs the object code associated with the named procedure or function. |
case | Changes how the dbx debug program interprets symbols. |
catch | Starts trapping a signal before that signal is sent to the application program. |
clear | Removes all stops at a given source line. |
cleari | Removes all breakpoints at an address. |
condition | Displays information about all or selected condition variables. |
cont | Continues application program execution from the current stopping point until the program finishes or another breakpoint is encountered. |
delete | Removes the traces and stops corresponding to the specified event numbers. |
detach | Continues execution of application and exits the debug program. |
display memory | Displays the contents of memory. |
down | Moves the current function down the stack. |
dump | Displays the names and values of variables in the specified procedure. |
edit | Starts an editor on the specified file. |
file | Changes the current source file to the specified file. |
func | Changes the current function to the specified procedure or function. |
goto | Causes the specified source line to be the next line run. |
gotoi | Changes the program counter address. |
help | Displays help information for dbx subcommands or topics. |
ignore | Stops trapping a signal before that signal is sent to the application program. |
list | Displays lines of the current source file. |
listi | Lists instructions from the application program. |
map | Displays information about load characteristics of the application. |
move | Changes the next line to be displayed. |
multproc | Enables or disables multiprocess debugging. |
mutex | Displays information about all or selected mutexes. |
next | Runs the application program up to the next source line. |
nexti | Runs the application program up to the next machine instruction. |
Prints the value of an expression or runs a procedure and prints the return code of that procedure. | |
prompt | Changes the dbx command prompt. |
quit | Stops the dbx debug program. |
registers | Displays the values of all general-purpose registers, system-control registers, floating-point registers, and the current instruction register. |
rerun | Begins execution of an application with the previous arguments. |
return | Continues running the application program until a return to the specified procedure is reached. |
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 | Displays the active trace and stop subcommands. |
step | Runs one source line. |
stepi | Runs one machine instruction. |
stop | Stops running of the application program. |
stopi | Sets a stop at a specified location. |
thread | Displays and controls threads. |
trace | Prints tracing information. |
tracei | Turns on tracing. |
unalias | Removes an alias. |
unset | Deletes a variable. |
up | Moves the current function up the stack. |
use | Sets the list of directories to be searched when looking for source files. |
whatis | Displays the declaration of application program components. |
where | Displays a list of active procedures and functions. |
whereis | Displays the full qualifications of all the symbols whose names match the specified identifier. |
which | Displays the full qualification of the given identifier. |
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.
/ 12
/
See the ? (search) subcommand and the regcmp subroutine.
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.
?z
?
See the / (search) subcommand and the regcmp subroutine.
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.
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.
The assign subcommand assigns the value specified by the Expression parameter to the variable specified by the Variable parameter.
assign x = 5
assign x = y
assign z = 'z'
assign B = false
assign Y = "Hello World"
set $unsafeassign
See Displaying and Modifying Variables.
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:
Notes:
attributeThe 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 3The 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 4.3 General Programming Concepts: Writing and Debugging Programs .
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.
To call a command while running dbx , enter:
(dbx) call printf("hello") hello
case [ default | mixed | lower | upper ]
The case subcommand changes how the dbx debug program interprets symbols. The default handling of symbols is based on the current language. If the current language is C, C++, or undefined, the symbols are not folded; if the current language is FORTRAN or Pascal, the symbols are folded to lowercase. Use this subcommand if a symbol needs to be interpreted in a way not consistent with the current language.
Entering the case subcommand with no parameters displays the current case mode.
case
case mixed
case upper
See Folding Variables to Lowercase and Uppercase.
catch [ SignalNumber | SignalName ]
The catch subcommand starts the trapping of a specified signal before that signal is sent to the application program. This subcommand is useful when the application program being debugged handles signals such as interrupts. The signal to be trapped can be specified by number or by name using either the SignalNumber or the SignalName parameter, respectively. Signal names are case insensitive, and the SIG prefix is optional. If neither the SignalNumber nor the SignalName parameter is specified, all signals are trapped by default except the SIGHUP, SIGCLD, SIGALARM, and SIGKILL signals. If no arguments are specified, the current list of signals to be caught is displayed.
catch
catch SIGALARM
See the ignore subcommand and Handling Signals.
The clear subcommand removes all stops at a given source line. The SourceLine parameter can be specified in two formats:
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 General Programming Concepts: Writing and Debugging Programs.
The cleari subcommand clears all the breakpoints at the address specified by the Address parameter.
cleari 0x100001b4
cleari &main
See the clear subcommand, the delete subcommand, and Setting and Deleting Breakpoints in in AIX General Programming Concepts: Writing and Debugging Programs.
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:
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.
wait | Displays condition variables which have waiting threads. |
nowait | Displays condition variables which have no waiting threads. |
condition
condition wait
condition 3The 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 4.3 General Programming Concepts: Writing and Debugging Programs:.
{ 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:
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.
>File | Redirects output to the specified file. |
0x3fffe460 / X
&y / 2c
&a_string + 5, &a_string + 7/c
See Examining Memory Addresses in in AIX General Programming Concepts: Writing and Debugging Programs.
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.
See the up subcommand, the where subcommand, and Displaying a Stack Trace in in AIX General Programming Concepts: Writing and Debugging Programs.
dump [ Procedure ] [ >File ]
The dump subcommand displays the names and values of all variables in the specified procedure. If the Procedure parameter is . (period), then all active variables are displayed. If the Procedure parameter is not specified, the current procedure is used. If the >File flag is used, the output is redirected to the specified file.
>File | Redirects output to the specified file. |
dump
dump add_count
dump > var.list
See Displaying and Modifying Variables in in AIX General Programming Concepts: Writing and Debugging Programs.
The edit subcommand invokes an editor on the specified file. The file may be specified through the File parameter or by specifying the Procedure parameter, where the editor is invoked on the file containing that procedure. If no file is specified, the editor is invoked on the current source file. The default is the vi editor. Override the default by resetting the EDITOR environment variable to the name of the desired editor.
edit
edit main.c
edit do_count
See the list subcommand, the vi or vedit command. Also, see Changing the Current File or Procedure and Displaying the Current File in in AIX General Programming Concepts: Writing and Debugging Programs.
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.
file main.c
file
See the func subcommand. Also, see Changing the Current File or Procedure and Displaying the Current File in in AIX General Programming Concepts: Writing and Debugging Programs.
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.
func do_count
func
See the file subcommand. Also, see Changing the Current File or Procedure in in AIX General Programming Concepts: Writing and Debugging Programs.
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.
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.
The gotoi subcommand changes the program counter address to the address specified by the Address parameter.
To change the program counter address to address 0x100002b4 , enter:
gotoi 0x100002b4
See the goto subcommand.
The help subcommand displays help information for dbx subcommands or topics, depending upon the parameter you specify. Entering the help subcommand with the Subcommand parameter displays the syntax statement and description of the specified subcommand. Entering the help subcommand with the Topic parameter displays a detailed description of the specified topic. The following topics are available:
help
help list
help set_variables
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 neither the SignalNumber nor the SignalName parameter is specified, all signals except the SIGHUP, SIGCLD, SIGALRM, and SIGKILL signals are trapped by default. The dbx debug program cannot ignore the SIGTRAP signal if it comes from a process outside of the debugee. If no arguments are specified, the list of currently ignored signals will be displayed.
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 in AIX General Programming Concepts: Writing and Debugging Programs.
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 should consist of a valid line number followed by an optional + (plus sign), or - (minus sign), and an integer. In addition, a SourceLine of $ (dollar sign) may be used to denote the current line number; a SourceLine of @ (at sign) may be used to denote the next line number to be listed.
All lines from the first line number specified to the second line number specified, inclusive, are then displayed.
If the second source line is omitted, the first line is printed only.
If the list subcommand is used without parameters, the number of lines specified by $listwindow are printed, beginning with the current source line.
To change the number of lines to list by default, set the special debug program variable, $listwindow, to the number of lines you want. Initially, $listwindow is set to 10.
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 in AIX General Programming Concepts: Writing and Debugging Programs.
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.
The dbx program can disassemble instructions for either the POWER or PowerPC architecture. In the default mode, the dbx program displays the instructions for the architecture on which it is running.
The $instructionset and $mnemonics variables of the set subcommand for the dbx command allow you to override the default disassembly mode. For more information, see the set subcommand for the dbx command.
at SourceLine | Specifies a starting source line for the listing. |
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 in AIX General Programming Concepts: Writing and Debugging Programs.
map [ > File ]
The map subcommand displays characteristics for each loaded portion of the application. This information includes the name, text origin, text length, data origin, and data length for each loaded module.
> File | Redirects output to the specified file. |
See Debugging at the Machine Level with dbx in in AIX General Programming Concepts: Writing and Debugging Programs.
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.
move 12
move "sample.c":5
See the list subcommand. Also, see Displaying the Current File in in AIX General Programming Concepts: Writing and Debugging Programs.
multproc [ on | parent | child | off ]
The multproc subcommand specifies the behavior of the dbx debug program when forked and execed processes are created. The on flag is used to specify that a new dbx session will be created to debug the child path of a fork. The original dbx will continue to debug the parent path. The parent and child flags are used to specify a single path of a fork to follow. All flags except off enable dbx to follow an execed process. The off flag disables multiprocess debugging. If no flags are specified, the multproc subcommand returns the current status of multiprocess debugging.
The dbx program uses Xwindows for multiprocess debugging. The dbx program opens as many windows as needed for multiprocessing. The title for each child window is the process ID (pid) of the child process. To switch between processes, use Xwindows handling techniques to activate the window where the dbx session is displayed. If the system does not have Xwindows support, a warning message is issued when the debuggee forks, and the dbx program continues debugging only the parent process. Multiprocess debugging can also be unsuccessful for the following reasons:
If $xdisplay is set to a remote display, the user may not be able to see the newly created Xwindow. If the $xdisplay setting is not correct, Xwindows or other system resources report the cause of the failure.
The dbx program does not distinguish between different types of failures, but the following message is sent when the subcommand is not successful:
Warning: dbx subcommand multiproc fails. dbx continued with multproc disabled.
The user-defined configuration of the newly created window can be defined under the dbx_term application name in the .Xdefaults file.
on | Enables multiprocess debugging. |
off | Disables multiprocess debugging. |
multproc
multproc on
multproc off
See the screen subcommand and the fork subroutine. Also, see Debugging Programs Involving Multiple Processes in in AIX General Programming Concepts: Writing and Debugging Programs.
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:
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.
mutex
mutex lock
mutex 4 5 6The 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 in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.
The next subcommand runs the application program up to the next source line. The Number parameter specifies the number of times the next subcommand runs. If the Number parameter is not specified, next runs once only.
If you use the next subcommand in a multi-threaded application program, all the user threads run during the operation, but the program continues execution until the running thread reaches the specified source line. If you wish to step the running thread only, use the set subcommand to set the variable $hold_next. Setting this variable may result in deadlock since the running thread may wait for a lock held by one of the blocked threads.
next
next 3
See the cont subcommand, goto subcommand, nexti subcommand, set subcommand, and the step subcommand.
The nexti subcommand runs the application program up to the next instruction. The Number parameter specifies the number of times the nexti subcommand will run. If the Number parameter is not specified, nexti runs once only.
If you use the nexti subcommand in a multi-threaded application program, all the user threads run during the operation, but the program continues execution until the running thread reaches the specified machine instruction. If you wish to step the running thread only, use the set subcommand to set the variable $hold_next. Setting this variable may result in deadlock since the running thread may wait for a lock held by one of the blocked threads.
nexti
nexti 3
See the gotoi subcommand, next subcommand, set subcommand, and stepi subcommand. Also, see Running a Program at the Machine Level in in AIX General Programming Concepts: Writing and Debugging Programs.
print Procedure ( [ Parameters ] )
The print subcommand does either of the following:
print x, y << 2
print sbrk(0)
See the assign subcommand, the call subcommand, and the set subcommand.
The prompt subcommand changes the dbx command prompt to the string specified by the String parameter.
To change the prompt to dbx> , enter:
prompt "dbx>"
See Defining a New dbx Prompt in in AIX General Programming Concepts: Writing and Debugging Programs.
The quit subcommand terminates all processes running in the dbx debugging session.
registers [ >File ]
The registers subcommand displays the values of general purpose registers, system control registers, floating-point registers, and the current instruction register.
Note: The register value may be set to the 0xdeadbeef hexadecimal value. The 0xdeadbeef hexadecimal value is an initialization value assigned to general-purpose registers at process initialization.
Note: The registers subcommand cannot display registers if the current thread is in kernel mode.
>File | Redirects output to the specified file. |
See the set subcommand and the unset subcommand. Also, see Using Machine Registers in in AIX General Programming Concepts: Writing and Debugging Programs.
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.
See the run subcommand.
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.
return
return main
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:
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
read | Displays information about all rwlocks whose status is in read mode. |
write | Displays information about all rwlocks whose status is in write mode. |
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 [ 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.
To run the application with the arguments blue and 12 , enter:
run blue 12
See the rerun subcommand.
The screen subcommand opens an Xwindow for the dbx command interaction. You continue to operate in the window in which the process originated.
The screen subcommand must be run while the dbx debug program is running in an Xwindows environment. If the screen subcommand is issued in a non-Xwindow environment, the dbx program displays a warning message and resumes debugging as if the screen subcommand had not been given. The screen subcommand can also be unsuccessful in the following situations:
The dbx program does not distinguish between different types of failures, but the program does send the following message:
Warning: dbx subcommand screen fails. dbx continues.
If $xdisplay is set to a remote display, the user may not be able to see the newly created Xwindow. If the $xdisplay setting is not correct, Xwindows or other system resources report the problem.
The user-defined configuration of the newly created window can be defined under the dbx_term application name in the .Xdefaults file.
To open an Xwindow for dbx command interaction, enter:
screen
See Separating dbx Output From Program Output in in AIX General Programming Concepts: Writing and Debugging Programs and AIXwindows Overview, in AIX Version 4 AIXwindows Programming Guide.
The set subcommand defines a value for the dbx debug program variable. The value is specified by the Expression parameter; the program variable is specified by the Variable parameter. The name of the variable should not conflict with names in the program being debugged. A variable is expanded to the corresponding expression within other commands. If the set subcommand is used without arguments, the variables currently set are displayed.
The following variables are set with the set subcommand:
$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 may not contain storage types of different sizes. |
$unsafebounds | Turns off subscript checking on arrays. |
$unsafecall | Turns off strict type checking for arguments to subroutines or function calls. |
$unsafegoto | Turns off the goto subcommand destination checking. |
$vardim | Specifies the dimension length to use when printing arrays with unknown bounds. The default value is 10. |
$xdisplay | Specifies the display name for Xwindows, for use with the multproc subcommand or the screen subcommand. The default is the value of the shell DISPLAY variable. |
The $unsafe variables limit the usefulness of the dbx debug program in detecting errors.
set $listwindow=20
set $unsafeassign
set $instructionset="601"
See the unset subcommand. Also, see Changing Print Output with Special Debug Program Variables in in AIX General Programming Concepts: Writing and Debugging Programs.
The set subcommand with the -o or edit option may 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.
set-o vi
or
set edit vi
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.
sh ls
sh
sh echo $SHELL
See Running Shell Commands from dbx in in AIX General Programming Concepts: Writing and Debugging Programs.
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.
To continue execution until the second breakpoint is encountered, enter:
skip 1
The source subcommand reads dbx subcommands from the file specified by the File parameter.
To read the dbx subcommands in the cmdfile file, enter:
source cmdfile
See Reading dbx Subcommands from a File in in AIX General Programming Concepts: Writing and Debugging Programs.
status [ >File ]
The status subcommand displays the trace and stop subcommands currently active. The > flag sends the output of the status subcommand to a file specified in the File parameter.
>File | Redirects output to File. |
See the clear subcommand, the delete subcommand, the stop subcommand, and the trace subcommand for the dbx command.
Also, see Setting and Deleting Breakpoints in in AIX General Programming Concepts: Writing and Debugging Programs.
The step subcommand runs source lines of the application program. Specify the number of lines to be executed with the Number parameter. If the Number parameter is omitted, it defaults to a value of 1.
If you use the step subcommand on a multi-threaded application program, all the user threads run during the operation, but the program continues execution until the running thread reaches the specified source line. If you wish to step the running thread only, use the set subcommand to set the variable $hold_next. Setting this variable may result in deadlock since the running thread may wait for a lock held by one of the blocked threads.
Note: Use the $stepignore variable of the set subcommand to control the behavior of the step subcommand. The $stepignore variable enables the step subcommand to step over large routines for which no debugging information is available.
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.
The stepi subcommand runs instructions of the application program. Specify the number of instructions to be executed in the Number parameter. If the Number parameter is omitted, it defaults to one.
If used on a multi-threaded application program, the stepi subcommand steps the running thread only. All other user threads remain stopped.
stepi
stepi 5
See the gotoi subcommand, the nexti subcommand, and the step subcommand.
stop { [Variable] [at SourceLine | in Procedure ] [ if Condition ]}
The stop subcommand halts the application program when certain conditions are fulfilled. The program is stopped when:
The SourceLine variable can be specified as an integer or as a file name string followed by a : (colon) and an integer.
After any of these commands, the dbx debug program responds with a message reporting the event it has built as a result of your command. The message includes the event ID associated with your breakpoint along with an interpretation of your command. The syntax of the interpretation might not be exactly the same as your command. For example:
stop in main [1] stop in main stop at 19 if x == 3 [2] stop at "hello.c":19 if x = 3
The numbers in brackets are the event identifiers associated with the breakpoints. The dbx debug program associates event numbers with each stop subcommand. When the program is halted as the result of one of the events, the event identifier is displayed along with the current line to show what event caused the program to stop. The events you create coexist with internal events created by dbx, so event numbers may not always be sequential.
Use the status subcommand to view these numbers. You can redirect output from status to a file. Use the delete or clear subcommand to turn the stop subcommand off.
In a multi-threaded application program, all user threads are halted when any user thread hits a breakpoint. A breakpoint set on a source line or function will be hit by any user thread which executes the line or function, unless you specify conditions as shown in example 9 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 below:
stopi at &Function if ($running_thread == ThreadNumber) stop at SourceLine if ($running_thread == ThreadNumber)
at SourceLine | Specifies the line number. |
if Condition | Specifies the condition, such as true. |
in Procedure | Specifies the procedure to be called. |
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)
See the clear subcommand, the delete subcommand, the stopi subcommand, and the trace subcommand. Also, see Setting and Deleting Breakpoints in in AIX General Programming Concepts: Writing and Debugging Programs.
stopi { [Address] [at Address | in Procedure ] [ if Condition ]}
The stopi subcommand sets a stop at the specified location:
if Condition | Specifies the condition, such as true. |
in Procedure | Specifies the procedure to be called. |
at Address | Specifies the machine instruction address. |
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 in AIX General Programming Concepts: Writing and Debugging Programs.
thread { [ info ] [ - ] [ ThreadNumber ... ] } | current | run | susp | term | wait
thread current [ - ] ThreadNumber
thread { hold | unhold } [ - ] [ ThreadNumber ... ]
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:
thread | Indicates the symbolic name of the user thread, in the form $t ThreadNumber. |
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.
thread | Indicates the symbolic name of the user thread, in the form $t ThreadNumber. |
Kernel thread related information
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 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 can be run, wait, susp, or zomb, for running, waiting, suspended, or zombie. |
User thread related information
tid | Indicates the user thread identifier. | ||||
pri | Indicates the priority of the userl thread. | ||||
sched | Indicates the scheduling policy of the user thread. This can be fif, oth, rr, for fifo, other, or round robin scheduling policies. | ||||
state | Indicates the state of the user thread. This 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 has been held. | ||||
scope | Indicates the contention scope of the user thread; this can be sys or pro for system or process contention scope. | ||||
cancellation |
|
joinable | Indicates whether the thread is joinable 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 below.
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 will not be resumed until it is released.
Note: The print subcommand of the dbx debug program recognizes symbolic thread names, and can be used to display the status of the corresponding object.
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 above 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. |
thread waitThe 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 4The 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 4.3 General Programming Concepts: Writing and Debugging Programs.
trace [ SourceLine | Expression at SourceLine | Procedure | [ Variable ] [ at SourceLine | in Procedure ] ] [ if Condition ]
The trace subcommand prints tracing information for the specified procedure, function, source line, expression, or variable when the program runs. The SourceLine variable can be specified as an integer or as a file name string followed by a : (colon) and an integer. A condition can be specified. The dbx debug program associates a number with each trace subcommand. Use the status subcommand to view these numbers. Use the delete subcommand to turn tracing off.
By default, tracing is process based. In order to make a thread based trace, specify the thread in a condition as shown in example 8 below.
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. |
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)
Also, see the tracei subcommand.
tracei [ [ Address ] [ at Address | in Procedure ] | Expression at Address ] [ if Condition ]
The tracei subcommand turns on tracing when:
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. |
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 in AIX General Programming Concepts: Writing and Debugging Programs.
The unalias subcommand removes the alias specified by the Name parameter.
To remove an alias named printx , enter:
unalias printx
See the alias subcommand. Also, see Creating Subcommand Aliases in in AIX General Programming Concepts: Writing and Debugging Programs.
The unset subcommand deletes the dbx debug program variable associated with the name specified by the Name parameter.
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 in AIX General Programming Concepts: Writing and Debugging Programs.
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.
up 2
up 0
See the down subcommand. Also, see Changing the Current File or Procedure, Displaying a Stack Trace in in AIX General Programming Concepts: Writing and Debugging Programs.
The use subcommand sets the list of directories to be searched when the dbx debug program looks for source files. If the use subcommand is specified without arguments, the current list of directories to be searched is displayed.
The @ (at-sign) is a special symbol that directs the dbx program to look at the full-path name information in the object file, if it exists. If you have a relative directory called @ to search, you should use ./@ in the search path.
The use subcommand uses the + (plus-sign) to add more directories to the list of directories to be searched. If you have a directory named +, specify the full-path name for the directory (for example, ./+ or /tmp/+).
use . .. /tmp
use . @ ../source
use + /tmp2
Also, see the edit subcommand and the list subcommand.
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.
whatis x
whatis main
whatis main.x
(dbx) whatis $$status enum $$status { run, create, delete, suspend };
where [ >File ]
The where subcommand displays a list of active procedures and functions. By using the >File flag, the output of this subcommand can be redirected to the specified file.
>File | Redirects output to the specified file. |
See the up subcommand and the down subcommand. Also, see Displaying a Stack Trace in in AIX General Programming Concepts: Writing and Debugging Programs.
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.
To display the qualified names of all symbols named x , enter:
whereis x
Also, see the which subcommand.
The which subcommand displays the full qualification of the given identifier. The full qualification consists of a list of the outer blocks with which the identifier is associated.
To display the full qualification of the x symbol, enter:
which x
See the whereis subcommand. Also. seeScoping of Names in in AIX General Programming Concepts: Writing and Debugging Programs.
a.out | Object file; contains object code. |
core | Contains core dump. |
.dbxinit | Contains initial commands. |
The adb command, cc command.
The dbx Symbolic Debug Program Overview and Using the dbx Debug Program in AIX General Programming Concepts: Writing and Debugging Programs.