Table of Contents

What is dbx?

This tutorial discusses how to use the dbx utility to debug executable programs. dbx provides a powerful tool for monitoring the execution of programs written in any language. With dbx, you can suspend program execution, continue execution, skip sections of code, and display and set the values of variables. In addition, you can manipulate external files by invoking your choice of editors and issue shell commands without exiting the debugging environment. The dbx utility can be used to examine corefiles as well as executable programs. By examining a core memory image file, you can use the dbx command to examine the state of the program when it faulted.

Using dbx

When you compile your program, use the -g flag to save symbolic information needed by dbx in the object file along with any executable code.

An interactive session with dbx is invoked by issuing the command:

	% dbx [filename]

The dbx utility examines an executable program or core image file, specified as a command line argument. If no filename is specified, dbx will prompt for one. After reading the symbolic information from the specified file, dbx will prompt interactively for commands.

A help facility is available from within the dbx utility. To request information, issue the command:

	help [dbx_command]

To exit from a dbx session and return to the shell prompt, issue the command:

	quit

To use dbx, you will need to perform the following steps:

1. compile your FORTRAN codes with the -g flag
2. link your code to build an executable
3. run dbx on your executable to debug your code

Commonly Used dbx Commands

The following list includes commonly used commands. While the next few sections of this tutorial describe these commands in detail, learning to use the debugger is best done by actually using it.

ALIAS         builds a user alias
ASSIGN        changes the values of variables
CONT          resumes execution after a breakpoint
DELETE, CLEAR removes a breakpoint or trace event
DUMP, PRINT   displays the values of variables and expressions
EDIT          invokes an editor on a source code file
FILE          changes the current source code file
FUNC          changes the current procedure or function
HELP          accesses on-line help
LIST          displays the current source code file
NEXT, STEP    suspends execution after a number of lines of code have executed
QUIT          exits dbx 
SH            passes a command to the interactive shell process for execution
STATUS        lists all breakpoints and trace events
STOP          sets a breakpoint
TRACE         sets a trace event
WHATIS        displays data types and dimension information
WHERE         displays of stack trace of current procedures and parameters
WHEREIS       displays the scope of an identifier
WHICH         lists the identifier resolutions

Displaying and Manipulating Source Code

The dbx utility can be used to search through and display source files for a program. dbx keeps track of the current file, current procedure and current line. Usually, the current procedure, current line and current file are initialized to the main routine, its first line, and the file containing it. As you display the source file, and start and stop execution of your code, the values for the current line and procedure will change. When working with core image files, dbx will initialize the current line, current procedure and current file to the line, procedure, and file containing the source statement where the process ended.

The list command displays lines of source code:

	list [ line1 [, line2 ] ]
	list procedure/function

With no arguments specified, the list command will display the next ten lines of source code in the current file. You may specify lines of code referencing by number, relative to the beginning of the source file, or name a function or procedure to list.

As dbx executes your code, the current procedure, current file, and current line are all updated to relate to the line of source code previously executed. However, you can use the func and file commands to change the current function and current file, without having dbx run any part of your program.

	func [ procedure/function ]
	file [ filename ]

With no arguments, these commands will display the name of the current function or source filename.

The dbx utility supports text searching in a manner similar to that used by the vi editor. The current file can be searched for text matching regular expressions in the following manner:

	/ regularexpression
	? regularexpression

The slash ("/") operator searches forward from the current line and the question-mark ("?") operator searches backward from the current line. Searches will wrap around the end of a file, and if a match is found, the current line will be set to the line containing the matching text.

From within the dbx environment, the edit command can be used to invoke an external text editor to alter your source code.

	edit [ filename ]
	edit procedure/function

With no arguments, the edit command edits the current file. Otherwise, this command selects the specified file or the source file containing the specified function to be edited. The default editor is vi, but you can override this default by setting the environment variable EDITOR to another editor before invoking dbx.

Displaying Values and Modifying Variables

The dbx utility allows you to display a wide range of expressions in either C, Pascal or FORTRAN syntax. An expression can be either a variable or constant, or a collection of variables and constants combined with one or more operators. dbx supports the following operators inside expressions:

	Algebraic:	+, - , *, / (floating), div (integral), mod, exp
	Bitwise:	|, bitand, xor, ~, <<, >>
	Logical:	or, and, not
	Comparison:	<, >, <=, >=, <>, !=, =, ==
	Other:		sizeof

Within expressions, variables can be referred to by name and arrays can be subscripted by brackets ("[]") or parenthesis ("()"). In addition, pointers can be dereferenced by using either a prefix asterisk ("*") or a postfix caret ("^"), as in C.

Expressions that contain identifiers may be hard to resolve, especially if different variables share the same name. Two commands help determine which symbol is used when there are multiple symbols with the same name:

	whereis identifier
	which identifier

The whereis command lists all possible symbols. The which command identifies the symbol to which the reference will be resolved. Both commands specify variables as program.procedure.variable. This syntax can be used to override the default resolution of an identifier. As an example, consider referring to the variable x declared in procedure sub in the program prog inside the file code.f, instead of the variable x in the current function. To do so, use the fully qualified name, namely "prog.sub.x".

