Commands Reference, Volume 2

dbx Command

Purpose

Provides an environment to debug and run programs.

Syntax

dbx [ -a ProcessID ] [ -c CommandFile ] [ -d NestingDepth ] [ -I Directory ] [ -E DebugEnvironment ] [ -p oldpath=newpath:...| pathfile ] [ -k ] [ -u ] [ -F ] [ -r ] [ -x ] [ ObjectFile [ CoreFile ] ]

Description

The dbx command provides a symbolic debug program for C, C++, Pascal, and FORTRAN programs, allowing you to carry out operations such as the following:

Examine object and core files.
Provide a controlled environment for running a program.
Set breakpoints at selected statements or run the program one line at a time.
Debug using symbolic variables and display them in their correct format.

The ObjectFile parameter is an object (executable) file produced by a compiler. Use the -g (generate symbol table) flag when compiling your program to produce the information the dbx command needs.

Note: The -g flag of the cc command should be used when the object file is compiled. If the -g flag is not used or if symbol references are removed from the xcoff file with the strip command, the symbolic capabilities of the dbx command are limited.

If the -c flag is not specified, the dbx command checks for a .dbxinit file in the user's $HOME directory. It then checks for a .dbxinit file in the user's current directory. If a .dbxinit file exists in the current directory, that file overrides the .dbxinit file in the user's $HOME directory. If a .dbxinit file exists in the user's $HOME directory or current directory, that file's subcommands run at the beginning of the debug session. Use an editor to create a .dbxinit file.

If ObjectFile is not specified, then dbx asks for the name of the object file to be examined. The default is a.out. If the core file exists in the current directory or a CoreFile parameter is specified, then dbx reports the location where the program faulted. Variables, registers, and memory held in the core image may be examined until execution of ObjectFile begins. At that point the dbx debug program prompts for commands.

Expression Handling

The dbx program can display a wide range of expressions. You can specify expressions in the dbx debug program with a common subset of C and Pascal syntax, with some FORTRAN extensions.

The following operators are valid in the debug program:

* (asterisk) or ^ (caret)	Denotes indirection or pointer dereferencing.
[ ] (brackets) or ( ) (parentheses)	Denotes subscript array expressions.
. (period)	Use this field reference operator with pointers and structures. This makes the C operator -> (arrow) unnecessary, although it is allowed.
& (ampersand)	Gets the address of a variable.
.. (two periods)	Separates the upper and lower bounds when specifying a subsection of an array. For example: n[1..4].

The following types of operations are valid in expressions in the debug program:

Algebraic	=, -, *, / (floating division), div (integral division), mod, exp (exponentiation)
Bitwise	-, I, bitand, xor, ~. <<, >>
Logical	or, and, not, II, &&
Comparison	<, >, <=, >=, < > or !=, = or ==
Other	(typename),sizeof

Logical and comparison expressions are allowed as conditions in stop and trace.

Expression types are checked. You override an expression type by using a renaming or casting operator. The three forms of type renaming are Typename(Expression), Expression|Typename, and (Typename) Expression. The following is an example where the x variable is an integer with value 97:

(dbx) print x
97
(dbx) print char (x), x \ char, (char) x, x
'a' 'a' 'a' 97

Command Line Editing

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.

Flags

-a ProcessID	Attaches the debug program to a process that is running. To attach the debug program, you need authority to use the kill command on this process. Use the ps command to determine the process ID. If you have permission, the dbx program interrupts the process, determines the full name of the object file, reads in the symbolic information, and prompts for commands.
-c CommandFile	Runs the dbx subcommands in the file before reading from standard input. The specified file in the $HOME directory is processed first; then the file in the current directory is processed. The command file in the current directory overrides the command file in the $HOME directory. If the specified file does not exist in either the $HOME directory or the current directory, a warning message is displayed. The source subcommand can be used once the dbx program is started.
-d NestingDepth	Sets the limit for the nesting of program blocks. The default nesting depth limit is 25.
-E DebugEnvironment	Specifies the environment variable for the debug program.
-p oldpath=newpath:...\| pathfile	Specifies a substitution for library paths when examining core files in the format oldpath=newpath. oldpath specifies the value to be substituted (as stored in the core file) and newpath specifies what it is to be replaced with. These may be complete or partial, relative or absolute paths. Multiple substitutions may be specified, separated by colons. Alternatively, the -p flag may 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.
-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: The directory the source file was located in when it was compiled. This directory is searched only if the compiler placed the source path in the object. The current directory. The directory where the program is currently located.
-k	Maps memory addresses; this is useful for kernel debugging.
-r	Runs the object file immediately. If it terminates successfully, the dbx debug program is exited. Otherwise, the debug program is entered and the reason for termination is reported. Note: Unless -r is specified, the dbx command prompts the user and waits for a command.
-u	Causes the dbx command to prefix file name symbols with an @ (at sign). This flag reduces the possibility of ambiguous symbol names.
-x	Prevents the dbx command from stripping _ (trailing underscore ) characters from symbols originating in FORTRAN source code. This flag allows dbx to distinguish between symbols which are identical except for an underscore character, such as `xxx` and `xxx_`.

