dbx Command

Purpose

Provides an environment to debug and run programs.

Syntax

dbx [-a ProcessID] [-B DebugFile] [-c CommandFile] [-I Directory] [-E DebugEnvironment] [-p oldpath=newpath:...| pathfile] [-u] [-F] [-L ] [-r] [-x] [-v] [-C CoreFile | ObjectFile [CoreFile] ]

Description

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

• 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.

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

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

The -B flag is used to specify an alternative object file or a separate .stab file containing debug information about startup. The alternative object file can be specified only while attaching to a process. The debug information is read from this alternate object file or the .stab debug file instead of the disk copy of the running process. This alternate object file must be the unstripped copy of the original object file; otherwise, it will be ignored. Use the -B flag when the size of the debug section is large. Use the stripped copy of the object file while running and an unstripped copy while debugging. The .stab debug file can be generated through the –bstabsplit linker option. If the -B flag is not specified for a stabsplit executable the dbx command will try to acquire the corresponding .stab file from the executable directory.

Expression Handling

The dbx program can display a wide range of expressions. You can specify expressions in the dbx debug program with C syntax, with some Fortran extensions.

The following operators are valid in the debug program:

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

Command Line Editing

The dbx command provides a command line editing feature similar to the features provided by Korn Shell. vi mode provides vi-like editing features, while emacs mode gives you controls similar to emacs.

These features can be turned on by using dbx subcommand set -o or set edit. To turn on vi-style command line editing, you would type the subcommand set edit vi or set -o vi.

You can also use the EDITOR environment variable to set the editing mode.

The dbx command saves the history of commands, which are entered in the command line, in the .dbxhist history file. If the DBXHISTFILE environment variable is not set, the $HOME/.dbxhist history file is used.

By default, dbx saves the text of the last 128 commands entered. The DBXHISTSIZE environment variable can be used to increase this limit.

Flags

Examples

1. The following example explains how to start the dbx debug program simultaneously with a process. The example uses a program called samp.c. This C program is first compiled with the -g flag to produce an object file that includes symbolic table references. In this case, the program is named samp:

   $ cc -g samp.c -o samp

   When the program samp is run, the operating system reports a bus error and writes a core image to your current working directory as follows:

   $ samp
   Bus Error - core dumped

   To determine the location where the error occurred, enter:

   $ dbx samp

   The system returns the following message:

   dbx version 3.1
   Type 'help' for help.
   reading symbolic information . . . [
   using memory image in core]
     25   x[i] = 0;
   (dbx) quit

2. This example explains how to attach dbx to a process. This example uses the following program, looper.c:

   main()
   {
         int i,x[10];
          
         for (i = 0; i < 10;);
   }

   The program never terminates because i is never incremented. Compile looper.c with the -g flag to get symbolic debugging capability:

   $ cc -g looper.c -o looper

   Run looper from the command line and perform the following steps to attach dbx to the program while it is running:
   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 was originally started with dbx.

3. To add directories to the list of directories to be searched for the source file of an executable file objfile, you can enter:

   $dbx -I /home/user/src -I /home/group/src 
   objfile

   The use subcommand might be used for this function once dbx is started. The use command resets the list of directories, whereas the -I flag adds a directory to the list.

4. To use the -r flag, enter:

   $ dbx -r samp 

   The system returns the following message:

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

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

5. To specify the environment variables for the debug program, enter:

   dbx -E LIBPATH=/home/user/lib -E LANG=Ja_JP objfile

6. To specify alternative object file and libraries while attaching to the process, enter:

   dbx –a 467 –B debug_samp –p /usr/lib/=./dir/debug_libs/

7. To specify the separated debug file at startup, enter:

    dbx –B /usr/debug_samp.stab debug_samp

dbx Subcommands

/ Subcommand

/ [ RegularExpression [ / ] ]

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

Examples

1. To search forward in the current source file for the number 12, enter:

   / 12

2. To repeat the previous search, enter:

   /

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

? Subcommand

? [ RegularExpression [ ? ] ]

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

Examples

1. To search backward in the current source file for the letter z, enter:

   ?z

2. To repeat the previous search, enter:

   ?

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

addcmd Subcommand

addcmd { Number... | all } "commands_string"

The addcmd subcommand adds dbx subcommands to the specified event. This specified event is run whenever the breakpoint, tracepoint, or watchpoint corresponding to the event is executed. The dbx subcommands can be specified through the "commands_string" parameter, which is a group of dbx subcommands separated by a semicolon (;). The event to which the dbx subcommands are to be added can be specified through the Number parameter, or the dbx subcommands can be added to all events by using the all flag.

Flags

Examples

1. To add the where subcommand to event number 1, enter:

   addcmd 1 "where"

2. To add the registers subcommand to event number 2, enter:

   addcmd 2 "registers"

3. To add the where and registers subcommands to event number 3, enter:

   addcmd 3 "where;registers"

See clear subcommand, the delcmd subcommand, the delete subcommand, disable subcommand, enable subcommand, the stop subcommand, the status subcommand, and the trace subcommand. Also see Setting and Deleting Breakpoints in in General Programming Concepts: Writing and Debugging Programs.

alias Subcommand

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

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

Examples

1. To substitute rr for rerun, enter:

   alias rr rerun

2. To run the two subcommands print n and step whenever printandstep is typed at the command line, enter:

   alias printandstep "print n; step"

3. The alias subcommand can also be used as a limited macro facility. For example:

   (dbx) alias px(n) "set $hexints; print n; unset $hexints"
   (dbx) alias a(x,y) "print symname[x]->symvalue._n_n.name.Id[y]"
   (dbx) px(126)
   0x7e

   In this example, the alias px prints a value in hexadecimal without permanently affecting the debugging environment.

assign Subcommand

assign Variable=Expression

The assign subcommand assigns the value specified by the Expression parameter to the variable specified by the Variable parameter.

Examples

1. To assign a value of 5 to the x variable, enter:

   assign x = 5

2. To assign the value of the y variable to the x variable, enter:

   assign x =  y

3. To assign the character value 'z' to the z variable, enter:

   assign  z  =  'z'

4. To assign the boolean value false to the logical type variable B, enter:

   assign  B  =  false

5. To assign the "Hello World" string to a character pointer Y, enter:

   assign  Y  =  "Hello  World"

6. To disable type checking, set the dbx debug program variable $unsafeassign by entering:

   set $unsafeassign

See Displaying and Modifying Variables.

attribute Subcommand

attribute [ AttributeNumber ... ]

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

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

Examples

1. To list information about all attributes, enter:

   attribute

   The output is similar to:

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

2. To list information about attributes 1 and 3, enter:

   attribute 1 3
    

   The output is similar to:

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

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

Also, see Creating Threads, Using Mutexes, and Using Condition Variables in 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 the dbx command, enter:

(dbx) call printf("hello")
hello

printf returns successfully.

case Subcommand

case [ default | mixed | lower | upper ]

The case subcommand changes how the dbx debug program interprets symbols. The default handling of symbols is based on the current language. If the current language is C, C++, or undefined, the symbols are not folded; if the current language is Fortran, the symbols are folded to lowercase. Use this subcommand if a symbol needs to be interpreted in a way not consistent with the current language.

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

Flags

Examples

1. To display the current case mode, enter:

   case

2. To instruct dbx to interpret symbols as they actually appear, enter:

   case mixed

3. To instruct dbx to interpret symbols as uppercase, enter:

   case upper

See Folding Variables to Lowercase and Uppercase.

catch Subcommand

catch [ SignalNumber | SignalName ]

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

Examples

1. To display a current list of signals to be caught by the dbx command, enter:

   catch

2. To trap signal SIGALARM, enter:

   catch SIGALARM

See the ignore subcommand and Handling Signals.

clear Subcommand

clear SourceLine

The clear subcommand removes all stops at a particular 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 General Programming Concepts: Writing and Debugging Programs.

cleari Subcommand

cleari Address

The cleari subcommand clears all the breakpoints at the address specified by the Address parameter.

Examples

1. To remove a breakpoint set at address 0x100001b4, enter:

   cleari 0x100001b4

2. To remove a breakpoint set at the main() procedure address, enter:

   cleari &main

See the clear subcommand, the delete subcommand, and Setting and Deleting Breakpoints in in 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:

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

Examples

1. To display information about all condition variables, enter:

   condition

2. To display information about all condition variables which have waiting threads, enter:
   condition  wait
3. To display information about the condition variable 3, enter:

   condition 3

   The output is similar to:

   cv      obj_addr     num_wait  waiters
   $c3     0x20003290         0

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

Also, see Using Condition Variables in General Programming Concepts: Writing and Debugging Programs.

cont Subcommand

cont [ SignalNumber | SignalName ]

The cont subcommand continues the execution of the application program from the current stopping point until either the program finishes or another breakpoint is reached. If a signal is specified, either by the number specified in the SignalNumber parameter or by the name specified in the SignalName parameter, the program continues as if that signal is received. Signal names are not case-sensitive and the SIG prefix is optional. If no signal is specified, the program continues as if it was not stopped.

Examples

1. To continue program execution from current stopping point, enter:

   cont

2. To continue program execution as though it received the signal SIGQUIT, enter:

   cont SIGQUIT

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

