The `dbx and gdb` Debuggers

One use for dbx or gdb is to analyze a core file from a program that has crashed.

A second use is to trace execution of a program.

The compiler you use determines which debugger you should use. If you use the GNU C compiler (gcc) then you should use the gdb debugger. Generally the dbx debugger is used for all other compilers and most notably the Sun C compiler. (On the AIX machines, only dbx is available, however on Thetis and Valdes gdb is available.)

CORE FILES

A core file is generated when a program executes the call
```
                abort(); 
```
or if an error interrupt occurs. Most computers will generate an interrupt when the program attempts to access a memory location outside the region it has been allocated, or for dividing by zero, or for floating-point overflow ... The exact list of errors that generate interrupts depends on the computer and on the system software. (The IBM AIX workstations do not, for example, catch divide by zero errors.)
The core file contains a complete snapshot of the program at the time of the error:
- program counter, all registers, and all (writeable) memory locations belonging to the program.

The Unix shell reports a program crash (and the creation of a core file) in a manner like this:

            % myprog
            Segmentation fault (core dumped)
            % ls -l
            -rw-r--r--  1 nigelh  csciperm  23979 Jan 31 09:36 core
            -rwxr-xr-x  1 nigelh  csciperm   4620 Jan 31 09:25 myprog
            -rw-r--r--  1 nigelh  csciperm    163 Jan 31 09:16 myprog.c