The print command displays values of expressions:

	print expression [, expression ...]

	dump [ procedure/function ] [> filename]

The assign command alters the contents of a variable:

	assign variable = expression

Setting and Deleting Breakpoints

The dbx utility provides you with the capability to set breakpoints within a program. When the program reaches a breakpoint, it halts. Other dbx commands can then be used to examine the state of your program to determine the location of errors within your code.

The four variations of the stop command set breakpoints:

	stop at linenumber [ if condition ]
	stop in procedure/function [ if condition ]
	stop variable [ if condition ]
	stop if condition

The first variation sets breakpoints by line numbers, relative to the beginning of the source code file. The second version can be used to stop execution at the beginning of a given procedure or function. The third variation halts execution whenever the value of a variable changes. The last version of the stop command continually evaluates the listed condition, stopping execution whenever this condition becomes true.

All variations of the stop command refer to a specified condition, which must be an expression that evaluates to true or false. If the condition is specified, execution will be halted only if the condition is true when this breakpoint is reached.

dbx labels each breakpoint with an event number. After handling a stop command, dbx responds with the event number and event description. The events you create with stop or trace commands exist along with internal events created by dbx, so user-initiated events might not always be sequentially labeled.

The status command displays all of the current events. To delete breakpoints, use the delete or clear command. The delete command references breakpoints by their event identifier. As an example, the command "delete 2" will remove the breakpoint having an event identifier of 2. The clear command references breakpoints by source code line number. Thus, the command "clear 19" will remove the breakpoint associated with line 19 in the current source code file.

Tracing Execution

When tracing execution, the dbx utility will display information about the state of the running program while it is executing. Be aware that tracing your code will slow its execution considerably, depending on how much work dbx has to perform to trace your code.

The five variations of the trace command set trace events:

	trace [ in procedure/function [ if condition ]]
	trace linenumber [ if condition ]
	trace procedure/function [ in procedure/function ] [ if condition ]
	trace expression at linenumber [ if condition ]
	trace variable [ in  ] [ if condition ]

The first two forms of the trace command print source code lines when the program reaches a specific line number or procedure. The third variation displays values of passed parameters and the name of the calling routine when the procedure is called. It also displays the return value upon exiting the procedure or function. The last two forms display the values of a variable or expression when the program reaches a specific line number or procedure. Be aware that the last version of the trace command will slow the execution of the program substantially, since dbx will need to continually monitor the value of a variable after each line of code to detect changes in this value.

All forms of the trace command refer to a specified condition, which must be an expression that evaluates to true or false. The display of trace information can be controlled by specifying this condition, since trace information will only be produced if this given condition evaluates to true.

Issuing trace commands creates trace events. These events can be displayed by issuing the status command and deleted by using the delete or clear commands, as previously described.

Running your Program

The run command starts the execution of your program:

	run [arguments] [< inputfile] [> outputfile]

Once a program has been stopped, dbx provides several ways to continue its execution from this point. Use the cont command to continue program execution. The step and next commands can be used to step through a program one line at a time. These two commands are equivalent, except if the next line to be run involves a call to a function or procedure. In this case, the step command will stop in the called routine, whereas the next command will stop execution after the called routine has finished, at the next instruction after the subroutine call.

The alias facility allows you to build your own commands from the dbx command set. Once defined, aliases can be used in place of the dbx primitives. By default, the following aliases are supplied by dbx:

	ALIAS	COMMAND		ALIAS	COMMAND
	  t	where		  p	print
	  j	status		  n	next
	  st	stop		  l	list
	  s	step		  e	edit
	  r	run		  h	help
	  x	registers	  d	delete
	  q	quit		  c	cont

The alias command is used to set and display aliases:

	alias [ aliasname [ commandname ]] 

With no arguments, the alias command displays all the current aliases in effect. With one argument, the alias command displays the replacement string associated with that alias. With two arguments, the alias command will substitute the later argument for the alias each time it is used. Aliases can include multiple commands and incorporate parameters. Creating these more complex aliases is beyond the scope of this tutorial. You can find more information on this topic in the Programming Tool and Interface manual listed in the Reference portion of this document.

Aliases can be removed by issuing the unalias command:

	unalias aliasname

If you wish, you can customize your dbx sessions by placing your preferred aliases into a special initialization file named .dbxinit in your home directory. Commands from this file are executed before dbx begins to read commands from standard input. Normally, the file .dbxinit contains alias commands, but it may also contain any valid dbx command.

Shell Commands

The sh command allows you to run shell commands without exiting the debugging environment:

	sh [ commandline ]

Tutor Example #1

Tutor Example #2

Problems with dbx

Incorrect variable values may be reported by dbx after the occurrence of an underflow exception error. If this happens, typing 'ignore 8' on the dbx command line before the program is run, will cause the program to run as it would without dbx, and report correct variable values.

References

• AIX Operating System Commands Reference, Volume 1
• AIX User's Manual
• AIX Programming Tools and Interface Guide
• man pages for the utility dbx

Cleanup

This tutor will leave the following files in your working directory:

	dbxc
	dbxc.c
	dbxf
	dbxf.f