corefile Subcommand

The corefile subcommand displays information from the header of a core file, including the executable name, core file format version information, flags indicating which data is available, the signal that caused the crash, and the execution mode of the process that dumped core.

coremap Subcommand

coremap [ stack | data | sdata | mmap | shm | loader ]

The coremap subcommand displays the mapping of a particular address space region. If you do not specify the region name, the coremap subcommand displays all available mappings.

Examples

1. To display the mapping of a shared memory region, enter:

   coremap shm

2. To display the mapping of a memory mapped region, enter:

   coremap mmap

3. To display the mappings of all of the regions described by the loader entries, enter:

   coremap loader

4. To display all of the available mappings, enter:

   coremap

See the corefile subcommand.

delcmd Subcommand

delcmd EventNumber { Number... | all }

The delcmd subcommand removes the dbx subcommands associated with the specified event. The dbx subcommands to be removed can be specified through Number parameters, or all dbx subcommands associated with the specified event can be removed by using the all flag. The EventNumber parameter specifies the event from which the dbx subcommands are to be removed.

Flags

Examples

1. To remove all the dbx subcommands from event number 2, enter:

   delcmd 2 all

2. To remove dbx subcommand number 1 from event number 3, enter:

   delcmd 3 1

3. To remove dbx subcommands numbers 1 and 2 from event number 2, enter:

   delcmd 2 1 2

See the addcmd subcommand, clear subcommand, the delete subcommand, disable subcommand, enable subcommand, the stop subcommand, the status subcommand, and the trace subcommand. Also see Setting and Deleting Breakpoints in in General Programming Concepts: Writing and Debugging Programs.

delete Subcommand

delete { Number ... | all | tskip [for $tthreadnumber]}

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

The remaining tskip count, which was set using the tskip subcommand for a thread, can be deleted using the tskip flag. Use the status subcommand to display the remaining thread tskip counts. If no thread is specified, the current thread is used.

Flag

Examples

1. To remove all traces and stops from the application program, enter:

   delete all

2. To remove traces and stops for event number 4, enter:

   delete 4

3. To remove the tskip count for thread 3, enter:

   delete tskip for $t3

4. To remove the tskip count for the current thread, enter:

   delete tskip 

See the clear subcommand, the cleari subcommand, the status subcommand, the tskip subcommand, and Setting and Deleting Breakpoints in in 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 received that signal. If no signal is specified, the program continues as if no stop occurred.

Examples

1. To continue execution of the application and exit dbx, enter:

   detach

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

   detach SIGREQUEST

See Using the dbx Debug Program.

disable Subcommand

disable { Number ... all }

The disable subcommand disables traces and stops associated with debug events. The traces and stops to be disabled can be specified through the Number parameters, or all traces and stops can be disabled by using the all flag. Use the status subcommand to display the event numbers associated by the dbx debug program with a trace or stop.

Flags

Examples

1. To disable all traces and stops from the application program, type:

   disable all

2. To disable traces and stops for event number 4, type:

   disable 4

For more information, see enable subcommand, delete subcommand, and status subcommand.

Also, see Setting and Deleting Breakpoints in General Programming Concepts: Writing and Debugging Programs.

display memory Subcommand

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

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

The range of memory displayed is controlled by specifying either:

• 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:

Flag

Examples

1. To display one long word of memory content in hexadecimal starting at the address 0x3fffe460, enter:

   0x3fffe460 / X

2. To display two bytes of memory content as characters starting at the variable y address, enter:

   &y / 2c

3. To display the sixth through the eighth elements of the Fortran character string a_string, enter:

   &a_string + 5, &a_string + 7/c

See Examining Memory Addresses in General Programming Concepts: Writing and Debugging Programs.

down Subcommand

down [ Count ]

The down subcommand moves the current function down the stack Count number of levels. The current function is used for resolving names. The default for the Count parameter is one.

Examples

1. To move one level down the stack, enter:

   down

2. To move three levels down the stack, enter:

   down 3

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

dump Subcommand

dump [ Procedure | "PATTERN" ] [ >File ]

The dump subcommand displays the names and values of all variables in the specified procedure or those variables that match with the specified pattern. If the Procedure parameter is a period (.), then all active variables are displayed. If the Procedure nor "PATTERN" parameter is specified, the current procedure is used. The "PATTERN" parameter is a wildcard expression with the *, ?, and [] meta-characters. When "PATTERN" is used, it displays all the matching symbols in the global space (from all the procedures). If the >File flag is used, the output is redirected to the specified file.

Flags

Examples

1. To display names and values of variables in the current procedure, enter:

   dump

2. To display names and values of variables in the add_count procedure, enter:

   dump add_count

3. To display names and values of variables starting from the character s, enter:

   dump "s*"

4. 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 General Programming Concepts: Writing and Debugging Programs.

edit Subcommand

edit [ Procedure | File ]

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

Examples

1. To start an editor on the current source file, enter:

   edit

2. To start an editor on the main.c file, enter:

   edit main.c

3. To start an editor on the file containing the do_count() procedure, enter:

   edit do_count

See the list subcommand, the vi or vedit command.

enable Subcommand

enable { Number ... all }

The enable subcommand enables traces and stops associated with debug events. The traces and stops to be enabled can be specified through the Number parameters, or all traces and stops can be enabled by using the all flag. Use the status subcommand to display the event numbers associated by the dbx debug program with a trace or stop.

Flags

Examples

1. To enable all traces and stops from the application program, type:

   enable all

2. To enable traces and stops for event number 4, type:

   enable 4

For more information, see disable subcommand, delete subcommand, status subcommand.

Also, see Setting and Deleting Breakpoints in General Programming Concepts: Writing and Debugging Programs.

fd Subcommand

fd [ raw ] [ start [ end ] ]

The fd subcommand displays file descriptor information. Using the raw option causes output to be displayed in raw hex format. Other optional arguments include start and end indices. If no index is given, then information about all available file descriptors is displayed. Use of one index displays a single file descriptor; two an inclusive range.

Examples

1. To view information about all file descriptors in hex, type:

   fd raw

2. To view information about file descriptors in the range of 3 to 5, type:

   fd 3 5

file Subcommand

file [ File ]

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

Examples

1. To change the current source file to the main.c file, enter:

   file main.c

2. To display the name of the current source file, enter:

   file

See the func subcommand. Also, see Changing the Current File or Procedure and Displaying the Current File in General Programming Concepts: Writing and Debugging Programs.

frame Subcommand

frame [ num ]

The frame subcommand changes the current function to the function corresponding to the specified stack frame number num. The current function is used for resolving names. The numbering of the stack frames starts from the currently active function stack frame (the function frame that is currently active is always numbered 0). If there are n frames, the frame of the main function is numbered n-1. When no frame number is specified, information about the function associated with the current frame is displayed.

Examples

1. To move to frame number 2, enter:

   frame 2

2. To display the current function on the stack, enter:

   frame

See the up and down subcommands. Also, see Changing the Current File or Procedure and Displaying a Stack Trace in General Programming Concepts: Writing and Debugging Programs.

func Subcommand

func [ Procedure ]

The func subcommand changes the current function to the procedure or function specified by the Procedure parameter. If the Procedure parameter is not specified, the default current function is displayed. Changing the current function implicitly changes the current source file to the file containing the new function; the current scope used for name resolution is also changed.

Examples

1. To change the current function to the do_count procedure, enter:

   func do_count

2. To display the name of the current function, enter:

   func

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

goto Subcommand

goto SourceLine

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

Example

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

goto 6

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

gotoi Subcommand

gotoi Address

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

Example

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

gotoi 0x100002b4

See the goto subcommand.

handler Subcommand

handler { atfork | cancel_cleanup [ all | pthread id ] }

The handler subcommand displays information about atfork or cancelation cleanup handlers registered using pthread_atfork, and pthread_cleanup_push, respectively. Using the atfork option, the names of routines registered as pre, parent and child atfork handlers are displayed (with their respective arguments in the case of non-posix compliant atfork handlers). The cancel_cleanup option causes display of all registered cancelation cleanup handlers, with an optional pthread id parameter specifying a particular pthread, or all specifying all pthreads. If none is given, then the cancelation cleanup handlers for the current pthread are displayed, if there are any.

Examples

1. To view information about all registered atfork handlers, type:

   handler atfork

2. To view information about any registered cancelation cleanup handlers for the current pthread, type:

   handler cancel_cleanup

3. To view information about any registered cancelation cleanup handlers for the pthread object referred to as $t2, type:

   handler cancel_cleanup 2

help Subcommand

help [ Subcommand | Topic ]

The help subcommand displays help information for dbx subcommands or topics, depending upon the parameter you specify. Entering the help subcommand with the Subcommand parameter displays the syntax statement and description of the specified subcommand. Entering the help subcommand with the Topic parameter displays a detailed description of the specified topic. You do not need to provide the entire topic string with the help subcommand. The dbx program can recognize the topic if you provide a substring starting from the beginning of the topic. The following topics are available:

Examples

1. To list all available dbx subcommands and topics, enter:

   help

2. To display the description of the dbx subcommand list, enter:

   help list

3. To display the description of the dbx topic set_variables, enter:

   help set_variables