Examples

The following example explains how to start the dbx debug program simultaneously with a process. The example uses a program called samp.c. This C program is first compiled with the -g flag to produce an object file that includes symbolic table references. In this case, the program is named samp:
```
$ cc -g samp.c -o samp
```
When the program samp is run, the operating system reports a bus error and writes a core image to your current working directory as follows:
```
$ samp
Bus Error - core dumped
```
To determine the location where the error occurred, enter:
```
$ dbx samp
```
The system returns the following message:
```
dbx version 3.1
Type 'help' for help.
reading symbolic information . . . [
using memory image in core]
  25   x[i] = 0;
(dbx) quit
```
This example explains how to attach dbx to a process. This example uses the following program, looper.c:
```
main()
{
      int i,x[10];
       
      for (i = 0; i < 10;);
}
```
The program will never terminate because i is never incremented. Compile looper.c with the -g flag to get symbolic debugging capability:
```
$ cc -g looper.c -o looper
```
Run looper from the command line and perform the following steps to attach dbx to the program while it is running:
1. To attach dbx to looper, you must determine the process ID. If you did not run looper as a background process, you must have another Xwindow open. From this Xwindow , enter:
```
ps -u UserID
```
  where UserID is your login ID. All active processes that belong to you are displayed as follows:
```
PID     TTY      TIME    COMMAND
68      console   0:04    sh
467     lft3     10:48    looper
```
  In this example the process ID associated with looper is 467.
2. To attach dbx to looper, enter:
```
$ dbx -a 467
```
  The system returns the following message:
```
Waiting to attach to process 467 . . .
Successfully attached to /tmp/looper.
dbx is initializing
Type 'help' for help.
reading symbolic information . . .
 
attached in main at line 5
5     for (i = 0; i < 10;);
(dbx)
```
  You can now query and debug the process as if it had been originally started with dbx.
To add directories to the list of directories to be searched for the source file of an executable file objefile, you can enter:
```
$dbx -I /home/user/src -I /home/group/src 
objfile
```
The use subcommand may be used for this function once dbx is started. The use command resets the list of directories, whereas the -I flag adds a directory to the list.

To use the -r flag, enter:

$ dbx -r samp

The system returns the following message:

Entering debug program . . .
dbx version 3.1
Type 'help' for help.
reading symbolic information . . .
bus error in main at line 25
  25   x[i] = 0;
(dbx) quit

The -r flag allows you to examine the state of your process in memory even though a core image is not taken.

To specify the environment variables for the debug program, enter:
```
dbx -E LIBPATH=/home/user/lib -E LANG=Ja_JP objfile
```

dbx Subcommands

Note: The subcommands can only be used while running the dbx debug program.

/	Searches forward in the current source file for a pattern.
?	Searches backward in the current source file for a pattern.
alias	Creates aliases for dbx subcommands.
assign	Assigns a value to a variable.
attribute	Displays information about all or selected attributes objects.
call	Runs the object code associated with the named procedure or function.
case	Changes how the dbx debug program interprets symbols.
catch	Starts trapping a signal before that signal is sent to the application program.
clear	Removes all stops at a given source line.
cleari	Removes all breakpoints at an address.
condition	Displays information about all or selected condition variables.
cont	Continues application program execution from the current stopping point until the program finishes or another breakpoint is encountered.
delete	Removes the traces and stops corresponding to the specified event numbers.
detach	Continues execution of application and exits the debug program.
display memory	Displays the contents of memory.
down	Moves the current function down the stack.
dump	Displays the names and values of variables in the specified procedure.
edit	Starts an editor on the specified file.
file	Changes the current source file to the specified file.
func	Changes the current function to the specified procedure or function.
goto	Causes the specified source line to be the next line run.
gotoi	Changes the program counter address.
help	Displays help information for dbx subcommands or topics.
ignore	Stops trapping a signal before that signal is sent to the application program.
list	Displays lines of the current source file.
listi	Lists instructions from the application program.
map	Displays information about load characteristics of the application.
move	Changes the next line to be displayed.
multproc	Enables or disables multiprocess debugging.
mutex	Displays information about all or selected mutexes.
next	Runs the application program up to the next source line.
nexti	Runs the application program up to the next machine instruction.
print	Prints the value of an expression or runs a procedure and prints the return code of that procedure.
prompt	Changes the dbx command prompt.
quit	Stops the dbx debug program.
registers	Displays the values of all general-purpose registers, system-control registers, floating-point registers, and the current instruction register.
rerun	Begins execution of an application with the previous arguments.
return	Continues running the application program until a return to the specified procedure is reached.
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.
stophwp	Sets a hardware watchpoint stop.
stop	Stops running of the application program.
stopi	Sets a stop at a specified location.
thread	Displays and controls threads.
trace	Prints tracing information.
tracehwp	Sets a hardware watchpoint trace.
tracei	Turns on tracing.
unalias	Removes an alias.
unset	Deletes a variable.
up	Moves the current function up the stack.
use	Sets the list of directories to be searched when looking for source files.
whatis	Displays the declaration of application program components.
where	Displays a list of active procedures and functions.
whereis	Displays the full qualifications of all the symbols whose names match the specified identifier.
which	Displays the full qualification of the given identifier.