Core files can be gigantic (often several megabytes in size). It is therefore common to limit or disable generation of core files by using a special C-shell command. The command
```
                limit coredumpsize 50 
```
will prevent a core file from growing larger than 50KB. It is quite possible that your `.login' file or `.cshrc' file (which contain commands to be executed when the shell is started up) contains the command:
```
                limit coredumpsize 0 
```
To be able to debug a crashed program with dbx or gdb, you need the whole core file. If you execute the command
```
                unlimit coredumpsize 
```
and then re-run the program that crashes, you will obtain the complete core file. A better suggestion is to edit your .cshrc file and remove the line which limits the coredumpsize.
If you have a program that gets caught in an infinite loop, you can force that program to abort with a core dump by hitting the control-backslash key combination. (In Unix parlance, that key combination is written as ^\ .)
(The ^\ combination generates a quit signal; this is similar to an error interrupt occurring in the program. It is possible to change the key combination which generates the quit signal; we assume that you haven't made such a change.)

USING DBX OR GDB TO ANALYZE A CORE FILE

A prerequisite: always supply the -g option when compiling your program! If you don't, dbx or gdb will be missing information needed to help interpret the core file. E.g.
```
                % cc -g -o buggy buggy.c 
```
If you have a multifile program, composed from one.c two.c ..., then all cc invocations need the -g flag. E.g.
```
                % cc -c -g one.c
                % cc -c -g two.c
                ...
                % cc -g -o bigBuggy one.o two.o ...  
```
Suppose that your program is called buggy and that, when you ran it, it produced a core file. You should then type the command
```
                % dbx buggy core 
```
or
```
                % gdb buggy core 
```
to start dbx or gdb. It will read the two files, report the line where the program stopped, and then wait for you to enter subcommands.
The output that dbx or gdb produces when it starts up should look something like this:
```
                Type 'help' for help.
                reading symbolic information ...
                [using memory image in core]
   
                Segmentation fault in calcSubr at line 7
                   7    A[n] = 0; 
```
Note that the output tells you the name of the function that was being executed when the program crashed, the source code line number, and a listing of exactly that line.
(An experienced C programmer would immediately guess from that listing of the line that variable n is probably out of range. Note that n being just out of range is unlikely to cause the program to crash. The location A[-1], for example, is probably still within the region of memory belonging to the program.)
NOTE: on the AIX system, dbx will only display source code lines if the source code files are in the same directory as the program and the core file that are being analyzed. This is inconvenient for debugging programs that are assembled from several modules (with the source code held in several directories).
If dbx does not find the source code file, it produces a message like:
```
                could not read "buggy.c" 
```
instead of displaying the line of source code.
The AIX version of dbx therefore has an extra option that tells it the name of a directory to check when looking for source code files. This option may be used several times if there are several directories to check. For example, if the program buggy has been created from source code in subdirectories named Module1 and Module2, we should invoke dbx with the command:
```
                dbx -I Module1 -I Module2 buggy core 
```
(That option letter is an upper-case i.) Alternatively, you give those directory names to dbx with the use command (see below).

If the location of the error is not enough to understand the error, we can ask dbx to provide additional information. The following dbx subcommands should be useful:

`where`	shows active functions
`dump`	dumps all variables
`print` expr	evaluates and prints an expression
`up`	go up to parent function
`down`	go down to child function
`list` functionName	display 10 lines of source code of the named function
`list`	display another 10 lines of code
`func` functionName	prepare to examine the named function
`file` fileName	prepare to examine the named source code file
`whatis` variableName	shows the datatype of the variable
`which` variableName	to ask which variable of this name is visible here
`whereis` variableName	asks where all the variables of this name are located
`use` directory list	if you forgot to provide the `-I` option when you started up `dbx`, you can instead list the directory names in the use command.
`help`	general help facility
`help` command	display help info about a command
`quit`	exit from `dbx` or `gdb`

Here is an example of the use command:
```
                use . Module1 Module2 
```
This tells dbx or gdb to check the current directory and the two specified subdirectories for source code files.
If you use dbx a or gdb lot, you would probably like to create a file with the name `.dbxinit' in your home directory. This file can contain lines like:
```
                alias p print
                alias l list
                ...  
```
The next time you use dbx or gdb, you can then use the command p as a synonym for print, and so on.
Note that you can print the values of arbitrary C expressions. For example,
```
                print A[n+1] 
```
prints the value of the expression A[n+1] using the current value of the variable n and the current contents of the array A. You can print the values of several expressions simultaneously. E.g.
```
                print n, A[n+1] 
```
If your C program uses structs, you can ask dbx or gdb to print a struct value and you will be shown the contents of all fields in that struct. When debugging programs that use pointers, it is common to make print requests like:
```
                print p, p->next, p->next->next 
```
to show the first three elements in a linked list (whose head pointer is p, and where the link field in each element is named next).
Printing the contents of an array is inconvenient with dbx but fairly easy with gdb.

For gdb, use a command like
```
   print A@50 
```
where A is the name of the array and A has 50 elements. And that's all there is to it.

For dbx, it is necessary to use a special notation that works for displaying the contents of any region of memory.
To use this notation, you must specify the starting and ending addresses of the desired region of memory, and the format to use when printing the memory contents.
For example, suppose that we wish to print the contents of the array named A. First, you might use the dbx command:
```
 whatis A 
```
The answer might come back looking like:
```
 int A[50]; 
```
(I.e. dbx has located the declaration of A in the source code and displays it for you.) Using your general knowledge of the computer and of C, you should know that int values require 4 bytes each. If you do not know this, you could ask dbx by using the command
```
 print sizeof(int) 
```
and dbx will print 4 as the value of that C expression.
Now you can deduce that the array A is 200 bytes in size and you might ask dbx to print out the contents of memory for A as follows:
```
 &A,&A+200/D 
```
The command is written as: address,address/format. The start address is simply &A (the C notation for the address of an object). The end address is &A+200 (i.e. dbx accepts an expression as the address). The format is D. The code letter D means 4-byte decimal number.

The most useful format code letters are as follows:

c

one-byte ASCII character

d

2-byte decimal integer

D

4-byte decimal integer

f

4-byte floating-point number

g

8-byte floating-point number

h

one-byte hexadecimal number

s

a character string terminated by a null byte

x

2-byte hexadecimal number

X

4-byte hexadecimal number
An alternative way of printing our 50-element array is to use the command form:
```
                &A/50D 
```
The number 50, here, is a repetition factor for the format code that follows.
If you are curious about the Assembly instructions that your C program was translated into, you can ask dbx to display regions of memory as disassembled machine instructions. For example, you can see the first 20 instructions of the function main by executing the dbx command:
```
                &main/20i 
```
The format code i means machine instruction.

TRACING PROGRAM EXECUTION WITH DBX

Prerequisites: make sure the program was compiled with the -g flag, as above. Also remove any old core file in your directory.
If your program is named buggy, then enter the command:
```
   % dbx buggy 
```
If your program was created from source code in other directories, you could supply the -I flag for each such directory. E.g.
```
   % dbx -I Module1 -I Module2 buggy 
```
Alternatively, you can enter the use subcommand of dbx (as explained above).

You should now enter dbx commands that establish breakpoints, and/or ask for variables and functions to be watched. These commands are:

`trace` funcName	ask for all calls to and returns from the function to generate trace output
`trace` variableName	ask for all assignments to the specified variable to generate trace output
`stop in` functionName	cause execution to halt if control enters the named function
`stop` variableName	cause execution to halt at any assignment to the specified variable
`stop at` lineNumber	stop if control reaches the specified line number

Note: if you want to stop at some line number in a particular file, you should first use the command

file fileName

(with the appropriate fileName) before using the stop at command. For example:

                file calcSubr.c
                stop at 27

When you are ready to let the program run, use the command
```
                run 
```
If the program requires command line arguments, you can supply those, as in
```
                run -d myfile 
```
If it requires file redirections, then these can be supplied too:
```
                run < inputFile 
```
(I.e., invoking the program is the same as running the program from the shell command line, except that the program name is replaced by the word run.)
The program will run up to a breakpoint (if it doesn't exit or crash first). At a breakpoint, you can use the dbx commands for finding out where you are, what values are in variables, etc. You can also add new breakpoints, etc.
To resume execution after the breakpoint, use the command
```
                cont 
```
You can also restart the program at the beginning with the command
```
                rerun 
```
(Again, arguments may be supplied. If you fail to supply arguments, the same ones as were used on the earlier run command will be re-used.)
If the program is stopped at a breakpoint, the command
```
                step 
```
causes one line of the program to be executed, and then the program halts again. If you would like to step through 10 statements and stop again, the command would be
```
                step 10 
```
A similar command to step is
```
                next 
```
The difference is that next causes any functions called inside the current statement to be fully executed. (The step subcommand would cause control to stop inside the function.)
Again, the command form
```
                next 10 
```
is available.
The stop commands may be modified with conditional expressions. For example:
```
                stop at 37 if i<0 
```
will cause control to stop just before executing line 37 in the current source code file if variable i happens to be less than zero at this point.

To change the contents of a variable before control resumes, use a command like

                assign i = 27

which stores 27 into variable i. Values of any simple C datatype can be assigned. Here are examples:

                assign ch = '*'
   
                assign f = 3.5e-5
   
                assign s = "some string value"

MACHINE-LANGUAGE TRACING

For those who are interested, dbx can display information at the machine instruction level. Here are some examples of the special dbx subcommands.

registers

displays the contents of the computer's registers.
stopi at 0x1000aefe

sets a breakpoint at the machine instruction with the specified address. (These machine instructions and their addresses have presumably been displayed using the
```
                &func/20i 
```
form of instruction.)
stepi

causes one instruction to be executed and then the program halts again.
nexti

is like stepi except that if the current instruction is a function call, the program halts only on return from that function.

Using GDB for Debugging

gdb has the same functionality as dbx, however it is more popular since it works for a better compiler (gcc) and its commands are less verbose. For any command you can just enter the start of the command name to remove any ambiguity and the debugger will figure out what you mean. Example p will mean print. Some basic equivalent commands in gdb are:

`break` file:line	add a breakpoint at a given file and line number.
`break` func	add a breakpoint at the start of function func.
`next`	Execute the next statement. If it is a function call then stop after executing the function.
`step`	Execute the next statement. If it is a function call then enter the function and stop.
`backtrace`	List the program stack. A synonym for this command is `bt`.
`frame` num	Go to the stack frame number num.
`print` var	Print the value of variable var.
`list`	display current lines of code.