ignore Subcommand

ignore [ SignalNumber | SignalName ]

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

The signal to be trapped can be specified by:

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

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

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

Example

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

ignore alrm

See the catch subcommand. Also, see Handling Signals in General Programming Concepts: Writing and Debugging Programs.

kthread Subcommand

kthread [ raw ] [ info | ru ] [ tid ]

The kthread subcommand displays information about kernel threads. Using the raw option causes all output to be displayed in hex, regardless of whether it can be displayed in a more human-readable format. Using no arguments, summary information about all kernel threads is printed. Supplying a numeric thread ID causes the dbx command to show information about a single thread. The info option produces more detailed output about a thread, from the user thread structure. Use of the ru option displays the ti_ru data member, which contains resource usage information.

For more information about user threads, see thread subcommand.

Examples

1. To find information about the thread that is currently running, you must first obtain information about all threads by typing the following on the command line:

   kthread

   Threads that were running (or runnable) just before the dbx command stopped the process are marked with an asterisk. Choose the correct thread ID based on the output and type:

   kthread info tid

2. To view resource information in hex about all threads, type:

   kthread raw ru

limitbp Subcommand

limitbp ( bp1, Limit ) [ ( bp2, [ + ] Limit ) … ]

The limitbp subcommand instructs the dbx command to stop running the debug program only when the breakpoint is executed a specified number of times. If the '+' character precedes the limit, the limit of that event is changed to the sum of the limit that is specified in the subcommand and the count of the number of times that the event is already executed. That is, the dbx command stops running the debug program when the breakpoint is about to be executed for the specified Limit after the limitbp subcommand is already run.

Examples

1. To instruct the dbx command to stop execution of the debug program when breakpoint 1 is about to be executed the 10th time, enter:

   limitbp (1, 10)

2. To instruct the dbx command to stop execution of the debug program when either breakpoint 1 is about to be executed the 15th time or breakpoint 2 is about to be executed the 20th time or both, enter:

   limitbp (1, 15) (2, 20)

3. To instruct the dbx command to stop execution of the debug program when breakpoint 1 is about to be executed the 20th time after the limitbp subcommand was run, enter:

   limitbp (1, +20)

list Subcommand

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

The list subcommand displays a specified number of lines of the source file. The number of lines displayed are specified in one of following 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 must consist of a valid line number followed by an optional + (plus sign), or - (minus sign), and an integer. In addition, a SourceLine of $ (dollar sign) might be used to denote the current line number; a SourceLine of @ (at sign) might be used to denote the next line number to be listed.

• By specifying the $listwindow internal dbx variable.

  If the list subcommand is used without parameters, the number of lines specified by the $listwindow variable are printed, beginning with the current source line. To change the default number of lines, set the $listwindow variable to the required number of lines. The $listwindow variable is a special debug program variable. Initially, the $listwindow variable is set to 10.

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

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

When you specify an address after the at parameter in the list subcommand, the list subcommand displays the source lines that correspond to the specified address. Address can be specified as a decimal or hexadecimal unsigned integer, or a mnemonic that corresponds to registers, such as $iar, $tfiar, and $tfhar or debug variables.

Examples

1. To list the lines 1 through 10 in the current file, enter:

   list 1,10

2. To list 10, or $listwindow, lines around the main procedure, enter:

   list main

3. To list 11 lines around the current line, enter:

   list $-5,$+5

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

   (dbx) list $
   4 {
   
   (dbx) list 5
   5 char i = '4';
   
   (dbx) list sub
   23 char *sub(s,a,k)
   24 int a;
   25 enum status k;  .  .  .  
   
   (dbx) move 
   25
   (dbx) list @ -2
   23 char *sub(s,a,k)

5. You can display the source lines that correspond to a specific address. For example:

   (dbx) r
   [1] stopped in main at line 5
       5 int i, sum = 0;
   
   (dbx) list at $iar
   source file: "tt.c"
       5 int i, sum = 0;
       6 int last = 0;
       7
       8 scanf("%d", &last);
       9 
       10 for ( i = 1; i <=last; i++ ) { 
       11 sum += i; 
       12 } 
       13 printf("sum = %d\n", sum); 
       14 
   
   (dbx) list at ($iar+16) 
   source file: "tt.c" 
       8 scanf("%d", &last); 
       9 
       10 for ( i = 1; i <= last; i++ ) { 
       11 sum += i; 
       12 } 
       13 printf("sum = %d\n", sum); 
       14 
       15 return 0; 
       16 }

See the edit subcommand, the listi subcommand, and the move subcommand. Also, see Displaying the current file in 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 filename 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 PowerPC® architecture. In the default mode, the dbx program displays the instructions for the architecture on which it is running.

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

Flag

Examples

1. To list the next 10, or $listwindow, instructions, enter:

   listi

2. To list the machine instructions beginning at source line 10, enter:

   listi at 10

3. To list the machine instructions beginning at source line 5 in file sample.c, enter:

   listi at "sample.c":5

4. To list the instructions between addresses 0x10000400 and 0x10000420, enter:

   listi 0x10000400, 0x10000420

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

malloc Subcommand

malloc [ > File ]

The malloc subcommand with no options prints out a list of enabled options and allocation policies as well as a statistical summary of malloc usage since process startup.

malloc [ allocation [ { address | size | heap | pid | tid | time } { "<" | "==" | ">" "!=" | “~=” ]} Value ] ] [ > File ]

The allocation option to the malloc subcommand displays a sorted list of all the allocations currently held by the process. Using an optional attribute RELOP value argument allows for a more narrow selection of active allocations.

malloc [ freespace [ { address | size | heap } { "<" | "==" | ">" | "!=" | “~=”]} Value ] ] [ > File ]

The freespace option to the malloc subcommand displays a sorted list of all the free space available in the process heap. Using an optional attribute RELOP value argument allows for a more narrow selection of free space nodes.

malloc address

The malloc subcommand with address displays the nodes details of the address, the address need not be a starting address of an allocated or free node.

Flags

For more information, see System Memory Allocation Using the malloc Subsystem in General Programming Concepts: Writing and Debugging Programs.

map Subcommand

map { [Format] [ entry ModuleNumber [ , ModuleNumber ] | Address | SymbolName ] [for $tthreadnumber] [ > File ] }

When called without one of the above specifications, the map subcommand displays information for all loaded portions of the application.

If no Format parameter is specified, the dbx command uses the value of the $mapformat internal variable. If no Format parameter is specified and $mapformat is unset, the dbx command displays loaded module information in normal mode.

The TLS data information of the specified thread is displayed if the loaded module has TLS data. If no thread is specified, the current thread is used.

Flags

Examples

1. To list all loaded modules in abbreviated mode, type:

   map abbr

2. To list loaded modules 3 through 5 in verbose mode, type:

   map verbose entry 3,5

3. To list the loaded module that contains address 0x20001000, type:

   map 0x20001000

4. To list the loaded module that contains variable example, type:

   map example

5. To list the loaded modules in normal mode with TLS data information of the modules for the thread 2, type:

   map normal for $t2

For more information, see the $mapformat internal variable. See also, Debugging at the Machine Level with dbx in General Programming Concepts: Writing and Debugging Programs.

move Subcommand

move SourceLine

The move subcommand changes the next line to be displayed to the line specified by the SourceLine parameter. This subcommand changes the value of the @ (at sign) variable.

The SourceLine variable can be specified as an integer or as a file name string followed by a : (colon) and an integer.

Examples

1. To change the next line to be listed to line 12, enter:

   move 12

2. To change the next line to be listed to line 5 in file sample.c, enter:

   move "sample.c":5

See the list subcommand. Also, see Displaying the Current File in General Programming Concepts: Writing and Debugging Programs.

multproc Subcommand

multproc [ on | parent | child | off ]

The multproc subcommand specifies the behavior of the dbx debug program when forked and exceed processes are created. The on flag is used to specify that a new dbx session is created to debug the child path of a fork. The original dbx continues to debug the parent path. The parent and child flags are used to specify a single path of a fork to follow. All flags except off enable dbx to follow an exceed process. The off flag disables multiprocess debugging. If no flags are specified, the multproc subcommand returns the status of multiprocess debugging.

The dbx program uses the X Window System for multiprocess debugging. The dbx program opens as many windows as needed for multiprocessing. The title for each child window is the process ID (pid) of the child process. To switch between processes, use the X Window System handling techniques to activate the window where the dbx command session is displayed. If the system does not have the X Window System support, a warning message is issued when the debugger forks, and the dbx program continues debugging only the parent process. Multiprocess debugging can also be unsuccessful for the following reasons:

• The dbx program is not running in the X Window System environment.
• The X Window System 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 might not be able to see the newly created Xwindow. If the $xdisplay setting is not correct, the X Window System or other system resources report the cause of the failure.

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

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

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

Flags

Examples

1. To check the status of multiprocess debugging, enter:

   multproc

2. To enable multiprocess debugging, enter:

   multproc on

3. To disable multiprocess debugging, enter:

   multproc off 

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

Flags

Examples

1. To display information about all mutexes, enter:

   mutex

2. To display information about all locked mutexes, enter:
   mutex  lock
3. To display information about mutexes number four, five and six enter:

   mutex 4 5 6

   The output is similar to:

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