/ Subcommand

/ [ RegularExpression [ / ] ]

The / subcommand searches forward in the current source file for the pattern specified by the RegularExpression parameter. Entering the / subcommand with no arguments causes dbx to search forward for the previous regular expression. The search wraps around the end of the file.

Examples

To search forward in the current source file for the number 12, enter:
```
/ 12
```
To repeat the previous search, enter:
```
/
```

See the ? (search) subcommand and the regcmp subroutine.

? Subcommand

? [ RegularExpression [ ? ] ]

The ? subcommand searches backward in the current source file for the pattern specified by the RegularExpression parameter. Entering the ? subcommand with no arguments causes the dbx command to search backwards for the previous regular expression. The search wraps around the end of the file.

Examples

To search backward in the current source file for the letter z, enter:
```
?z
```
To repeat the previous search, enter:
```
?
```

See the / (search) subcommand and the regcmp subroutine.

alias Subcommand

alias [ Name [ [ (Arglist) ] String | Subcommand ] ]

The alias subcommand creates aliases for dbx subcommands. The Name parameter is the alias being created. The String parameter is a series of dbx subcommands that, after the execution of this subcommand, can be referred to by Name. If the alias subcommand is used without parameters, it displays all current aliases.

Examples

To substitute rr for rerun, enter:
```
alias rr rerun
```
To run the two subcommands print n and step whenever printandstep is typed at the command line, enter:
```
alias printandstep "print n; step"
```
The alias subcommand can also be used as a limited macro facility. For example:
```
(dbx) alias px(n) "set $hexints; print n; unset $hexints"
(dbx) alias a(x,y) "print symname[x]->symvalue._n_n.name.Id[y]"
(dbx) px(126)
0x7e
```
In this example, the alias px prints a value in hexadecimal without permanently affecting the debugging environment.

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

To assign a value of 5 to the x variable, enter:
```
assign x = 5
```
To assign the value of the y variable to the x variable, enter:
```
assign x =  y
```
To assign the character value 'z' to the z variable, enter:
```
assign  z  =  'z'
```
To assign the boolean value false to the logical type variable B, enter:
```
assign  B  =  false
```
To assign the "Hello World" string to a character pointer Y, enter:
```
assign  Y  =  "Hello  World"
```
To disable type checking, set the dbx debug program variable $unsafeassign by entering:
```
set $unsafeassign
```

See Displaying and Modifying Variables.

attribute Subcommand

attribute [ AttributeNumber ... ]

The attribute subcommand displays information about the user thread, mutex, or condition attributes objects defined by the AttributeNumber parameters. If no parameters are specified, all attributes objects are listed.

For each attributes object listed, the following information is displayed:

`attr`	Indicates the symbolic name of the attributes object, in the form `$a`AttributeNumber.
`obj_addr`	Indicates the address of the attributes object.
`type`	Indicates the type of the attributes object; this can be `thr`, `mutex`, or `cond` for user threads, mutexes, and condition variables respectively.
`state`	Indicates the state of the attributes object. This can be `valid` or `inval`.
`stack`	Indicates the stacksize attribute of a thread attributes object.
`scope`	Indicates the scope attribute of a thread attributes object. This determines the contention scope of the thread, and defines the set of threads with which it must contend for processing resources. The value can be `sys` or `pro` for system or process contention scope.
`prio`	Indicates the priority attribute of a thread attributes object.
`sched`	Indicates the schedpolicy attribute of a thread attributes object. This attribute controls scheduling policy, and can be `fifo` , `rr` (round robin), or `other`.
`p-shar`	Indicates the process-shared attribute of a mutex or condition attribute object. A mutex or condition is process-shared if it can be accessed by threads belonging to different processes. The value can be `yes` or `no`.
`protocol`	Indicates the protocol attribute of a mutex. This attribute determines the effect of holding the mutex on a threads priority. The value can be `no_prio`, `prio`, or `protect`.

