This document is intended to help the new user of the dbx symbolic debugger package on the IBM RS/6000s. It assumes a working knowledge of basic UNIX commands and their functions. For this information, you should see U-002, "Introduction to the UNIX Operating System". This and other Information Technology and Communication (ITC) documents can be found on the document shelves near Room 235 Wilson Hall.
The dbx symbolic debugger can be used with programs written in C, FORTRAN and Pascal. Before using the dbx debugger, you must compile your programs with the -g option. The following command, issued at the UNIX prompt, will compile the C program stored in the file prog.c, creating an output file named a.out. The -g option tells the compiler to include symbol table references in a.out for use by the debugger.
xlc -g prog.c
For more information on compiling source code, see the documents
U-015, Using FORTRAN on the RS/6000
U-016, Using C on the RS/6000
the IBM reference manuals, and the man pages for xlc, xlf, and xlp.
Issue the command dbx to invoke the debugger. You may specify the name of the program that you want to run in the debugger. If you do not specify a program name, dbx will prompt you for the name, offering you the default name of a.out. If you want to debug the program a.out, press Return (or Enter) at the prompt:
enter object file name (default is `a.out', ^D to exit):.
If a file named core exists in your current directory and was created by your program, dbx will examine the core image and try to find where the error that caused the core dump occured. Dbx will then print out that line.
In the following example, the FORTRAN program ex1.f is compiled, creating an output file named a.out. (By default, UNIX compilers create programs named a.out; if you want to specify a different name, use the -o option in your compile command. Note that if you are debuging a file named a.out, you will need to use the file subcommand [see the Quick Reference at the end of this document] to tell dbx the filename of the source code in order to use the list subcommand). The -g option must be included in the compile command. After the program was compiled, it was executed. The execution caused a core dump, so the dbx debugger was invoked. Because the name of the program was not specified, dbx prompts for the name of the program. The carriage return was pressed and dbx loads the program a.out. Because a core file was created by a.out in the directory, dbx examines the core image and then prints out the line that caused the dump.
holmes: /home/yourid $ xlf -g -qcheck ex1.f
** ex1 === End of Compilation 1 ===
** swap === End of Compilation 2 ===
1501-510 Compilation successful for file ex1.f.
holmes: /home/yourid $ a.out
Trace/BPT trap(coredump)
holmes: /home/yourid $ dbx
dbx version 3.1 for AIX.
Type 'help' for help.
enter object file name (default is `a.out', ^D to exit): CR
reading symbolic information ...
[using memory image in core]
1525-502 Array subscript out of bounds. in ex1 at line 12 in file "ex1.f"
12 if ( a(i) .gt. a(i+1) ) call swap(a,i)
(dbx)
If a core file did not exist, you would just see the dbx prompt after pressing the carriage return.
Use the dbx run subcommand. The syntax of the command is as follows:
run [arguments] [<inFile] [>outFile | >>outFile] [2>errFile | 2>>errFile]
For example:
run execute program
run <data >>results execute program, get input from file data,
append output to the file results
If your program expects arguments, specify them in the run subcommand. For example, if you would usually invoke your program with the command:
myprog -verbose
issue the command:
run -verbose
in dbx.
You can use the stop subcommand (prior to issuing a run subcommand) to specify breakpoints in the code. You can remove these breakpoints with the clear and delete subcommands.
After a break, you can continue execution by using the cont, return, or skip subcommands, or you can step through the code, line by line, by using the next and step subcommands.
To tell dbx to inform you of what is going on as the code executes, use the status subcommand.
The syntax and options for the above commands and more are detailed in the Quick Reference section at the end of this document.
Exit dbx by issuing the dbx quit subcommand. By default, the quit subcommand is aliased to q.
There are many ways, both on-line and off-line, to get help.
NOTE: man will also bring up other manual pages that match the keyword that you just specified. Thus, man screen will bring up manual pages for the screen subcommand of the kernel debug program in addition to the manual page for the screen subcommand of the dbx program.
Syntax Explanation of Example <alias> Example
alias [aliasName [dbxSubcommand | "dbxSubcommand(s) string"]] alias print current aliases alias s print string associated with alias s alias k "step 5;print i" create alias k; each time k is issued, dbx will execute the commands contained in the quotes
assign variable = expression assign x=3 assign value 3 to variable x assign n=n*sum assign result of n multiplied by sum to variable n
clear lineNumber clear 100 clear breakpoint at line 100 (see delete)
cont [signalNumber | SignalName] <c> cont continue executing program cont 3 continue executing as if signal 3 sent
delete [all | eventNumber] <d> delete all delete all breakpoints and trace events delete 3 delete event number 3 (also see clear)
file [sourceFile] file myprog.f look in myprog.f for source code
help help print summary of command usage
list [procedure | lineNumberExpression [,lineNumberExpression]] <l> list print ten lines starting with current line (unless at end of program) list 120 print line 120 list 120, 125 print lines 120 through 125 list @ print next line list readchar print first few lines of readchar procedure
next [number] <n> next execute next command; if next command calls subroutine, execute whole subroutine; do not step through subroutine next 4 execute next 4 commands; do not step through any subroutines called (contrast with step)
print variable [,variable...,variable] <p> print a,b,c print values of variables a, b, and c
return [Procedure] return resume execution until current procedure returns return main resume execution until return to procedure main occurs
run [arguments] [<inFile] [>outFile | >>outFile] [2>errFile | 2>>errFile] <r> run execute program run <data >>results execute program, get input from file data, append output to file results
screen screen create virtual terminal to display dbx command input and output
sh [shell command] sh ls run shell ls command from within dbx sh invoke shell which runs until you enter exit, then control returns to dbx
skip [n] skip 3 continue execution, skipping n breakpoints
status [>file] <j> status print list of all current events status>outfile write list of current events to outfile
step [number] <s> step execute next command, including subroutines step 5 execute next 5 commands, including subroutines (contrast with next) NOTE: It is faster to use next command rather than step command on a line that contains a subroutine that has not been compiled with -g
stop <st> stop at lineNumber [if Condition] stop at 23 stop execution of program at line 23 stop at a.c:60 stop at line 60 in file a.c stop in procedure [if Condition] stop in calc stop at first (executable) statement in (procedure or function) calc stop in menu if (i=10) stop at first executable statement in menu if i=10 stop variable [in Procedure | LineNumber] [if Condition] stop temp stop when value of variable temp changes stop count at 45 stop at line 45 when value of count changes stop flag in calc if i>200 stop in calc, when value of flag changes, if i>200 stop if condition stop if (total=44) stop if condition (total=44) is ever true stop if (x=y) and (y>z) stop when both conditions are true
whereis name whereis x print qualification of x in form a.b.x, where a is sourcefile name (without extension) and b is module name
whatis name whatis test print declaration of test
where [>fileName] <t> where lists all procedure calls and argument values which occurred before program stopped (up and down will move through list of calls) where > record writes list to file record
WE REALLY WANT TO KNOW...
Have you found this publication useful? Are there ways we
might improve or supplement it or other ITC publications?
Did you find this document in Web or in hard copy?
We really want your opinion. Send e-mail to: newsdesk@virginia.edu