The `dbx` Debugger

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

A second use is to trace execution of a program.

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 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, 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.
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 TO ANALYZE A CORE FILE

A prerequisite: always supply the -g option when compiling your program! If you don't, dbx 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
```
to start dbx. 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 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 some 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.
For such versionis of dbx there is 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`

Here is an example of the use command:
```
		use . Module1 Module2
```
This tells dbx to check the current directory and the two specified subdirectories for source code files.
If you use dbx a 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, 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 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. 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 machine 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.

The dbx Debugger

CORE FILES

USING DBX TO ANALYZE A CORE FILE

TRACING PROGRAM EXECUTION WITH DBX

MACHINE-LANGUAGE TRACING

The `dbx` Debugger