Notes:

The print subcommand of the dbx debug program recognizes symbolic attribute names, and can be used to display the status of the corresponding object.

The available attributes depend on the implementation of POSIX options.

Examples

To list information about all attributes, enter:

attribute

The output is similar to:

attr   obj_addr   type  state  stack   scope    prio 
sched p-shar
$a1   0x200035c8  mutex valid                                no 
$a2   0x20003628  cond  valid                                no
$a3   0x200037c8  thr   valid  57344    sys      126 other
$a4   0x200050f8  thr   valid  57344    pro      126 other

To list information about attributes 1 and 3, enter:

attribute 1 3

The output is similar to:

attr   obj_addr   type  state  stack   scope    prio 
sched p-shar
$a1   0x200035c8  mutex valid                                no 
$a3   0x200037c8  thr   valid  57344    sys      126 other

See the condition subcommand, mutex subcommand, print subcommand, and thread subcommand for the dbx command.

Also, see Creating Threads, Using Mutexes, and Using Condition Variables in AIX 5L Version 5.2 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 or Pascal, the symbols are folded to lowercase. Use this subcommand if a symbol needs to be interpreted in a way not consistent with the current language.

Entering the case subcommand with no parameters displays the current case mode.

Flags

default	Varies with the current language.
mixed	Causes symbols to be interpreted as they actually appear.
lower	Causes symbols to be interpreted as lowercase.
upper	Causes symbols to be interpreted as uppercase.

Examples

To display the current case mode, enter:
```
case
```
To instruct dbx to interpret symbols as they actually appear, enter:
```
case mixed
```
To instruct dbx to interpret symbols as uppercase, enter:
```
case upper
```

See Folding Variables to Lowercase and Uppercase.

catch Subcommand

catch [ SignalNumber | SignalName ]

The catch subcommand starts the trapping of a specified signal before that signal is sent to the application program. This subcommand is useful when the application program being debugged handles signals such as interrupts. The signal to be trapped can be specified by number or by name using either the SignalNumber or the SignalName parameter, respectively. Signal names are case insensitive, and the SIG prefix is optional. If neither the SignalNumber nor the SignalName parameter is specified, all signals are trapped by default except the SIGHUP, SIGCLD, SIGALARM, and SIGKILL signals. If no arguments are specified, the current list of signals to be caught is displayed.

Examples

To display a current list of signals to be caught by dbx, enter:
```
catch
```
To trap signal SIGALARM, enter:
```
catch SIGALARM
```

See the ignore subcommand and Handling Signals.

clear Subcommand

clear SourceLine

The clear subcommand removes all stops at a given source line. The SourceLine parameter can be specified in two formats:

As an integer
As a file name string followed by a : (colon) and an integer

Examples

To remove breakpoints set at line 19, enter:

clear 19

The cleari subcommand and delete subcommand. Also, see Setting and Deleting Breakpoints in in AIX 5L Version 5.2 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

To remove a breakpoint set at address 0x100001b4, enter:
```
cleari 0x100001b4
```
To remove a breakpoint set at the main() procedure address, enter:
```
cleari &main
```

See the clear subcommand, the delete subcommand, and Setting and Deleting Breakpoints in in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

condition Subcommand

condition [ wait | nowait | ConditionNumber ... ]

The condition subcommand displays information about one or more condition variables. If one or more ConditionNumber parameters are given, the condition subcommand displays information about the specified condition variables. If no flags or parameters are specified, the condition subcommand lists all condition variables.

The information listed for each condition is as follows:

`cv`	Indicates the symbolic name of the condition variable, in the form `$c`ConditionNumber.
`obj_addr`	Indicates the memory address of the condition variable.
`num_wait`	Indicates the number of threads waiting on the condition variable.
`waiters`	Lists the user threads which are waiting on the condition variable.

Note: The print subcommand of the dbx debug program recognizes symbolic condition variable names, and can be used to display the status of the corresponding object.

Flags

wait	Displays condition variables which have waiting threads.
nowait	Displays condition variables which have no waiting threads.

Examples