4. To display information about all the mutexes held by thread 1, enter:

   mutex thnum 1

5. 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 General Programming Concepts: Writing and Debugging Programs.

next Subcommand

next [ Number ]

The next subcommand runs the application program up to the next source line. The Number parameter specifies the number of times the next subcommand runs. If the Number parameter is not specified, next runs once only.

If you use the next subcommand in a multithreaded application program, all the user threads run during the operation, but the program continues execution until the running thread reaches the specified source line. If you want to step the running thread only, use the set subcommand to set the variable $hold_next. Setting this variable might result in deadlock since the running thread might wait for a lock held by one of the blocked threads.

Examples

1. To continue execution up to the next source line, enter:

   next

2. To continue execution up to the third source line following the current source line, enter:

   next 3

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

nexti Subcommand

nexti [ Number ]

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

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

Examples

1. To continue execution up to the next machine instruction, enter:

   nexti

2. To continue execution up to the third machine instruction following the current machine instruction, enter:

   nexti 3

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

onceblock Subcommand

onceblock [ uninit | done ]

The onceblock subcommand displays information about blocks of initialization code registered using the pthread_once routine. With no arguments, information about all registered once blocks are shown. The optional uninit and done flags display only the once blocks that either have not, or have already executed, respectively, while supplying a numeric once ID displays information for a single once block.

Examples

1. To find out if any once blocks are not yet executed, type:

   onceblock uninit

plugin Subcommand

plugin [ Name [ Command ] ]

The plugin subcommand passes the command specified by the Command parameter to the plug-in specified by the Name parameter. If no parameters are specified, the names of all available plug-ins are displayed.

Examples

1. To list all available plug-ins, type:

   plugin

2. To start the subcommand "help" of a plug-in named "sample", type:

   plugin sample help

3. To start the subcommand "interpret 0x20000688" of a plug-in named "xyz", type:

   plugin xyz interpret 0x20000688

See the pluginload subcommand and pluginunload subcommand. Also see Developing for the dbx Plug-in Framework in General Programming Concepts.

pluginload Subcommand

pluginload File

Examples

pluginload /home/user/dbx_plugins/libdbx_sample.so

See the plugin subcommand and pluginunload subcommand. Also see Developing for the dbx Plug-in Framework in General Programming Concepts.

pluginunload Subcommand

pluginunload Name

The pluginunload subcommand unloads the plug-in specified by the Name parameter.

Examples

pluginunload sample

See the plugin subcommand and pluginload subcommand. Also see Developing for the dbx Plug-in Framework in General Programming Concepts.

print Subcommand

print Expression ...

print Procedure ( [ Parameters ] )

The print subcommand does either of the following operations:

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

Examples

1. To display the value of x and the value of y shifted left two bits, enter:

   print x, y << 2

2. To display the value returned by calling the sbrk routine with an argument of 0, enter:

   print sbrk(0)

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

printbp Subcommand

printbp [ bp1 ] [ bp2 ] ... | all

The printbp subcommand instructs the dbx command to print the number of times that each of the breakpoints or all the subcommands were run and the details of the limit on the breakpoint, if a limit was set on it.

Examples

1. To instruct the dbx command to print the number of times that breakpoint 1 is run and the details of the limit set, enter:

   printbp 1

2. To instruct the dbx command to print the number of times that breakpoints 1 and 2 are run and to limit the number of times that breakpoints 1 and 2 can be allowed to run if a limit is set on them, enter:

   printbp 1, 2

3. To instruct the dbx command to print the number of times that all breakpoints are run and the details of a limit on any breakpoint, if applicable, enter:

   printbp all

proc Subcommand

proc [ raw ] [ cred | cru | ru | sigflags | signal ]

The proc subcommand displays information about the process. Usage of the raw option causes output to be displayed in raw hex, rather than interpreting values in a more human-readable fashion. Using the proc subcommand with no additional arguments outputs general information about the process, as is stored in the user process data structure. The cred option displays contents of the pi_cred data member, which describes the credentials of the process. The cru and ru options display data members pi_cru and pi_ru respectively, which contain resource usage information. The sigflags and signal options display information relating to the current signal status and registered signal handlers, as contained within the pi_sigflags and pi_signal data members.

Examples

1. To view resource usage information for the current process (or core file) in raw hex, type:

   proc raw ru

2. To view signal handler information, type:

   proc signal

prompt Subcommand

prompt [ "String" ]

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

Example

To change the prompt to dbx>, enter:

prompt "dbx>"

See Defining a New dbx Prompt in General Programming Concepts: Writing and Debugging Programs.

quit Subcommand

quit

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

See the detach subcommand.

registers Subcommand

registers [ ALL | $tthreadnumber … ] [ >File ]

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

• General-purpose registers are denoted by the $rNumber variable, where the Number parameter indicates the number of the register.

  Note: The register value might be set to the 0xdeadbeef hexadecimal value. The 0xdeadbeef hexadecimal value is an initialization value assigned to general-purpose registers at process initialization.

• 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.
• Vector registers are denoted by the $vrNumber variable. The $novregs internal variable controls whether vector registers are displayed. The $novregs variable is set by default, and vector registers are not displayed. When $novregs is not set, and vector registers are valid (either debugging a program on a vector capable processor, or analyzing a core file containing vector registers state), then all the vector registers are displayed (vr0–vr31, vrsave, vscr). Vector registers can also be referenced by type. For example, the $vrNf (float), $vrNs (short), and $vrNc (char) vector register variables can be used with the print and assign subcommands to display and set vector registers by type.
• Vector scalar registers are denoted by the $vsrNumber variable. By default, the vector scalar registers are not displayed. Unset $novsregs variable to display the vector scalar registers whenever vector scalar registers are valid (either debugging a program on a vector scalar capable processor, or analyzing a core file containing vector scalar registers state). As vector scalar registers are a superset of legacy floating point registers and vector registers, the debug variable $novsregs , when unset, takes precedence over $noflregs and $novsregs , whenever vector scalar registers state is valid. The registers subcommand will then display the vector scalar registers with the legacy register aliases along with it in braces. The floating point register aliases correspond to the low 64-bits only. Vector scalar registers can also be referenced by type as similar to vector registers. For example, the $vsrNf (float), $vsrNs (short), $vsrNc (char), $vsrNg (double) and $vsrNll (long long) vector scalar register variables can be used with the print and assign subcommands to display and set vector scalar registers by type.
• In the multithreaded environment option ALL displays the register details for all available threads. The register details of individual threads are displayed by specifying the thread number along with registers subcommand. Using the registers subcommand with no options display the registers for the current thread.

Flag

See the set subcommand and the unset subcommand. Also, see Using Machine Registers in General Programming Concepts: Writing and Debugging Programs.

Example

registers $t1 $t2 $t3

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

See the run subcommand.

resource Subcommand

resource { owner | waiter } [ all | pthread id ]

The resource subcommand displays information about which resources pthreads currently hold or are waiting on. The first argument, which is required, indicates whether you are interested in viewing pthreads that own resources or are waiting for them. The second argument can be used to indicate all pthreads, or a specific one. If none is given, then only information relevant to the current pthread is displayed, if applicable.

Examples

1. To ascertain whether the current pthread holds any resources, type:

   resource owner

2. To view which resources any pthreads are waiting on, type:

   resource waiter all

return Subcommand

return [ Procedure ]

The return subcommand causes the application program to execute until a return to the procedure specified by the Procedure parameter is reached. If the Procedure parameter is not specified, execution ceases when the current procedure returns.

Examples

1. To continue execution to the calling routine, enter:

   return

2. To continue execution to the main procedure, enter:

   return main 

rwlock Subcommand

rwlock [read | write | RwlockNumber....]

The rwlock subcommand displays information about rwlocks. If the RwlockNumber parameter is given, the rwlock subcommand displays information about the specified rwlocks. If no flags or parameters are specified, the rwlock subcommand displays information about all rwlocks.

The information for each rwlock is as follows:

Flags

Examples

1. To display information about all rwlocks, enter:

   rwlock

   The output is similar to:

   rwl     flag_value    owner status
   $rwl        1         $t1    write
           rsleeps[     0]:
           wsleeps[     0]:

2. To display information about all rwlocks in write mode:

   rwlock write

   The output is similar to:

   rwl     flag_value    owner status
   $rwl        1         $t1    write
           rsleeps[     0]:
           wsleeps[     0]:

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

run Subcommand

run [ Arguments ] [ <File ] [ >File ] [ > >File ] [ 2>File ] [ 2> >File ] [ >&File ] [ > >&File ]

The run subcommand starts the object file. The Arguments are passed as command-line arguments.

Flags

Example

To run the application with the arguments blue and 12, enter:

run blue 12

See the rerun subcommand.

screen Subcommand

screen

The screen subcommand opens an Xwindow for the dbx command interaction. You continue to operate in the window in which the process originated.

The screen subcommand must be run while the dbx debug program is running in the X Window System environment. If the screen subcommand is issued in a non-Xwindow environment, the dbx program displays a warning message and resumes debugging as if the screen subcommand was not given. The screen subcommand can also be unsuccessful in the following situations:

