.de P1.sp .5.if \\n(.$>0 .ta \\$1 \\$2 \\$3 \\$4 \\$5 \\$6.if \\n(.$=0 .ta 1i 1.7i 2.5i.ft 3.nf...de P2.sp .5.ft 1.fi...RP.....TM "77-8234-11 77-1273-10" "49170-220 39199" "40952-1 39199-11".ND May 5, 1977.TLA Tutorial Introduction to ADB.AU "MH2F-207" "3816"J. F. Maranzano.AU "MH2C-512" 7419S. R. Bourne.AI.MH.OKUNIXDebuggingC Programming.AB.PPDebugging tools generally provide a wealth of informationabout the inner workings of programs.These tools have been available on.UXto allow users toexamine ``core'' files that result from aborted programs.A new debugging program, ADB, provides enhanced capabilitiesto examine "core" and other program files in avariety of formats, run programs with embedded breakpoints and patch files..PPADB is an indispensable but complex tool for debugging crashed systems and/orprograms.This document provides an introduction to ADB with examples of its use.It explains the various formatting options, techniques for debugging C programs, examples of printingfile system information and patching..AE.CS 12 15 27 13 0 5.NHIntroduction.PPADB is a new debugging program that isavailable on UNIX.It provides capabilities to look at``core'' files resulting from aborted programs, print output in avariety of formats, patch files, and run programswith embedded breakpoints.This document provides examples ofthe more useful features of ADB.The reader is expected to befamiliar with the basic commands on.UXwith the Clanguage, and with References 1, 2 and 3..NHA Quick Survey.NH 2Invocation.PPADB is invoked as:.P1	adb objfile corefile.P2where.ulobjfileis an executable UNIX file and .ulcorefile is a core image file.Many times this will look like:.P1	adb a.out core.P2or more simply:.P1	adb.P2where the defaults are .ula.outand.ulcorerespectively.The filename minus (\-) means ignore this argument as in:.P1	adb \- core.P2.PPADB has requests for examining locations in either file.The\fB?\fPrequest examines the contents of .ulobjfile,the\fB/\fPrequest examines the .ulcorefile.The general form of these requests is:.P1	address ? format.P2or.P1	address / format.P2.NH 2Current Address.PPADB maintains a current address, called dot,similar in function to the current pointer in the UNIX editor.When an address is entered, the current address is set to that location,so that:.P1	0126?i.P2sets dot to octal 126 and prints the instructionat that address.The request:.P1	.,10/d.P2prints 10 decimal numbers starting at dot.Dot ends up referring to the address of the last item printed.When used with the \fB?\fP or \fB/\fP requests,the current address can be advanced by typing newline; it can be decrementedby typing \fB^\fP..PPAddresses are represented byexpressions.Expressions are made up from decimal, octal, and hexadecimal integers,and symbols from the program under test.These may be combined with the operators +, \-, *, % (integer division), & (bitwise and), | (bitwise inclusive or),  # (round upto the next multiple), and ~ (not).(All arithmetic within ADB is 32 bits.)When typing a symbolic address for a C program, the user can type .ulnameor.ul_name;ADB will recognize both forms..NH 2Formats.PPTo print data, a user specifies a collection of letters and charactersthat describe the format of the printout.Formats are "remembered" in the sense that typing a request without onewill cause the new printout to appear in the previous format.The following are the most commonly used format letters..P1\fB	b	\fPone byte in octal\fB	c	\fPone byte as a character\fB	o	\fPone word in octal\fB	d	\fPone word in decimal\fB	f	\fPtwo words in floating point\fB	i	\fPPDP 11 instruction\fB	s	\fPa null terminated character string\fB	a	\fPthe value of dot\fB	u	\fPone word as unsigned integer\fB	n	\fPprint a newline\fB	r	\fPprint a blank space\fB	^	\fPbackup dot.P2(Format letters are also available for "long" values,for example, `\fBD\fR' for long decimal, and `\fBF\fP' for double floating point.)For other formats see the ADB manual..NH 2General Request Meanings.PPThe general form of a request is:.P1	address,count command modifier.P2which sets `dot' to \fIaddress\fPand executes the command\fIcount\fR times..PPThe following table illustrates some general ADB command meanings:.P1	Command	Meaning\fB	    ?	\fPPrint contents from \fIa.out\fP file\fB	    /	\fPPrint contents from \fIcore\fP file\fB	    =	\fPPrint value of "dot"\fB	    :	\fPBreakpoint control\fB	    $	\fPMiscellaneous requests\fB	    ;	\fPRequest separator\fB	    !	\fPEscape to shell.P2.PPADB catches signals, so a user cannot use a quit signal to exit from ADB.The request $q or $Q (or cntl-D) must be usedto exit from ADB..NHDebugging C Programs.NH 2Debugging A Core Image .PPConsider the C program in Figure 1.The program is used to illustrate a common error made byC programmers.The object of the program is to change thelower case "t" to upper case in the string pointed to by.ulcharpand then write the character string to the file indicated byargument 1.The bug shown is that the character "T"is stored in the pointer .ulcharpinstead of the string pointed to by.ulcharp.Executing the program produces a core file because of an out of bounds memory reference..PPADB is invoked by:.P1	adb a.out core.P2The first debugging request:.P1	$c.P2is used to give a C backtrace through thesubroutines called.As shown in Figure 2only one function (\fImain\fR) was called and thearguments .ulargc and .ulargv have octal values 02 and0177762 respectively.Both of these values lookreasonable; 02 = two arguments, 0177762 = address on stackof parameter vector..brThe next request:.P1	$C.P2is used to give a C backtrace plus an interpretationof all the local variables in each function and theirvalues in octal.The value of the variable .ulcclooks incorrectsince.ulccwas declared as a character..PPThe next request:.P1	$r.P2prints out the registers including the programcounter and an interpretation of the instruction at thatlocation..PPThe request:.P1	$e.P2prints out the values of all external variables..PPA map exists for each filehandled byADB.The map for the.ula.outfile is referenced by \fB?\fP whereas the map for .ulcorefile is referenced by \fB/\fP.Furthermore, a good rule of thumb is to use \fB?\fP forinstructions and \fB/\fP for data when looking at programs.To print out information about the maps type:.P1	$m.P2This produces a report of the contents of the maps.More about these maps later..PPIn our example, it is useful to see thecontents of the string pointed to by.ulcharp.This is done by:.P1	*charp/s.P2which says use .ulcharpas a pointer in the.ulcorefileand print the information as a character string.This printout clearly shows that the character bufferwas incorrectly overwritten and helps identify the error.Printing the locations around .ulcharpshows that the buffer is unchangedbut that the pointer is destroyed.Using ADB similarly, we could print information about thearguments to a function.The request:.P1	main.argc/d.P2prints the decimal .ulcoreimage value of the argument .ulargcin the function .ulmain..brThe request:.P1	*main.argv,3/o.P2prints the octal values of the three consecutivecells pointed to by .ulargvin the function .ulmain.Note that these values are the addresses of the argumentsto main.Therefore: .P1	0177770/s.P2prints the ASCII value of the first argument.Another way to print this value would have been.P1	*"/s.P2The " means ditto which remembers the last addresstyped, in this case \fImain.argc\fP ; the \fB*\fP instructs ADB to use the address field of the.ulcore file as a pointer..PPThe request:.P1	.=o.P2prints the current address (not its contents) in octal which has been set to the address of the first argument.The current address, dot, is used by ADB to"remember" its current location.It allows the user to reference locations relative to the currentaddress, for example:.P1	.\-10/d.P2.NH 2Multiple Functions.PPConsider the C program illustrated inFigure 3.This program calls functions .ulf, g,and.ulh until the stack is exhausted and a core image is produced..PPAgain you can enter the debugger via:.P1	adb.P2which assumes the names .ula.outand .ulcorefor the executablefile and core image file respectively.The request:.P1	$c.P2will fill a page of backtrace references to .ulf, g,and.ulh.Figure 4 shows an abbreviated list (typing .ulDELwill terminate the output and bring you back to ADB request level)..PPThe request:.P1	,5$C.P2prints the five most recent activations..PPNotice that each function (\fIf,g,h\fP) has a counterof the number of times it was called..PPThe request:.P1	fcnt/d.P2prints the decimal value of the counter for the function.ulf.Similarly .ulgcntand.ulhcntcould be printed.To print the value of an automatic variable,for example the decimal value of.ul xin the last call of the function.ulh,type:.P1	h.x/d.P2It is currently not possible in the exported version to print stack frames other than the most recent activation of a function.Therefore, a user can print everything with \fB$C\fR or the occurrence of a variable in the most recent call of a function.It is possible with the \fB$C\fR request, however, to print the stack framestarting at some address as \fBaddress$C.\fR.NH 2Setting Breakpoints.PPConsider the C program in Figure 5.This program, which changes tabs into blanks, is adapted from.ulSoftware Toolsby Kernighan and Plauger, pp. 18-27..PPWe will run this program under the control of ADB (see Figure 6a) by:.P1	adb a.out \-.P2Breakpoints are set in the program as:.ul.P1	address:b  [request].P2The requests:.P1	settab+4:b	fopen+4:b	getc+4:b	tabpos+4:b.P2set breakpoints at the start of these functions.C does not generate statement labels.Therefore it is currently not possible to plant breakpoints at locationsother than function entry points without a knowledge of the codegenerated by the C compiler.The above addresses are entered as.ft Bsymbol+4.ft Rso that they will appear in anyC backtrace since the first instruction of each function is a callto the C save routine (\fIcsv\fR).Note that some of the functions are from the C library..PPTo print the location of breakpoints one types:.P1	$b.P2The display indicates a.ulcountfield.A breakpoint is bypassed.ulcount \-1times before causing a stop.The.ulcommandfield indicates the ADB requests to be executed each time the breakpoint is encountered.In our example no.ulcommandfields are present..PPBy displaying the original instructions at the function.ulsettabwe see that the breakpoint is set after the jsr to the C save routine.We can display the instructions using the ADB request:.P1	settab,5?ia.P2This request displays five instructions starting at.ulsettabwith the addresses of each location displayed.Another variation is:.P1	settab,5?i.P2which displays the instructions with only the starting address..PPNotice that we accessed the addresses from the .ula.out file with the \fB?\fP command.In general when asking for a printout of multiple items,ADB will advance the current address the number ofbytes necessary to satisfy the request; in the aboveexample five instructions were displayed and the current address wasadvanced 18 (decimal) bytes..PPTo run the program one simply types:.P1	:r.P2To delete a breakpoint, for instance the entry to the function.ulsettab,one types:.P1	settab+4:d.P2To continue execution of the program from the breakpoint type:.P1	:c.PPOnce the program has stopped (in this case at the breakpoint for.ulfopen),ADB requests can be used to display the contents of memory.For example:.P1	$C.P2to display a stack trace, or:.P1	tabs,3/8o.P2to print three lines of 8 locations each from the array called.ultabs.By this time (at location.ulfopen)in the C program,.ulsettabhas been called and should have set a one in every eighth location of .ultabs..NH 2Advanced Breakpoint Usage.PPWe continue execution of the program with:.P1	:c.P2See Figure 6b..ulGetcis called three times and  the contents of the variable .ulcin the function.ulmainare displayedeach time.The single character on the left hand edge is the output from the C program.On the third occurrence of .ulgetcthe program stops.We can look at the full buffer of characters by typing:.P1	ibuf+6/20c.P2When we continue the program with:.P1	:c.P2we hit our first breakpoint at.ultabpossince there is a tab following the"This" word of the data..PPSeveral breakpoints of.ultabposwill occur until the program has changed the tab into equivalent blanks.Since we feel that.ultabposis working,we can remove the breakpoint at that location by:.P1	tabpos+4:d.P2If the program is continued with:.P1	:c.P2it resumes normal execution after ADB prints