To display information about all condition variables, enter:
```
condition
```
To display information about all condition variables which have waiting threads, enter:
condition wait
To display information about the condition variable 3, enter:
```
condition 3
```
The output is similar to:
```
cv      obj_addr     num_wait  waiters
$c3     0x20003290         0
```

See the attribute subcommand, mutex subcommand, print subcommand, and thread subcommand.

Also, see Using Condition Variables in AIX 5L Version 5.2 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 had been received. Signal names are not case sensitive and the SIG prefix is optional. If no signal is specified, the program continues as if it had not been stopped.

Examples

To continue program execution from current stopping point, enter:
```
cont
```
To continue program execution as though it received the signal SIGQUIT, enter:
```
cont SIGQUIT
```

See the detach subcommand for the dbx command, the goto subcommand for the dbx command, the next subcommand for the dbx command, the skip subcommand for the dbx command, the step subcommand for the dbx command.

delete Subcommand

delete { Number ... | all }

The delete subcommand removes traces and stops from the application program. The traces and stops to be removed can be specified through the Number parameters, or all traces and stops can be removed by using the all flag. Use the status subcommand to display the numbers associated by the dbx debug program with a trace or stop.

Flag

all	Removes all traces and stops.

Examples

To remove all traces and stops from the application program, enter:
```
delete all
```
To remove traces and stops for event number 4, enter:
```
delete 4
```

See the clear subcommand, the cleari subcommand, the status subcommand and Setting and Deleting Breakpoints in in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

detach Subcommand

detach [ SignalNumber | SignalName ]

The detach subcommand continues the execution of the application program and exits the debug program. A signal can be specified either by:

Name, using the SignalName parameter
Number, using the SignalNumber parameter
Signal names are not case sensitive and the SIG prefix is optional.

If a signal is specified, the program continues as if it had received that signal. If no signal is specified, the program continues as if no stop had occurred.

Examples

To continue execution of the application and exit dbx, enter:
```
detach
```
To exit dbx and continue execution of the application as though it received signal SIGREQUEST, enter:
```
detach SIGREQUEST
```

See Using the dbx Debug Program.

display memory Subcommand

{ Address,Address/ | Address/ [ Count ] } [ Mode ] [ >File ]

The display memory subcommand, which does not have a keyword to initiate the command, displays a portion of memory controlled by the following factors:

The range of memory displayed is controlled by specifying either:

Two Address parameters, where all lines between those two addresses are displayed,
OR
One Address parameter where the display starts and a Count that determines the number of lines displayed from Address.

Specify symbolic addresses by preceding the name with an & (ampersand). Addresses can be expressions made up of other addresses and the operators + (plus sign), - (minus sign), and * (indirection). Any expression enclosed in parentheses is interpreted as an address.

The format in which the memory is displayed is controlled by the Mode parameter. The default for the Mode parameter is the current mode. The initial value of Mode is X. The possible modes include:

b	Prints a byte in octal.
c	Prints a byte as a character.
d	Prints a short word in decimal.
D	Prints a long word in decimal.
f	Prints a single-precision real number.
g	Prints a double-precision real number.
h	Prints a byte in hexadecimal.
i	Prints the machine instruction.
lld	Prints an 8-byte signed decimal number.
llu	Prints an 8-byte unsigned decimal number.
llx	Prints an 8-byte unsigned hexadecimal number.
llo	Prints an 8-byte unsigned octal number.
o	Prints a short word in octal
O	Prints a long word in octal.
q	Prints an extended-precision floating-point number.
s	Prints a string of characters terminated by a null byte.
x	Prints a short word in hexadecimal.
X	Prints a long word in hexadecimal.

Flag

>File

Redirects output to the specified file.

Examples

To display one long word of memory content in hexadecimal starting at the address 0x3fffe460, enter:
```
0x3fffe460 / X
```
To display two bytes of memory content as characters starting at the variable y address, enter:
```
&y / 2c
```
To display the sixth through the eighth elements of the FORTRAN character string a_string, enter:
```
&a_string + 5, &a_string + 7/c
```

See Examining Memory Addresses in AIX 5L Version 5.2 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

To move one level down the stack, enter:
```
down
```
To move three levels down the stack, enter:
```
down 3
```

See the up subcommand, the where subcommand, and Displaying a Stack Trace in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

dump Subcommand

dump [ Procedure ] [ >File ]

The dump subcommand displays the names and values of all variables in the specified procedure. If the Procedure parameter is . (period), then all active variables are displayed. If the Procedure parameter is not specified, the current procedure is used. If the >File flag is used, the output is redirected to the specified file.

Flags

>File

Redirects output to the specified file.

Examples