• The dbx program is not running in the X Window System environment.
• The X Window System is running but the dbx global $xdisplay variable is not set to a valid display name. The $xdisplay variable is initialized to the DISPLAY environment variable. The dbx subcommand set Name=Expression changes the value of the display name.
• The X Window System is running, but the TERM environment variable is not set to a valid command name to start a new window.
• The /tmp directory does not allow read or write access to the program. The dbx program requires a small amount of space in this directory when the screen command is executed.
• System does not have enough resources to accommodate a new Xwindow.

The dbx program does not distinguish between different types of failures, but the program does send the following message:

Warning: dbx subcommand screen fails. dbx 
continues.

If $xdisplay is set to a remote display, you might not be able to see the newly created Xwindow. If the $xdisplay setting is not correct, the X Window System or other system resources report the problem.

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

Example

To open an Xwindow for dbx command interaction, enter:

screen

set Subcommand

set [ Variable=Expression ]

The set subcommand defines a value for the dbx debug program variable. The value is specified by the Expression parameter; the program variable is specified by the Variable parameter. The name of the variable must not conflict with names in the program being debugged. A variable is expanded to the corresponding expression within other commands. If the set subcommand is used without arguments, the variables currently set are displayed.

Process {PID} may have performed a transaction - $texasr, $tfiar, $tfhar 
are valid and may be inspected

The $unsafe variables limit the usefulness of the dbx debug program in detecting errors.

Examples

1. To change the default number of lines to be listed to 20, enter:

   set $listwindow=20

2. To disable type checking on the assign subcommand, enter:

   set $unsafeassign

3. To disassemble machine instructions for the POWER7 processor, enter:

   set $instructionset="pwr7"

4. To display strings encoded in the IBM®-eucCN code set, enter:

   set $codepage="IBM-eucCN"

5. To specify a limit of four characters in the identifiers and a limit of twelve characters in the strings that are displayed in a stack trace, enter the following command:

   set $compact_bt_ident=6
   set $compact_bt_string=12

   The stack trace that uses identifiers such as long_identifier, long_variable_name_str, and recursive_fun, and string such as this_is_a_really_long_string looks similar to the following output:

   long_i...(a = 11, long_v... = "this_is_a_re..."), line 3 in "example.c"
   recurs...(), line 13 in "example.c"

See the unset subcommand. Also, see Changing Print Output with Special Debug Program Variables in General Programming Concepts: Writing and Debugging Programs.

set edit [vi, emacs] or set -o [vi, emacs] Subcommand

The set subcommand with the -o or edit option might be used to turn on one of the line edit modes. If the set-o vi or set edit vi command is given, you are placed in the input mode of the vi line editor. If the set -o emacs or set edit emacs command is given, you are placed in the input mode of the emacs line editor.

Example

1. To turn on the vi line editor, enter:

   set-o vi

   or

   set edit vi

sh Subcommand

sh [ Command ]

The sh subcommand passes the command specified by the Command parameter to the shell for execution. The SHELL environment variable determines which shell is used. The default is the sh shell. If no argument is specified, control is transferred to the shell.

Examples

1. To run the ls command, enter:

   sh ls

2. To escape to a shell, enter:

   sh

3. To use the SHELL environment variable, enter:

   sh echo $SHELL

See Running Shell Commands from dbx in General Programming Concepts: Writing and Debugging Programs.

skip Subcommand

skip [ Number ]

The skip subcommand continues execution of the application program from the current stopping point. A number of breakpoints equal to the value of the Number parameter are skipped and execution then ceases when the next breakpoint is reached or when the program finishes. If the Number parameter is not specified, it defaults to a value of one.

Example

To continue execution until the second breakpoint is encountered, enter:

skip 1

Also see the cont subcommand.

source Subcommand

source File

The source subcommand reads dbx subcommands from the file specified by the File parameter.

Example

To read the dbx subcommands in the cmdfile file, enter:

source cmdfile

See Reading dbx Subcommands from a File in General Programming Concepts: Writing and Debugging Programs.

status Subcommand

status [ more ] [ >File ]

The status subcommand displays all user-defined breakpoints, tracepoints, and watchpoints, in addition to the remaining thread tskip counts (set by using the tskip subcommand). If the more parameter is specified, the status subcommand also displays the dbx subcommands associated with the breakpoints, tracepoints, and watchpoints. The status subcommand lists enabled events with square brackets ([]) surrounding the event number, disabled events with periods (..) surrounding the event number, and deferred events with angle brackets (<>) surrounding the event number.

The > flag sends the output of the status subcommand to a file specified in the File parameter.

Flag

Examples

1. To display all user-defined breakpoints, tracepoints, and watchpoints, as well as the remaining thread tskip counts, type:

   status

   The output is similar to:

   [1] stop at 13
   [2] stop at 14
   .3. stop at 15
   .4. stop at 16
   [5] stop at 17 ( count = 0, limit = 3 )
   <6> stop at 18 if g > 10
   <7> stop in func
   
   Remaining tskip counts:
   tskip 2 for $t1
   tskip 1 for $t5

   In the example output, events 3 and 4 are disabled, and events 6 and 7 are deferred.
2. To display all user-defined breakpoints, tracepoints, and watchpoints with associated dbx subcommands, enter:

   status more

   The output is similar to:

          [1] stop at 13
              [1] where 
          .2. stop at 14
              [1] where
              [2] registers        
          <3> stop at 15 if g > 10
              [1] where; registers

See the addcmd subcommand, the clear subcommand, the delete subcommand, the delcmd subcommand, the tskip subcommand, the stop subcommand, and the trace subcommand for the dbx command.

Also, see Setting and Deleting Breakpoints in General Programming Concepts: Writing and Debugging Programs.

step Subcommand

step [ Number ]

The step subcommand runs source lines of the application program. Specify the number of lines to be executed with the Number parameter. If the Number parameter is omitted, it defaults to a value of 1.

If you use the step subcommand on a multithreaded application program, all the user threads run during the operation, but the program continues execution until the running thread reaches the specified source line. If you want to step the running thread only, use the set subcommand to set the variable $hold_next. Setting this variable might result in deadlock since the running thread might wait for a lock held by one of the blocked threads.

Examples

1. To continue execution for one source line, enter:

   step

2. To continue execution for five source lines, enter:

   step 5

3. To prevent the dbx program from single-stepping the printf function, as illustrated in the following example code:

   60 printf ("hello world \n");

   enter:

   set $stepignore="function"; step

See the cont subcommand, the goto subcommand, the next subcommand, the set subcommand, and the stepi subcommand.

stepi Subcommand

stepi [ Number ]

The stepi subcommand runs instructions of the application program. Specify the number of instructions to be executed in the Number parameter. If the Number parameter is omitted, it defaults to one.

If used on a multithreaded application program, the stepi subcommand steps the running thread only. All other user threads remain stopped.

Examples

1. To continue execution for one machine instruction, enter:

   stepi 

2. To continue execution for 5 machine instructions, enter:

   stepi 5

See the gotoi subcommand, the nexti subcommand, and the step subcommand.

stop Subcommand

stop { [Variable ] [ at SourceLine | in Procedure | on load ["ModuleName"] ] [ if Condition ]} [ "{ "Limit" }" ]

The stop subcommand halts the application program when certain conditions are fulfilled. The program is stopped when:

• The Condition is true when the if Condition flag is used.
• The Procedure is called if the in Procedure flag is used.
• The Variable is changed if the Variable parameter is specified.
• The SourceLine line number is reached if the at SourceLine flag is used.

  The SourceLine variable can be specified as an integer or as a file name string followed by a : (colon) and an integer.

• The ModuleName loaded module is loaded or unloaded if the on load flag is used and the ModuleName parameter is specified.
  The optional ModuleName variable can be specified as a single module name, or as a module name paired with a member name in the format:

  ModuleName(MemberName)

• Any loaded module is loaded or unloaded if the on load flag is used and the ModuleName parameter is not specified.

You can set the Limit parameter to instruct the dbx command to ignore a condition for a specified number of times. In other words, the Limit parameter specifies the number of times that the specified condition must be fulfilled before the debug program execution is stopped.

After any of these commands, the dbx debug program responds with a message reporting the event it built as a result of your command. The message includes the event ID associated with your breakpoint along with an interpretation of your command. The syntax of the interpretation might not be the same as your command. For example:

stop in main
[1] stop in main
stop at 19 if x == 3
[2] stop at "hello.c":19 if x = 3
stop in func
<3> stop in func
stop g 
<4> stop g
stop in getdata {3} 
[5] stop in getdata ( count = 0, limit = 3 ) 

The numbers in square brackets ([]) are the event identifiers associated with the breakpoints. The dbx debug program associates event numbers with each stop subcommand. When the program is halted as the result of one of the events, the event identifier is displayed along with the current line to show which event caused the program to stop. The numbers in angle brackets (<>) are the event identifiers for the deferred events. A deferred event is an event without having any breakpoint, tracepoint, or watchpoint associated with it, and is created whenever the input command involves the symbols that are not currently loaded in the memory. A normal event displayed in square brackets ([]) is also converted into a deferred event whenever the corresponding module is unloaded. Whenever the module corresponding to the deferred event is loaded into the memory, the deferred event is converted into the normal event, and the corresponding breakpoint, tracepoint, or watchpoint is created. The events that you create coexist with internal events that are created by the dbx command, so the event numbers might not always be sequential.