To display names and values of variables in the current procedure, enter:
```
dump
```
To display names and values of variables in the add_count procedure, enter:
```
dump add_count
```
To redirect names and values of variables in the current procedure to the var.list file, enter:
```
dump > var.list
```

See Displaying and Modifying Variables in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

edit Subcommand

edit [ Procedure | File ]

The edit subcommand invokes an editor on the specified file. The file may be specified through the File parameter or by specifying the Procedure parameter, where the editor is invoked on the file containing that procedure. If no file is specified, the editor is invoked on the current source file. The default is the vi editor. Override the default by resetting the EDITOR environment variable to the name of the desired editor.

Examples

To start an editor on the current source file, enter:
```
edit
```
To start an editor on the main.c file, enter:
```
edit main.c
```
To start an editor on the file containing the do_count() procedure, enter:
```
edit do_count
```

See the list subcommand, the vi or vedit command. Also, see Changing the Current File or Procedure and Displaying the Current File in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

file Subcommand

file [ File ]

The file subcommand changes the current source file to the file specified by the File parameter; it does not write to that file. The File parameter can specify a full path name to the file. If the File parameter does not specify a path, the dbx program tries to find the file by searching the use path. If the File parameter is not specified, the file subcommand displays the name of the current source file. The file subcommand also displays the full or relative path name of the file if the path is known.

Examples

To change the current source file to the main.c file, enter:
```
file main.c
```
To display the name of the current source file, enter:
```
file
```

See the func subcommand. Also, see Changing the Current File or Procedure and Displaying the Current File in AIX 5L Version 5.2 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

To change the current function to the do_count procedure, enter:
```
func do_count
```
To display the name of the current function, enter:
```
func
```

See the file subcommand. Also, see Changing the Current File or Procedure in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

goto Subcommand

goto SourceLine

The goto subcommand causes the specified source line to be run next. Normally, the source line must be in the same function as the current source line. To override this restriction, use the set subcommand with the $unsafegoto flag.

Example

To change the next line to be executed to line 6, enter:

goto 6

See the cont subcommand, the gotoi subcommand, and the set subcommand.

gotoi Subcommand

gotoi Address

The gotoi subcommand changes the program counter address to the address specified by the Address parameter.

Example

To change the program counter address to address 0x100002b4, enter:

gotoi 0x100002b4

See the goto subcommand.

help Subcommand

help [ Subcommand | Topic ]

The help subcommand displays help information for dbx subcommands or topics, depending upon the parameter you specify. Entering the help subcommand with the Subcommand parameter displays the syntax statement and description of the specified subcommand. Entering the help subcommand with the Topic parameter displays a detailed description of the specified topic. The following topics are available:

startup	Lists dbx startup options.
execution	Lists dbx subcommands related to program execution.
breakpoints	Lists dbx subcommands related to breakpoints and traces.
files	Lists dbx subcommands for accessing source files.
data	Lists dbx subcommands for accessing program variables and data.
machine	Lists descriptions of dbx subcommands for machine-level debugging.
environment	Lists dbx subcommands for setting dbx configuration and environment.
threads	Lists dbx subcommands for accessing thread-related objects.
expressions	Describes dbx expression syntax and operators.
scope	Describes how dbx resolves names from different scopes.
set_variables	Lists dbx debug variables with a usage description.
usage	Lists common dbx subcommands with brief descriptions.

Examples

To list all available dbx subcommands and topics, enter:
```
help
```
To display the description of the dbx subcommand list, enter:
```
help list
```
To display the description of the dbx topic set_variables, enter:
```
help set_variables
```

ignore Subcommand

ignore [ SignalNumber | SignalName ]

The ignore subcommand stops the trapping of a specified signal before that signal is sent to the application program. This subcommand is useful when the application program being debugged handles signals such as interrupts.

The signal to be trapped can be specified by:

Number, with the SignalNumber parameter
Name, with the SignalName parameter

Signal names are not case sensitive. The SIG prefix is optional.

If neither the SignalNumber nor the SignalName parameter is specified, all signals except the SIGHUP, SIGCLD, SIGALRM, and SIGKILL signals are trapped by default. The dbx debug program cannot ignore the SIGTRAP signal if it comes from a process outside of the debugger. If no arguments are specified, the list of currently ignored signals will be displayed.

Example

To cause dbx to ignore alarm clock time-out signals sent to the application program, enter:

ignore alrm

See the catch subcommand. Also, see Handling Signals in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

list Subcommand

list [ Procedure | SourceLine-Expression [ ,SourceLine-Expression ] ]

The list subcommand displays a specified number of lines of the source file. The number of lines displayed are specified in one of two ways:

By specifying a procedure using the Procedure parameter.

In this case, the list subcommand displays lines starting a few lines before the beginning of the specified procedure and until the list window is filled.

By specifying a starting and ending source line number using the SourceLine-Expression parameter.

The SourceLine-Expression parameter should consist of a valid line number followed by an optional + (plus sign), or - (minus sign), and an integer. In addition, a SourceLine of $ (dollar sign) may be used to denote the current line number; a SourceLine of @ (at sign) may be used to denote the next line number to be listed.

All lines from the first line number specified to the second line number specified, inclusive, are then displayed.

If the second source line is omitted, the first line is printed only.

If the list subcommand is used without parameters, the number of lines specified by $listwindow are printed, beginning with the current source line.

To change the number of lines to list by default, set the special debug program variable, $listwindow, to the number of lines you want. Initially, $listwindow is set to 10.

Examples

To list the lines 1 through 10 in the current file, enter:
```
list 1,10
```
To list 10, or $listwindow, lines around the main procedure, enter:
```
list main
```
To list 11 lines around the current line, enter:
```
list $-5,$+5
```

You can use simple integer expressions involving addition and subtraction in SourceLineExpression expressions. For example:

(dbx) list $
4 {

(dbx) list 5
5 char i = '4';

(dbx) list sub
23 char *sub(s,a,k)
24 int a;
25 enum status k;  .  .  .  

(dbx) move 
25
(dbx) list @ -2
23 char *sub(s,a,k)

See the edit subcommand, the listi subcommand, and the move subcommand. Also, see Displaying the Current File in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

listi Subcommand

listi [ Procedure | at SourceLine | Address [ , Address ] ]

The listi subcommand displays a specified set of instructions from the source file. The instructions displayed are specified by:

Providing the Procedure parameter, where the listi subcommand lists instructions from the beginning of the specified procedure until the list window is filled.
Using the at SourceLine flag, where the listi subcommand displays instructions beginning at the specified source line and continuing until the list window is filled. The SourceLine variable can be specified as an integer or as a file-name string followed by a : (colon) and an integer.
Specifying a beginning and ending address using the Address parameters, where all instructions between the two addresses, inclusive, are displayed.

If the listi subcommand is used without flags or parameters, the next $listwindow instructions are displayed. To change the current size of the list window, use the set $listwindow=Value subcommand.

Disassembly Modes

The dbx program can disassemble instructions for either the POWER family or POWER PC architecture. In the default mode, the dbx program displays the instructions for the architecture on which it is running.

The $instructionset and $mnemonics variables of the set subcommand for the dbx command allow you to override the default disassembly mode. For more information, see the set subcommand for the dbx command.

Flag

at SourceLine

Specifies a starting source line for the listing.

Examples

To list the next 10, or $listwindow, instructions, enter:
```
listi
```
To list the machine instructions beginning at source line 10, enter:
```
listi at 10
```
To list the machine instructions beginning at source line 5 in file sample.c, enter:
```
listi at "sample.c":5
```
To list the instructions between addresses 0x10000400 and 0x10000420, enter:
```
listi 0x10000400, 0x10000420
```

See the list subcommand and the set subcommand. Also, see Debugging at the Machine Level with dbx in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

map Subcommand

map [ > File ]

The map subcommand displays characteristics for each loaded portion of the application. This information includes the name, text origin, text length, data origin, and data length for each loaded module.

Flag

> File

Redirects output to the specified file.

See Debugging at the Machine Level with dbx in AIX 5L Version 5.2 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

To change the next line to be listed to line 12, enter:
```
move 12
```
To change the next line to be listed to line 5 in file sample.c, enter:
```
move "sample.c":5
```

See the list subcommand. Also, see Displaying the Current File in AIX 5L Version 5.2 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 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 exceed 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 debugger forks, and the dbx program continues debugging only the parent process. Multiprocess debugging can also be unsuccessful for the following reasons:

The dbx program is not running in an Xwindows environment.
Xwindows is running but the dbx global $xdisplay variable is not set to a valid display name. The $xdisplay variable is initialized to the shell DISPLAY environment variable. The set Name=Expression dbx subcommand can be used to change the value of the display name.
The /tmp directory does not allow read or write access to the debugging program. The dbx program requires a small amount of space in this directory when controlling an Xwindow environment.
The system does not have enough resources to accommodate a new Xwindow.

If $xdisplay is set to a remote display, the user may not be able to see the newly created Xwindow. If the $xdisplay setting is not correct, Xwindows or other system resources report the cause of the failure.

The dbx program does not distinguish between different types of failures, but the following message is sent when the subcommand is not successful:

Warning: dbx subcommand multiproc fails. dbx 
continued with multproc disabled.

The user-defined configuration of the newly created window can be defined under the dbx_term application name in the .Xdefaults file.

Flags

on	Enables multiprocess debugging.
off	Disables multiprocess debugging.

Examples

To check the current status of multiprocess debugging, enter:
```
multproc
```
To enable multiprocess debugging, enter:
```
multproc on
```
To disable multiprocess debugging, enter:
```
multproc off 
```

See the screen subcommand and the fork subroutine. Also, see Debugging Programs Involving Multiple Processes in AIX 5L Version 5.2 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:

`mutex`	Indicates the symbolic name of the mutex, in the form `$m`MutexNumber.
`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

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 given user thread id.

Examples

To display information about all mutexes, enter:
```
mutex
```
To display information about all locked mutexes, enter:
mutex lock

To display information about mutexes number four, five and six enter:

mutex 4 5 6

The output is similar to:

mutex   obj_addr         type     lock owner  blockers
$m4    0x20003274        non-rec   no
$m5    0x20003280        recursi   no
$m6    0x2000328a        fast      no

To display information about all the mutexes held by thread 1, enter:
```
mutex thnum 1
```
To display information about all the mutexes held by a thread whose user thread id is 0x0001, enter:
```
mutex utid 0x0001
```

See the attribute subcommand, the condition subcommand, the print subcommand, and the thread subcommand.

Also, see. Using Mutexes AIX 5L Version 5.2 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 multi-threaded application program, all the user threads run during the operation, but the program continues execution until the running thread reaches the specified source line. If you wish to step the running thread only, use the set subcommand to set the variable $hold_next. Setting this variable may result in deadlock since the running thread may wait for a lock held by one of the blocked threads.

Examples

To continue execution up to the next source line, enter:
```
next
```
To continue execution up to the third source line following the current source line, enter:
```
next 3
```

See the cont subcommand, goto subcommand, nexti subcommand, set subcommand, and the step subcommand.

nexti Subcommand

nexti [ Number ]

The nexti subcommand runs the application program up to the next instruction. The Number parameter specifies the number of times the nexti subcommand will run. If the Number parameter is not specified, nexti runs once only.

If you use the nexti subcommand in a multi-threaded application program, all the user threads run during the operation, but the program continues execution until the running thread reaches the specified machine instruction. If you wish to step the running thread only, use the set subcommand to set the variable $hold_next. Setting this variable may result in deadlock since the running thread may wait for a lock held by one of the blocked threads.

Examples

To continue execution up to the next machine instruction, enter:
```
nexti
```
To continue execution up to the third machine instruction following the current machine instruction, enter:
```
nexti 3
```

See the gotoi subcommand, next subcommand, set subcommand, and stepi subcommand. Also, see Running a Program at the Machine Level in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

print Subcommand

print Expression ...

print Procedure ( [ Parameters ] )

The print subcommand does either of the following:

Prints the value of a list of expressions, specified by the Expression parameters.
Executes a procedure, specified by the Procedure parameter and prints the return value of that procedure. Parameters that are included are passed to the procedure.

Examples

To display the value of x and the value of y shifted left two bits, enter:
```
print x, y << 2
```
To display the value returned by calling the sbrk routine with an argument of 0, enter:
```
print sbrk(0)
```

See the assign subcommand, the call subcommand, and the set subcommand.

prompt Subcommand

prompt [ "String" ]

The prompt subcommand changes the dbx command prompt to the string specified by the String parameter.

Example

To change the prompt to dbx>, enter:

prompt "dbx>"

See Defining a New dbx Prompt in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

quit Subcommand

quit

The quit subcommand terminates all processes running in the dbx debugging session.

See the detach subcommand.

registers Subcommand

registers [ >File ]

The registers subcommand displays the values of general purpose registers, system control registers, floating-point registers, and the current instruction register.

General purpose registers are denoted by the $rNumber variable, where the Number parameter indicates the number of the register.
Note: The register value may be set to the 0xdeadbeef hexadecimal value. The 0xdeadbeef hexadecimal value is an initialization value assigned to general-purpose registers at process initialization.
Floating point registers are denoted by the $frNumber variable. By default, the floating-point registers are not displayed. To display the floating-point registers, use the unset $noflregs dbx subcommand.

Note: The registers subcommand cannot display registers if the current thread is in kernel mode.

Flag

>File

Redirects output to the specified file.

See the set subcommand and the unset subcommand. Also, see Using Machine Registers in AIX 5L Version 5.2 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

<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