A limit can be associated with an event after its creation by using the limitbp subcommand. To view the limit associated with an event, the printbp subcommand can be used.

Use the status subcommand to view these numbers. You can redirect output from status to a file. Use the delete or clear subcommand to turn the stop subcommand off, or use the enable or disable subcommands. Use the addcmd subcommand to add dbx subcommands to the specified event number and the delcmd subcommand to delete the associated dbx subcommands from the specified event number.

In a multithreaded application program, all user threads are halted when any user thread hits a breakpoint. A breakpoint set on a source line or function is hit by any user thread which executes the line or function, unless you specify conditions (as in example 9). The following aliases specify the conditions automatically:

• bfth(Function, ThreadNumber)
• blth(SourceLine, ThreadNumber)

ThreadNumber is the number part of the symbolic thread name as reported by the thread subcommand (for example, 5 is the ThreadNumber for the thread name $t5). These aliases are actually macros which produce the expanded subcommands shown in the following example:

stopi at &Function if ($running_thread == ThreadNumber)
stop at SourceLine if ($running_thread == ThreadNumber)

Flags

Examples

1. To stop execution at the first statement in the main procedure, enter:

   stop in main

2. To stop execution when the value of the x variable is changed on line 12 of the execution, enter:

   stop x at 12

3. To stop execution at line 5 in file sample.c, enter:

   stop at "sample.c":5

4. To check the value of x each time that the dbx command runs a subroutine within func1, enter:

   stop in func1 if x = 22

5. To check the value of x each time that the dbx command begins to run func1, enter:

   stopi at &func1 if x = 22

6. To stop the program when the value of Variable changes, enter:

   stop Variable

7. To stop the program whenever Condition evaluates to true, enter:

   stop if (x > y) and (x < 2000)

8. The following example shows how to display active events and remove them:

   status
   [1] stop in main
   [2] stop at "hello.c":19 if x = 3
   delete 1
   status
   [2] stop at "hello.c":19 if x = 3
   clear 19
   status
   (dbx)

   The delete command eliminates events by event identifier. The clear command deletes breakpoints by line number.
9. To place a breakpoint at the start of func1 only when executed by thread $t5, enter one of the following equivalent commands:

   stopi at &func1 if ($running_thread == 5)

   or

   bfth(func1, 5)

10. To stop the program when any module is loaded or unloaded, enter:

    stop on load

11. To stop the program whenever module Module is loaded or unloaded, enter:

    stop on load "Module"

12. To stop the program whenever member Member of module Module is loaded or unloaded, enter:

    stop on load "Module(Member)"

13. To stop the program in a function getdata when it is called the third time, enter:

    stop in getdata {3}

See the addcmd subcommand, the clear subcommand, the delete subcommand, the delcmd subcommand, disable subcommand, enable subcommand, the limitbp subcommand, the printbp subcommand, the status subcommand, the stopi subcommand, and the trace subcommand. Also, see Setting and Deleting Breakpoints in General Programming Concepts: Writing and Debugging Programs.

stophwp Subcommand

stophwp Address Size

Example

1. To stop the program when the contents of the 4 byte memory region starting at address 0x200004e8 change, enter:

   stophwp 0x200004e8 4

See the tracehwp subcommand.

stopi Subcommand

stopi { [Address] [ at Address | in Procedure ] [ if Condition ]}

The stopi subcommand sets a stop at the specified location:

• With the if Condition flag, the program stops when the condition true is specified.
• With the Address parameter, the program stops when the contents of Address change.
• With the at Address flag, a stop is set at the specified address.
• With the in Procedure flag, the program stops when the Procedure is called.

Flags

Examples

1. To stop execution at address 0x100020f0, enter:

   stopi at 0x100020f0

2. To stop execution when the contents of address 0x100020f0 change, enter:

   stopi 0x100020f0

3. To stop execution when the contents of address 0x100020f0 are changed by thread $t1, enter:

   stopi 0x200020f0 if ($running_thread == 1)

See the stop subcommand. Also, see Debugging at the Machine Level with dbx in General Programming Concepts: Writing and Debugging Programs.

thdata Subcommand

thdata [ $tthreadnumber [ all | key1 … ] … ] | [ all ]

Examples

1. To print the data associated to the current thread with all the available keys, enter:

   (dbx) thdata $t1
   Thread  :  1
   	Key : 1 Data pointer : 0x200f7a28
   	Key : 2  Data pointer : 0x200f7aa8
   	Key : 3 Data pointer : 0x200f7ac4
   (dbx) 

2. To print the data associated to multiple threads and multiple keys, enter:

   (dbx) thdata $t1 2 3 $t2
   Thread  :  1
   	Key : 2  Data pointer : 0x200f7aa8
   	Key : 3 Data pointer : 0x200f7ac4
   Thread : 2
   	Key : 2  Data pointer : 0x200f7b24
   	Key : 3 Data pointer : 0x200f7ba4
   (dbx)

See Thread-Specific Data in General Programming Concepts: Writing and Debugging Programs

thread Subcommand

Display Selected Threads

thread { [ info ] [ - ] [ ThreadNumber ... ] } | current | run | susp | term | wait

Select an Individual Thread

thread current [ - ] ThreadNumber

Hold or Release Threads

thread { hold | unhold } [ - ] [ ThreadNumber ... ]

Help for the options displayed

thread { help}

The thread subcommand displays and controls user threads.

The first form of the thread subcommand can display information in two formats. If the thread subcommand is th, then the information displayed is in the first format. If the thread subcommand is th -, then the information displayed is in the second format. If no parameters are given, information about all user threads is displayed. If one or more ThreadNumber parameters are given, information about the corresponding user threads is displayed. When the thread subcommand displays threads, the current thread line is preceded by a >. If the running thread is not the same as the current thread, its line is preceded by a *. The information displayed by the thread subcommand in both the formats is described below.

The information displayed by the thread subcommand in the first format is as follows:

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.

Kernel thread-related information

User thread-related information

If the option set $thcomp is set, then the information is displayed in the compressed form as shown in the following example.

m           mode           (k)ernel (u)ser
k           k-state        (r)unning (w)aiting (s)uspended (z)ombie
u           u-state        (r)unning (R)unnable (s)uspended (t)erminated

                           (b)locked (c)reating
h           held           (yes) (n)o
s           scope          (s)ystem (p)rocess
c           cancellation   not pending:  (e)nabled & (d)eferred,
                                         (e)nabled & (a)sync, (d)isabled
                           pending    :  (E)nabled & (D)eferred,
                                         (E)nabled & (A)sync, (D)isabled
j           joinable       (yes) (n)o
b           boosted        value of boosted field in pthread structure
plk         kernel thread  (oth)er  (fif)o  (rr)-> round-robin
            policy
plu         user thread    (oth)er  (fif)o  (rr)-> round-robin
            policy
prk         kernel thread  hex number
            policy
pru         user thread    hex number
            policy
k-tid                      kernel thread id in hex
u-tid                      pthread id in hex
fl                         value of flags field in pthread structure in hex
sta                        value of state field in pthread structure in hex
cs                         value of the current signal
wchan                      event for which thread is waiting
function                   function name           

The second form of the thread subcommand is used to select the current thread. The print, registers, and where subcommands of the dbx debug program all work in the context of the current thread. The registers subcommand cannot display registers if the current thread is in kernel mode.

The third form of the thread subcommand is used to control thread execution. Threads can be held using the hold flag, or released using the unhold flag. A held thread is not resumed until it is released.

Flags

Examples

1. To display information about threads that are in the wait state, enter:
   thread  wait
   The output is similar to:

   thread  state-k   wchan state-u   k-tid mode held scope function 
    $t1     wait            running   17381   u   no   pro  main
    $t3     wait            running    8169   u   no   pro  iothread

2. To display information about several given threads, enter:

   thread 1 3 4

   The output is similar to:

   thread  state-k   wchan state-u   k-tid mode held scope function
    $t1     wait           running   17381   u   no   pro  main
    $t3     wait           running    8169   u   no   pro  iothread
   >$t4     run            running    9669   u   no   pro  save_thr

3. To make thread 4 the current thread, enter:
   thread  current 4
4. To hold thread number 2, enter:
   thread  hold 2
5. To display information about threads that are in the wait state, in the second format, enter:

   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  

6. To display information about several given threads in the second format, enter:

   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 General Programming Concepts: Writing and Debugging Programs.

tls Subcommand

tls map

The tls subcommand takes only one flag that it uses to display the TLS initialization template origin and length for each loaded TLS module.

tm_status Subcommand

tm_status

The tm_status subcommand displays the contents of the $texasr variable (transaction exception and summary register) and interprets the contents to determine the cause and nature of a transaction failure.

Example

To display and interpret the values that are stored in the $texasr variable, enter the following command:

(dbx) tm_status

An output that is similar to the following example is displayed:

REGISTER : TEXASR = 0x100000018C000001
Bit(s)   |Field                     |Meaning
_________________________________________________________________________________
0-7      Failure Code                TM_SIG_DELIVERED | Failed due to signal delivery
7        Failure Persistent          Failure is transient
31       Abort                       Execution of TM instruction caused Abort
32       Suspended                   Failure while in Suspended State
34-35    Privilege                   During Failure process-thread privilege state was 0
36       Failure                     Summary Failure recording has been performed
37       TFIAR (in)exact             TFIAR is exact
38       Rollback Only Transaction   non-ROT tbegin. initiated
52-63    Transaction Level           1

tnext Subcommand

tnext [Number]

The tnext subcommand runs the running thread up to the next source line. The Number parameter specifies the number of times the tnext subcommand runs. If the Number parameter is not specified, tnext runs once only. This subcommand can be started only on system-scope threads.

All the threads are run during this operation. To catch breakpoints during this operation, set the $catchbp dbx variable. If the $catchbp variable is set and a breakpoint is reached for another thread, the tnext subcommand is not repeated for the remaining number of times.

Examples

1. To continue execution of the running thread up to the next source line, enter:

   tnext

2. To continue execution of the running thread up to the third source line following the current source line, enter:

   tnext 3

See the tnexti subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

tnexti Subcommand

tnexti [Number]

The tnexti subcommand runs the running thread up to the next instruction. The Number parameter specifies the number of times the tnexti subcommand runs. If the Number parameter is not specified, tnexti runs once only. This subcommand can be started only on system-scope threads.

All the threads are run during this operation. To catch breakpoints during this operation, set the $catchbp dbx variable. If the $catchbp variable is set and a breakpoint is reached for another thread, the tnexti subcommand is not repeated for the remaining number of times.

Examples

1. To continue execution of the running thread up to the next machine instruction, enter:

   tnexti

2. To continue execution of the running thread up to the third machine instruction following the current machine instruction, enter:

   tnexti 3

See the tnext subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

trace Subcommand

trace [ SourceLine | Expression at SourceLine | Procedure | [ Variable ] [ at SourceLine | in Procedure ] | on load ModuleName ] [ if Condition ]

The trace subcommand prints tracing information for the specified procedure, function, source line, expression, or variable when the program runs. The SourceLine variable can be specified as an integer or as a file name string followed by a : (colon) and an integer. A condition can be specified. The dbx debug program associates a number with each trace subcommand. Use the status subcommand to view these numbers. Use the delete subcommand to turn tracing off. You can enable and disable traces using the enable and disable subcommands, respectively.

ModuleName(MemberName)

If the on load flag is used without the ModuleName parameter, the dbx command traces the load and unload of all modules.

By default, tracing is process-based. To make a thread-based trace, specify the thread in a condition (as in example 8).

Flags

Examples

1. To trace each call to the printf procedure, enter:

   trace printf

2. To trace each execution of line 22 in the hello.c file, enter:

   trace "hello.c":22

3. To trace changes to the x variable within the main procedure, enter:

   trace x in main

4. To trace the data address 0x2004000, enter:

   set $A=0x2004000
   trace $A

   Note: The tracei subcommand is designed to trace addresses.
5. You can restrict the printing of source lines to when the specified Procedure is active. You can also specify an optional Condition to control when trace information must be produced. For example:

   (dbx) trace in sub2
   [1] trace in sub2
   (dbx) run
   trace in hellosub.c:  8  printf("%s",s);
   trace in hellosub.c:  9  i = '5';
   trace in hellosub.c:  10  }

6. You can display a message each time a procedure is called or returned. When a procedure is called, the information includes passed parameters and the name of the calling routine. On a return, the information includes the return value from Procedure. For example:

   (dbx) trace sub
   [1] trace sub
   (dbx) run
   calling sub(s = "hello", a = -1, k = delete) from function main
   returning "hello" from sub

7. You can print the value of Expression when the program reaches the specified source line. The lines number and file are printed, but the source line is not. For example:

   (dbx) trace x*17 at "hellosub.c":8 if (x > 0)
   [1] trace x*17 at "hellosub.c":8 if x > 0
   (dbx) run
   at line 8 in file "hellosub.c": x*17 = 51
    
   (dbx) trace x
   [1] trace x
   initially (at line 4 in "hello.c"):  x = 0
   after line 17 in "hello.c":  x = 3

8. To trace changes to the x variable that are made by thread $t1, enter the following command:

   (dbx) trace x if ($running_thread == 1)

9. To trace the load or unload of all modules, enter the following command:

   trace on load

10. To trace the load or unload of module Module, enter the following command:

    trace on load "Module"

11. To trace the load or unload of member Member in module Module, enter the following command:

    trace on load "Module(Member)"

Also, see the tracei subcommand.

tracehwp Subcommand

tracehwp Address Size

Examples

1. To trace each time the contents of the 4 byte memory region starting at address 0x200004e8 change, enter the following command:

    tracehwp 0x200004e8 4 

See the stophwp subcommand.

tracei Subcommand

tracei [ [Address] [at Address | in Procedure] | Expression at Address] [if Condition]

The tracei subcommand turns on tracing when:

• The contents of the address specified by the Address parameter change if the Address flag is included.
• The instruction at Address is run if the at Address parameter is specified.
• The procedure specified by Procedure is active if the in Procedure flag is included.
• The condition specified by the Condition parameter is true if the if Condition flag is included.

Flags

Examples

1. To trace each instruction executed, enter the following command:

   tracei

2. To trace each time the instruction at address 0x100020f0 is executed, enter the following command:

   tracei at 0x100020f0

3. To trace each time the contents of memory location 0x20004020 change while the main procedure is active, enter the following command:

   tracei 0x20004020 in main

4. To trace each time the instruction at address 0x100020f0 is executed by thread $t4, enter the following command:

   tracei at 0x100020f0 if ($running_thread == 4)

See the trace subcommand. Also, see Debugging at the Machine Level with dbx in General Programming Concepts: Writing and Debugging Programs.

tskip Subcommand

tskip [Number]

The tskip subcommand continues the execution of the running thread from the current stopping point. The number of thread-level breakpoints specified by the Number parameter is skipped for the running thread. This subcommand can be started for system-scope threads only.

All the other threads are run during this operation, and all breakpoints and watchpoints specified by the user are caught. The execution can cease when any thread hits a breakpoint or watchpoint. Even though the execution started by tskip subcommand can stop because of an event for another thread, the tskip count specified for the previous thread is still active and the number of thread-level breakpoints specified by the tskip count is ignored for that thread when the process continues. When the thread ends, the tskip count associated with it is deleted.

Use the status subcommand to view the remaining tskip count for the threads. Use the delete subcommand to delete the remaining tskip count for the threads.

Example

tskip 1

See the cont subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

tstep Subcommand

tstep [Number]

The tstep subcommand runs the specified number of source lines from the current source line for the running thread. The Number parameter specifies the number of times the tstep subcommand runs. If the Number parameter is not specified, tstep runs once only. This subcommand can be started only on system-scope threads.

Examples

1. To continue execution of the running thread up for one source line, enter:

   tstep

2. To continue execution of the running thread for five source lines, enter:

   tstep 5

3. To prevent the dbx program from single-stepping the printf function, as illustrated in the example code:

   60 printf ("hello world /n");

   enter:

   set $stepignore="function"; step

See the cont subcommand, the goto subcommand, tnext subcommand, the set subcommand, and the tstepi subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

tstepi Subcommand

tstepi [Number]

The tstepi subcommand runs the specified number of instructions from the current instruction for the running thread. The Number parameter specifies the number of times the tstepi subcommand runs. If the Number parameter is not specified, tstepi runs once only. This subcommand can be started only on system-scope threads.

All the threads are run during this operation. If $hold_next is set, all the threads except the running thread is held.

Examples

1. To continue execution of the running thread up for one machine instruction, enter:

   tstepi

2. To continue execution of the running thread for five machine instructions, enter:

   tstepi 5

See the gotoi subcommand, tnexti subcommand, and the tstep subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

tstop Subcommand

tstop { in Procedure | [Variable] at SourceLine [ if Condition ] } [for $tthreadnumber]

Thread-level breakpoints can be set on system scope threads only. When a thread-level and a process-level breakpoint are hit at the same time, both the breakpoints are processed and the thread-level breakpoint is ported. When the thread terminates, the events associated with it are deleted.

Flags

Examples

1. To stop execution at the first statement in the func procedure while running thread 2, enter:

   tstop in func for $t2

2. To stop execution of the current thread when the value of the x variable is changed on line 12 of the execution, enter:

   tstop x at 12

See the ttrace subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

tstophwp Subcommand

tstophwp address size [for $tthreadnumber]

The tstophwp subcommand sets a thread-level hardware watchpoint stop for the specified memory region. The program stops when the contents of the region changes while running the specified thread. The thread specified must exist at the same time as the creation of the event. The current thread is used if no thread is specified. The thread-level watchpoint events can be set only for system-scope threads. When the thread terminates, the events associated with it are deleted.

Flags

Example

To stop the program when thread 2 is running and the contents of the 4-byte memory region starting at address 0x200004e8 change, enter:

tstophwp 0x200004e8 4 for $t2

See the ttracehwp subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

tstopi Subcommand

tstopi { in Procedure | [Address] at Address [ if Condition ] } [for $tthreadnumber]

Thread-level breakpoints can be set on system scope threads only. When a thread-level and a process-level breakpoint are hit at the same time, both the breakpoints are processed and the thread-level breakpoint is reported. When the thread terminates, the events associated with it are deleted.

Flags

Example

1. To stop execution at address 0x100020f0 while running thread 2, enter:

   tstopi at 0x100020f0 for $t2

2. To stop execution when the func procedure is entered while running the current thread, enter:

   tstopi in func

See the ttracei subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

ttrace Subcommand

ttrace { [Variable] at SourceLine | Procedure } [ if Condition ] [for $tthreadnumber]

The ttrace subcommand prints tracing information when the specified thread runs for the specified procedure, function, source line, and variable. The SourceLine variable can be specified as an integer or as a file name string followed by a colon (:) and an integer. The dbx debug program associates a number with each ttrace subcommand. Use the status subcommand to view these numbers. Use the delete subcommand to turn tracing off. You can enable and disable traces using the enable and disable subcommands, respectively.

The current thread is used if no thread is specified. Thread-level trace can be set only for system-scope threads. The thread specified must exist at the same time as the creation of the event. When the thread ends, the events associated with it are deleted.

Flags

Examples

1. To trace each call to the printf procedure while running thread 2, enter:

   ttrace printf for $t2

2. To trace each execution of line 22 in the hello.c/ file while the current thread is running, enter:

   ttrace "hello.c":22

See the ttracei subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

ttracei Subcommand

ttracei [Address] at Address [if Condition] } [for $tthreadnumber]

The current thread is used if no thread is specified. Thread-level trace can be set only for system-scope threads. The thread specified must exist at the time as the creation of the event. When the thread ends, the events associated with it are deleted.

Flags

Example

1. To trace each time the instruction at address 0x100020f0 is executed while thread 3 is running, enter:

   tracei at 0x100020f0 for $t3

2. To trace each time the instruction at address 0x100020f0 is executed by the current thread, enter:

   tracei at 0x100020f0 

See the ttrace subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

ttracehwp Subcommand

ttracehwp address size [for $tthreadnumber]

Thettracehwp subcommand sets a thread-level hardware watchpoint trace for the specified memory region. The dbx debug program prints tracing information when the contents of the region change while running the specified thread. The thread specified must exist at the same time as the creation of the event. The current thread is used if no thread is specified. The thread-level watchpoint events can be set only for system-scope threads. When the thread terminates, the events associated with it are deleted.

Flags

Example

To trace each time the contents of the 4-byte memory region starting at address 0x200004e8 change while running thread 2, enter:

ttracehwp 0x200004e8 4 for $t2

See the tstophwp subcommand. Also, see Debugging Programs Involving Multiple Threads in General Programming Concepts: Writing and Debugging Programs.

unalias Subcommand

unalias Name

The unalias subcommand removes the alias specified by the Name parameter.

Example

To remove an alias named printx, enter:

unalias printx

See the alias subcommand. Also, see Creating Subcommand Aliases in General Programming Concepts: Writing and Debugging Programs.

unset Subcommand

unset Name

The unset subcommand deletes the dbx debug program variable associated with the name specified by the Name parameter.

Example

To delete the variable inhibiting the display of floating-point registers, enter:

unset $noflregs

See the set subcommand. Also, see Changing Print Output With Special Debugging Variables in General Programming Concepts: Writing and Debugging Programs.

up Subcommand

up [ Count ]

The up subcommand moves the current function up the stack Count number of levels. The current function is used for resolving names. The default for the Count parameter is one.

Examples

1. To move the current function up the stack 2 levels, enter:

   up 2

2. To display the current function on the stack, enter:

   up 0

See the down subcommand. Also, see Changing the Current File or Procedure, Displaying a Stack Trace in General Programming Concepts: Writing and Debugging Programs.

use Subcommand

use [ { + | Directory | '['RegularExpression = NewPath']' } ... ]

The use subcommand sets the list of directories to be searched and path mappings to be applied when the dbx debug program looks for source files. If the use subcommand is specified without arguments, the current list of directories to be searched and path mappings to be applied are displayed.

The @ (at-sign) is a special directory that directs the dbx program to look at the full-path name information in the object file, if it exists. If you have a relative directory called @ to search, you must use ./@ in the search path.

The use subcommand uses the + (plus-sign) to add more directories or mappings to the list of directories to be searched. The + represents the current list of directories and mappings when specified as input to the use subcommand. To append a directory or mapping to the end of the current list, the + must be specified before the new directory or mapping. To add a directory to the beginning of the current list, the + must be specified after the new directory or mapping. If you have a directory named +, specify the full-path name for the directory (for example, ./+ or /tmp/+).

The use subcommand interprets strings enclosed in [ and ] (square brackets) which contain an = (equal-sign) as path mappings. These path mappings are used with the special @ directory. They make it easier for the user to express source file locations in the case that entire directory structures of source files are relocated after compilation.

Examples

1. To change the list of directories to be searched to the current directory (.), the parent directory (..), and the /tmp directory, enter:

   use . .. /tmp

2. To change the list of directories to be searched to the current directory (.), the directory the source file was located in at compilation time (@), and the ../source directory, enter:

   use . @ ../source

3. To add the /tmp2 directory to the list of directories to be searched, enter:

   use + /tmp2

4. To add the /tmp3 directory to the beginning of the list of directories to be searched, enter:

   use /tmp3 +

5. To express that source files whose full-path name information begins with /home/developer are now located under /mnt, enter:

   use + [/home/developer=/mnt]

6. To direct the dbx program to first look under /latest and then, if the file does not exist there, to look under /stable for files with full-path name information beginning with /home/developer, enter:

   use + [/home/developer=/latest] [/home/developer=/stable]

Also, see the edit subcommand and the list subcommand.

whatis Subcommand

whatis Name

The whatis subcommand displays the declaration of Name, where the Name parameter designates a variable, procedure, or function name, optionally qualified with a block name.

Examples

1. To display the declaration of the x variable, enter:

   whatis x

2. To display the declaration of the main procedure, enter:

   whatis main

3. To display the declaration of the x variable within the main function, enter:

   whatis main.x

4. To print the declaration of an enumeration, structure, or union tag, use $$TagName:

   (dbx) whatis $$status
   enum $$status { run, create, delete, suspend };

where Subcommand

where [ all | $tthreadumber [(startframe endframe)] …] [ startframe endframe ] [ >File ]

The where subcommand displays a list of active procedures and functions associated with the frame numbers startframe to endframe. The numbering of the stack frame starts from the currently active function stack frame (which is always numbered 0). If there are n frames, the frame of the main function is numbered n-1. By using the >File flag, the output of this subcommand can be redirected to the specified file.

In the multithreaded environment option all displays the stack details for all available threads. The stack details of individual threads are displayed by specifying the thread number along with where subcommand. If start and end frames for individual threads are not specified, stack frames are displayed by the global start and end frame numbers. Command with no options displays the stack frames of current thread.

Flag

See the frame subcommand, up subcommand, and down subcommand. Also, see Displaying a Stack Trace in General Programming Concepts: Writing and Debugging Programs.

Example

See the frame subcommand, up subcommand, and down subcommand. Also, see Displaying a Stack Trace in General Programming Concepts: Writing and Debugging Programs.

whereis Subcommand

whereis Identifier

The whereis subcommand displays the full qualifications of all the symbols whose names match the specified identifier. The order in which the symbols print is not significant.

Examples

To display the qualified names of all symbols named x, enter:

whereis x

Also, see the which subcommand.

which Subcommand

which Identifier

The which subcommand displays the full qualification of the identifier. The full qualification consists of a list of the outer blocks with which the identifier is associated.

Examples

To display the full qualification of the x symbol, enter:

which x

See the whereis subcommand. Also. see Scoping of Names in in General Programming Concepts: Writing and Debugging Programs.

Files

Debugging applications that use transactional memory

For applications that use transactional memory (TM), the most reliable debugging aids are the transaction exception and summary register ($texasr), transaction failure handler address register ($tfhar), and transaction failure instruction address register ($tfiar) variables.

The $texasr, $tfhar, and $tfiar variables can be displayed by using the print subcommand, which is similar to displaying the $iar variable. However, you cannot manipulate the values in these registers by using the assign subcommand.

(dbx) list at $tfiar

(dbx) list at $tfhar

The cause of a transaction failure can be determined by using the $texasr variable. The tm_status subcommand interprets the cause and nature of a transaction failure.

The dbx command monitors the occurrence of a transaction and displays the cause of the transaction failure through the following series of messages. These following messages are displayed after you run the run subcommand, the rerun subcommand, or the continue subcommand.

• Process {PID} may have failed a transaction - $texasr, $tfiar, $tfhar are valid and may be inspected
• Process {PID} may have performed a transaction - $texasr, $tfiar, $tfhar, are valid and may be inspected

  This message is displayed only when the $trace_good_transaction internal variable is set.

• Process {PID} is in Transactional State – debugging efforts through dbx may result in repeated transaction failure or undefined behavior
• Process {PID} is in Suspended State – debugging efforts through dbx may result in repeated transaction failure or undefined behavior

Where PID is the process ID of the process that is debugged.