home *** CD-ROM | disk | FTP | other *** search
/ minnie.tuhs.org / unixen.tar / unixen / PDP-11 / Trees / V7 / usr / doc / adb / tut next >
Encoding:
Text File  |  1979-01-10  |  29.4 KB  |  1,293 lines

  1. .de P1
  2. .sp .5
  3. .if \\n(.$>0 .ta \\$1 \\$2 \\$3 \\$4 \\$5 \\$6
  4. .if \\n(.$=0 .ta 1i 1.7i 2.5i
  5. .ft 3
  6. .nf
  7. ..
  8. .de P2
  9. .sp .5
  10. .ft 1
  11. .fi
  12. ..
  13. .RP
  14. .....TM "77-8234-11 77-1273-10" "49170-220 39199" "40952-1 39199-11"
  15. .ND May 5, 1977
  16. .TL
  17. A Tutorial Introduction to ADB
  18. .AU "MH2F-207" "3816"
  19. J. F. Maranzano
  20. .AU "MH2C-512" 7419
  21. S. R. Bourne
  22. .AI
  23. .MH
  24. .OK
  25. UNIX
  26. Debugging
  27. C Programming
  28. .AB
  29. .PP
  30. Debugging tools generally provide a wealth of information
  31. about the inner workings of programs.
  32. These tools have been available on
  33. .UX
  34. to allow users to
  35. examine ``core'' files 
  36. that result from aborted programs.
  37. A new debugging program, ADB, provides enhanced capabilities
  38. to examine "core" and other program files in a
  39. variety of formats, run programs with embedded breakpoints and patch files.
  40. .PP
  41. ADB is an indispensable but complex tool for debugging crashed systems and/or
  42. programs.
  43. This document provides an introduction to ADB with examples of its use.
  44. It explains the various formatting options, 
  45. techniques for debugging C programs, examples of printing
  46. file system information and patching.
  47. .AE
  48. .CS 12 15 27 13 0 5
  49. .NH
  50. Introduction
  51. .PP
  52. ADB is a new debugging program that is
  53. available on UNIX.
  54. It provides capabilities to look at
  55. ``core'' files resulting from aborted programs, print output in a
  56. variety of formats, patch files, and run programs
  57. with embedded breakpoints.
  58. This document provides examples of
  59. the more useful features of ADB.
  60. The reader is expected to be
  61. familiar with the basic commands on
  62. .UX
  63. with the C
  64. language, and with References 1, 2 and 3.
  65. .NH
  66. A Quick Survey
  67. .NH 2
  68. Invocation
  69. .PP
  70. ADB is invoked as:
  71. .P1
  72.     adb objfile corefile
  73. .P2
  74. where
  75. .ul
  76. objfile
  77. is an executable UNIX file and 
  78. .ul
  79. corefile 
  80. is a core image file.
  81. Many times this will look like:
  82. .P1
  83.     adb a.out core
  84. .P2
  85. or more simply:
  86. .P1
  87.     adb
  88. .P2
  89. where the defaults are 
  90. .ul
  91. a.out
  92. and
  93. .ul
  94. core
  95. respectively.
  96. The filename minus (\-) means ignore this argument as in:
  97. .P1
  98.     adb \- core
  99. .P2
  100. .PP
  101. ADB has requests for examining locations in either file.
  102. The
  103. \fB?\fP
  104. request examines the contents of 
  105. .ul
  106. objfile,
  107. the
  108. \fB/\fP
  109. request examines the 
  110. .ul
  111. corefile.
  112. The general form of these requests is:
  113. .P1
  114.     address ? format
  115. .P2
  116. or
  117. .P1
  118.     address / format
  119. .P2
  120. .NH 2
  121. Current Address
  122. .PP
  123. ADB maintains a current address, called dot,
  124. similar in function to the current pointer in the UNIX editor.
  125. When an address is entered, the current address is set to that location,
  126. so that:
  127. .P1
  128.     0126?i
  129. .P2
  130. sets dot to octal 126 and prints the instruction
  131. at that address.
  132. The request:
  133. .P1
  134.     .,10/d
  135. .P2
  136. prints 10 decimal numbers starting at dot.
  137. Dot ends up referring to the address of the last item printed.
  138. When used with the \fB?\fP or \fB/\fP requests,
  139. the current address can be advanced by typing newline; it can be decremented
  140. by typing \fB^\fP.
  141. .PP
  142. Addresses are represented by
  143. expressions.
  144. Expressions are made up from decimal, octal, and hexadecimal integers,
  145. and symbols from the program under test.
  146. These may be combined with the operators +, \-, *, % (integer division), 
  147. & (bitwise and), | (bitwise inclusive or),  # (round up
  148. to the next multiple), and ~ (not).
  149. (All arithmetic within ADB is 32 bits.)
  150. When typing a symbolic address for a C program, 
  151. the user can type 
  152. .ul
  153. name
  154. or
  155. .ul
  156. _name;
  157. ADB will recognize both forms.
  158. .NH 2
  159. Formats
  160. .PP
  161. To print data, a user specifies a collection of letters and characters
  162. that describe the format of the printout.
  163. Formats are "remembered" in the sense that typing a request without one
  164. will cause the new printout to appear in the previous format.
  165. The following are the most commonly used format letters.
  166. .P1
  167. \fB    b    \fPone byte in octal
  168. \fB    c    \fPone byte as a character
  169. \fB    o    \fPone word in octal
  170. \fB    d    \fPone word in decimal
  171. \fB    f    \fPtwo words in floating point
  172. \fB    i    \fPPDP 11 instruction
  173. \fB    s    \fPa null terminated character string
  174. \fB    a    \fPthe value of dot
  175. \fB    u    \fPone word as unsigned integer
  176. \fB    n    \fPprint a newline
  177. \fB    r    \fPprint a blank space
  178. \fB    ^    \fPbackup dot
  179. .P2
  180. (Format letters are also available for "long" values,
  181. for example, `\fBD\fR' for long decimal, and `\fBF\fP' for double floating point.)
  182. For other formats see the ADB manual.
  183. .NH 2
  184. General Request Meanings
  185. .PP
  186. The general form of a request is:
  187. .P1
  188.     address,count command modifier
  189. .P2
  190. which sets `dot' to \fIaddress\fP
  191. and executes the command
  192. \fIcount\fR times.
  193. .PP
  194. The following table illustrates some general ADB command meanings:
  195. .P1
  196.     Command    Meaning
  197. \fB        ?    \fPPrint contents from \fIa.out\fP file
  198. \fB        /    \fPPrint contents from \fIcore\fP file
  199. \fB        =    \fPPrint value of "dot"
  200. \fB        :    \fPBreakpoint control
  201. \fB        $    \fPMiscellaneous requests
  202. \fB        ;    \fPRequest separator
  203. \fB        !    \fPEscape to shell
  204. .P2
  205. .PP
  206. ADB catches signals, so a user cannot use a quit signal to exit from ADB.
  207. The request $q or $Q (or cntl-D) must be used
  208. to exit from ADB.
  209. .NH
  210. Debugging C Programs
  211. .NH 2
  212. Debugging A Core Image 
  213. .PP
  214. Consider the C program in Figure 1.
  215. The program is used to illustrate a common error made by
  216. C programmers.
  217. The object of the program is to change the
  218. lower case "t" to upper case in the string pointed to by
  219. .ul
  220. charp
  221. and then write the character string to the file indicated by
  222. argument 1.
  223. The bug shown is that the character "T"
  224. is stored in the pointer 
  225. .ul
  226. charp
  227. instead of the string pointed to by
  228. .ul
  229. charp.
  230. Executing the program produces a core file because of an out of bounds memory reference.
  231. .PP
  232. ADB is invoked by:
  233. .P1
  234.     adb a.out core
  235. .P2
  236. The first debugging request:
  237. .P1
  238.     $c
  239. .P2
  240. is used to give a C backtrace through the
  241. subroutines called.
  242. As shown in Figure 2
  243. only one function (\fImain\fR) was called and the
  244. arguments 
  245. .ul
  246. argc 
  247. and 
  248. .ul
  249. argv 
  250. have octal values 02 and
  251. 0177762 respectively.
  252. Both of these values look
  253. reasonable; 02 = two arguments, 0177762 = address on stack
  254. of parameter vector.
  255. .br
  256. The next request:
  257. .P1
  258.     $C
  259. .P2
  260. is used to give a C backtrace plus an interpretation
  261. of all the local variables in each function and their
  262. values in octal.
  263. The value of the variable 
  264. .ul
  265. cc
  266. looks incorrect
  267. since
  268. .ul
  269. cc
  270. was declared as a character.
  271. .PP
  272. The next request:
  273. .P1
  274.     $r
  275. .P2
  276. prints out the registers including the program
  277. counter and an interpretation of the instruction at that
  278. location.
  279. .PP
  280. The request:
  281. .P1
  282.     $e
  283. .P2
  284. prints out the values of all external variables.
  285. .PP
  286. A map exists for each file
  287. handled by
  288. ADB.
  289. The map for the
  290. .ul
  291. a.out
  292. file is referenced by \fB?\fP whereas the map for 
  293. .ul
  294. core
  295. file is referenced by \fB/\fP.
  296. Furthermore, a good rule of thumb is to use \fB?\fP for
  297. instructions and \fB/\fP for data when looking at programs.
  298. To print out information about the maps type:
  299. .P1
  300.     $m
  301. .P2
  302. This produces a report of the contents of the maps.
  303. More about these maps later.
  304. .PP
  305. In our example, it is useful to see the
  306. contents of the string pointed to by
  307. .ul
  308. charp.
  309. This is done by:
  310. .P1
  311.     *charp/s
  312. .P2
  313. which says use 
  314. .ul
  315. charp
  316. as a pointer in the
  317. .ul
  318. core
  319. file
  320. and print the information as a character string.
  321. This printout clearly shows that the character buffer
  322. was incorrectly overwritten and helps identify the error.
  323. Printing the locations around 
  324. .ul
  325. charp
  326. shows that the buffer is unchanged
  327. but that the pointer is destroyed.
  328. Using ADB similarly, we could print information about the
  329. arguments to a function.
  330. The request:
  331. .P1
  332.     main.argc/d
  333. .P2
  334. prints the decimal 
  335. .ul
  336. core
  337. image value of the argument 
  338. .ul
  339. argc
  340. in the function 
  341. .ul
  342. main.
  343. .br
  344. The request:
  345. .P1
  346.     *main.argv,3/o
  347. .P2
  348. prints the octal values of the three consecutive
  349. cells pointed to by 
  350. .ul
  351. argv
  352. in the function 
  353. .ul
  354. main.
  355. Note that these values are the addresses of the arguments
  356. to main.
  357. Therefore: 
  358. .P1
  359.     0177770/s
  360. .P2
  361. prints the ASCII value of the first argument.
  362. Another way to print this value would have been
  363. .P1
  364.     *"/s
  365. .P2
  366. The " means ditto which remembers the last address
  367. typed, in this case \fImain.argc\fP ; the \fB*\fP instructs ADB to use the address field of the
  368. .ul
  369. core 
  370. file as a pointer.
  371. .PP
  372. The request:
  373. .P1
  374.     .=o
  375. .P2
  376. prints the current address (not its contents) in octal which has been set to the address of the first argument.
  377. The current address, dot, is used by ADB to
  378. "remember" its current location.
  379. It allows the user 
  380. to reference locations relative to the current
  381. address, for example:
  382. .P1
  383.     .\-10/d
  384. .P2
  385. .NH 2
  386. Multiple Functions
  387. .PP
  388. Consider the C program illustrated in
  389. Figure 3.
  390. This program calls functions 
  391. .ul
  392. f, g,
  393. and
  394. .ul
  395. until the stack is exhausted and a core image is produced.
  396. .PP
  397. Again you can enter the debugger via:
  398. .P1
  399.     adb
  400. .P2
  401. which assumes the names 
  402. .ul
  403. a.out
  404. and 
  405. .ul
  406. core
  407. for the executable
  408. file and core image file respectively.
  409. The request:
  410. .P1
  411.     $c
  412. .P2
  413. will fill a page of backtrace references to 
  414. .ul
  415. f, g,
  416. and
  417. .ul
  418. h.
  419. Figure 4 shows an abbreviated list (typing 
  420. .ul
  421. DEL
  422. will terminate the output and bring you back to ADB request level).
  423. .PP
  424. The request:
  425. .P1
  426.     ,5$C
  427. .P2
  428. prints the five most recent activations.
  429. .PP
  430. Notice that each function 
  431. (\fIf,g,h\fP) has a counter
  432. of the number of times it was called.
  433. .PP
  434. The request:
  435. .P1
  436.     fcnt/d
  437. .P2
  438. prints the decimal value of the counter for the function
  439. .ul
  440. f.
  441. Similarly 
  442. .ul
  443. gcnt
  444. and
  445. .ul
  446. hcnt
  447. could be printed.
  448. To print the value of an automatic variable,
  449. for example the decimal value of
  450. .ul 
  451. x
  452. in the last call of the function
  453. .ul
  454. h,
  455. type:
  456. .P1
  457.     h.x/d
  458. .P2
  459. It is currently not possible in the exported version to print stack frames other than the most recent activation of a function.
  460. Therefore, a user can print everything with 
  461. \fB$C\fR or the occurrence of a variable in the most recent call of a function.
  462. It is possible with the \fB$C\fR request, however, to print the stack frame
  463. starting at some address as \fBaddress$C.\fR
  464. .NH 2
  465. Setting Breakpoints
  466. .PP
  467. Consider the C program in Figure 5.
  468. This program, which changes tabs into blanks, is adapted from
  469. .ul
  470. Software Tools
  471. by Kernighan and Plauger, pp. 18-27.
  472. .PP
  473. We will run this program under the control of ADB (see Figure 6a) by:
  474. .P1
  475.     adb a.out \-
  476. .P2
  477. Breakpoints are set in the program as:
  478. .ul
  479. .P1
  480.     address:b  [request]
  481. .P2
  482. The requests:
  483. .P1
  484.     settab+4:b
  485.     fopen+4:b
  486.     getc+4:b
  487.     tabpos+4:b
  488. .P2
  489. set breakpoints at the start of these functions.
  490. C does not generate statement labels.
  491. Therefore it is currently not possible to plant breakpoints at locations
  492. other than function entry points without a knowledge of the code
  493. generated by the C compiler.
  494. The above addresses are entered as
  495. .ft B
  496. symbol+4
  497. .ft R
  498. so that they will appear in any
  499. C backtrace since the first instruction of each function is a call
  500. to the C save routine 
  501. (\fIcsv\fR).
  502. Note that some of the functions are from the C library.
  503. .PP
  504. To print the location of breakpoints one types:
  505. .P1
  506.     $b
  507. .P2
  508. The display indicates a
  509. .ul
  510. count
  511. field.
  512. A breakpoint is bypassed
  513. .ul
  514. count \-1
  515. times before causing a stop.
  516. The
  517. .ul
  518. command
  519. field indicates the ADB requests to be executed each time the breakpoint is encountered.
  520. In our example no
  521. .ul
  522. command
  523. fields are present.
  524. .PP
  525. By displaying the original instructions at the function
  526. .ul
  527. settab
  528. we see that 
  529. the breakpoint is set after the jsr to the C save routine.
  530. We can display the instructions using the ADB request:
  531. .P1
  532.     settab,5?ia
  533. .P2
  534. This request displays five instructions starting at
  535. .ul
  536. settab
  537. with the addresses of each location displayed.
  538. Another variation is:
  539. .P1
  540.     settab,5?i
  541. .P2
  542. which displays the instructions with only the starting address.
  543. .PP
  544. Notice that we accessed the addresses from the 
  545. .ul
  546. a.out 
  547. file with the \fB?\fP command.
  548. In general when asking for a printout of multiple items,
  549. ADB will advance the current address the number of
  550. bytes necessary to satisfy the request; in the above
  551. example five instructions were displayed and the current address was
  552. advanced 18 (decimal) bytes.
  553. .PP
  554. To run the program one simply types:
  555. .P1
  556.     :r
  557. .P2
  558. To delete a breakpoint, for instance the entry to the function
  559. .ul
  560. settab,
  561. one types:
  562. .P1
  563.     settab+4:d
  564. .P2
  565. To continue execution of the program from the breakpoint type:
  566. .P1
  567.     :c
  568. .PP
  569. Once the program has stopped (in this case at the breakpoint for
  570. .ul
  571. fopen),
  572. ADB requests can be used to display the contents of memory.
  573. For example:
  574. .P1
  575.     $C
  576. .P2
  577. to display a stack trace, or:
  578. .P1
  579.     tabs,3/8o
  580. .P2
  581. to print three lines of 8 locations each from the array called
  582. .ul
  583. tabs.
  584. By this time (at location
  585. .ul
  586. fopen)
  587. in the C program,
  588. .ul
  589. settab
  590. has been called and should have set a one in every eighth location of 
  591. .ul
  592. tabs.
  593. .NH 2
  594. Advanced Breakpoint Usage
  595. .PP
  596. We continue execution of the program with:
  597. .P1
  598.     :c
  599. .P2
  600. See Figure 6b.
  601. .ul
  602. Getc
  603. is called three times and  the contents of the variable 
  604. .ul
  605. c
  606. in the function
  607. .ul
  608. main
  609. are displayed
  610. each time.
  611. The single character on the left hand edge is the output from the C program.
  612. On the third occurrence of 
  613. .ul
  614. getc
  615. the program stops.
  616. We can look at the full buffer of characters by typing:
  617. .P1
  618.     ibuf+6/20c
  619. .P2
  620. When we continue the program with:
  621. .P1
  622.     :c
  623. .P2
  624. we hit our first breakpoint at
  625. .ul
  626. tabpos
  627. since there is a tab following the
  628. "This" word of the data.
  629. .PP
  630. Several breakpoints of
  631. .ul
  632. tabpos
  633. will occur until the program has changed the tab into equivalent blanks.
  634. Since we feel that
  635. .ul
  636. tabpos
  637. is working,
  638. we can remove the breakpoint at that location by:
  639. .P1
  640.     tabpos+4:d
  641. .P2
  642. If the program is continued with:
  643. .P1
  644.     :c
  645. .P2
  646. it resumes normal execution after ADB prints
  647. the message
  648. .P1
  649.     a.out:running
  650. .P2
  651. .PP
  652. The UNIX quit and interrupt signals
  653. act on ADB itself rather than on the program being debugged.
  654. If such a signal occurs then the program being debugged is stopped and control is returned to ADB.
  655. The signal is saved by ADB and is passed on to the test program if:
  656. .P1
  657.     :c
  658. .P2
  659. is typed.
  660. This can be useful when testing interrupt
  661. handling routines.
  662. The signal is not passed on to the test program if:
  663. .P1
  664.     :c  0
  665. .P2
  666. is typed.
  667. .PP
  668. Now let us reset the breakpoint at
  669. .ul
  670. settab
  671. and display the instructions located there when we reach the breakpoint.
  672. This is accomplished by:
  673. .P1
  674.     settab+4:b  settab,5?ia  \fR*
  675. .P2
  676. .FS
  677. * Owing to a bug in early versions of ADB (including the
  678. version distributed in Generic 3 UNIX) these statements
  679. must be written as:
  680. .br
  681. .in 1i
  682. \fBsettab+4:b    settab,5?ia;0\fR
  683. .ft B
  684. .br
  685. getc+4,3:b    main.c?C;0
  686. .br
  687. settab+4:b    settab,5?ia; ptab/o;0
  688. .br
  689. .ft R
  690. .in -1i
  691. Note that \fB;0\fR will set dot to zero and stop at the breakpoint.
  692. .FE
  693. It is also possible to execute the ADB requests for each occurrence of the breakpoint but
  694. only stop after the third occurrence by typing:
  695. .P1
  696.     getc+4,3:b  main.c?C  \fR*
  697. .P2
  698. This request will print the local variable 
  699. .ul
  700. c
  701. in the function 
  702. .ul
  703. main
  704. at each occurrence of the breakpoint.
  705. The semicolon is used to separate multiple ADB requests on a single line.
  706. .PP
  707. Warning:
  708. setting a breakpoint causes the value of dot to be changed;
  709. executing the program under ADB does not change dot.
  710. Therefore:
  711. .P1
  712.     settab+4:b  .,5?ia
  713.     fopen+4:b
  714. .P2
  715. will print the last thing dot was set to
  716. (in the example \fIfopen+4\fP)
  717. .ul
  718. not
  719. the current location (\fIsettab+4\fP)
  720. at which the program is executing.
  721. .PP
  722. A breakpoint can be overwritten without first deleting the old breakpoint.
  723. For example:
  724. .P1
  725.     settab+4:b  settab,5?ia; ptab/o  \fR*
  726. .P2
  727. could be entered after typing the above requests.
  728. .PP
  729. Now the display of breakpoints:
  730. .P1
  731.     $b
  732. .P2
  733. shows the above request for the
  734. .ul
  735. settab
  736. breakpoint.
  737. When the breakpoint at
  738. .ul
  739. settab
  740. is encountered the ADB requests are executed.
  741. Note that the location at
  742. .ul
  743. settab+4
  744. has been changed to plant the breakpoint;
  745. all the other locations match their original value.
  746. .PP
  747. Using the functions,
  748. .ul
  749. f, g
  750. and 
  751. .ul
  752. h
  753. shown in Figure 3,
  754. we can follow the execution of each function by planting non-stopping
  755. breakpoints.
  756. We call ADB with the executable program of Figure 3 as follows:
  757. .P1
  758.     adb ex3 \-
  759. .P2
  760. Suppose we enter the following breakpoints:
  761. .P1
  762.     h+4:b    hcnt/d;  h.hi/;  h.hr/
  763.     g+4:b    gcnt/d;  g.gi/;  g.gr/
  764.     f+4:b    fcnt/d;  f.fi/;  f.fr/
  765.     :r
  766. .P2
  767. Each request line indicates that the variables are printed in decimal
  768. (by the specification \fBd\fR).
  769. Since the format is not changed, the \fBd\fR can be left off all but
  770. the first request.
  771. .PP
  772. The output in Figure 7 illustrates two points.
  773. First, the ADB requests in the breakpoint line are not
  774. examined until the program under
  775. test is run.
  776. That means any errors in those ADB requests is not detected until run time.
  777. At the location of the error ADB stops running the program.
  778. .PP
  779. The second point is the way ADB handles register variables.
  780. ADB uses the symbol table to address variables.
  781. Register variables, like \fIf.fr\fR above, have pointers to uninitialized
  782. places on the stack.
  783. Therefore the message "symbol not found".
  784. .PP
  785. Another way of getting at the data in this example is to print
  786. the variables used in the call as:
  787. .P1
  788.     f+4:b    fcnt/d;  f.a/;  f.b/;  f.fi/
  789.     g+4:b    gcnt/d;  g.p/;  g.q/;  g.gi/
  790.     :c
  791. .P2
  792. The operator / was used instead of ?
  793. to read values from the \fIcore\fP file.
  794. The output for each function, as shown in Figure 7, has the same format.
  795. For the function \fIf\fP, for example, it shows the name and value of the
  796. .ul
  797. external
  798. variable
  799. .ul
  800. fcnt.
  801. It also shows the address on the stack and value of the
  802. variables
  803. .ul
  804. a, b
  805. and
  806. .ul
  807. fi.
  808. .PP
  809. Notice that the addresses on the stack will continue to decrease
  810. until no address space is left for program execution
  811. at which time (after many pages of output)
  812. the program under test aborts.
  813. A display with names would be produced by requests like the following:
  814. .P1
  815.     f+4:b    fcnt/d;  f.a/"a="d;  f.b/"b="d;  f.fi/"fi="d
  816. .P2
  817. In this format the quoted string is printed literally and the \fBd\fP
  818. produces a decimal display of the variables.
  819. The results are shown in Figure 7.
  820. .NH 2
  821. Other Breakpoint Facilities
  822. .LP
  823. .IP \(bu 4
  824. Arguments and change of standard input and output are passed to a program as:
  825. .P1
  826.     :r  arg1  arg2 ... <infile  >outfile
  827. .P2
  828. This request
  829. kills any existing program under test and
  830. starts the
  831. .ul
  832. a.out
  833. afresh.
  834. .IP \(bu
  835. The program being debugged can be single stepped
  836. by:
  837. .P1
  838.     :s
  839. .P2
  840. If necessary, this request will start up the program being
  841. debugged and stop after executing
  842. the first instruction.
  843. .IP \(bu
  844. ADB allows a program to be entered at a specific address
  845. by typing:
  846. .P1
  847.     address:r
  848. .P2
  849. .IP \(bu
  850. The count field can be used to skip the first \fIn\fR breakpoints as:
  851. .P1
  852.     ,n:r
  853. .P2
  854. The request:
  855. .P1
  856.     ,n:c
  857. .P2
  858. may also be used for skipping the first \fIn\fR breakpoints
  859. when continuing a program.
  860. .sp
  861. .IP \(bu
  862. A program can be continued at an address different from the breakpoint by:
  863. .P1
  864.     address:c
  865. .P2
  866. .IP \(bu
  867. The program being debugged runs as a separate process and can be killed by:
  868. .P1
  869.     :k
  870. .P2
  871. .LP
  872. .NH
  873. Maps
  874. .PP
  875. UNIX supports several executable file formats.  These are used to tell
  876. the loader how to load  the program file.  File type 407
  877. is the most common and is generated by a C compiler invocation such as
  878. \fBcc pgm.c\fP.
  879. A 410 file is produced by a C compiler command of the form \fBcc -n pgm.c\fP,
  880. whereas a 411 file is produced by \fBcc -i pgm.c\fP.
  881. ADB interprets these different file formats and
  882. provides access to the different segments through a set of maps (see Figure 8).
  883. To print the maps type:
  884. .P1
  885.     $m
  886. .P2
  887. .PP
  888. In 407 files, both text (instructions) and data are intermixed.
  889. This makes it impossible for ADB to differentiate data from
  890. instructions and some of the printed symbolic addresses look incorrect;
  891. for example, printing data addresses as offsets from routines.
  892. .PP
  893. In 410 files (shared text), the instructions are separated from data and
  894. \fB?*\fR accesses the data part of the \fIa.out\fP file.
  895. The \fB?* \fP request tells ADB to use the second part of the
  896. map in the
  897. .ul
  898. a.out
  899. file.
  900. Accessing data in the \fIcore\fP file shows
  901. the data after it was modified by the execution of the program.
  902. Notice also that the data segment may have grown during
  903. program execution.
  904. .PP
  905. In 411 files (separated I & D space), the
  906. instructions and data are also separated.
  907. However, in this
  908. case, since data is mapped through a separate set of segmentation
  909. registers, the base of the data segment is also relative to address zero.
  910. In this case since the addresses overlap it is necessary to use
  911. the \fB?*\fR operator to access the data space of the \fIa.out\fP file.
  912. In both 410 and 411 files the corresponding
  913. core file does not contain the program text.
  914. .PP
  915. Figure 9 shows the display of three maps
  916. for the same program linked as a 407, 410, 411 respectively.
  917. The b, e, and f fields are used by ADB to map
  918. addresses into file addresses.
  919. The "f1" field is the
  920. length of the header at the beginning of the file (020 bytes
  921. for an \fIa.out\fP file and 02000 bytes for a \fIcore\fP file).
  922. The "f2" field is the displacement from the beginning of the file to the data.
  923. For a 407 file with mixed text and data this is the
  924. same as the length of the header; for 410 and 411 files this
  925. is the length of the header plus the size of the text portion.
  926. .PP
  927. The "b" and "e" fields are the starting and ending locations
  928. for a segment.
  929. Given an address, A, the location in
  930. the file (either \fIa.out\fP or \fIcore\fP) is calculated as:
  931. .P1
  932.     b1\(<=A\(<=e1 =\h'-.5m'> file address = (A\-b1)+f1
  933.     b2\(<=A\(<=e2 =\h'-.5m'> file address = (A\-b2)+f2
  934. .P2
  935. A user can access locations by using the ADB defined variables.
  936. The \fB$v\fR request prints the variables initialized by ADB:
  937. .P1
  938.     b    base address of data segment
  939.     d    length of the data segment
  940.     s    length of the stack
  941.     t    length of the text
  942.     m    execution type (407,410,411)
  943. .P2
  944. .PP
  945. In Figure 9 those variables not present are zero.
  946. Use can be made of these variables by expressions such as:
  947. .P1
  948.     <b
  949. .P2
  950. in the address field.
  951. Similarly the value of the variable can be changed by an assignment request
  952. such as:
  953. .P1
  954.     02000>b
  955. .P2
  956. that sets \fBb\fP to octal 2000.
  957. These variables are useful to know if the file under examination
  958. is an executable or \fIcore\fP image file.
  959. .PP
  960. ADB reads the header of the \fIcore\fP image file to find the
  961. values for these variables.
  962. If the second file specified does not
  963. seem to be a \fIcore\fP file, or if it is missing then the header of
  964. the executable file is used instead.
  965. .NH
  966. Advanced Usage
  967. .PP
  968. It is possible with ADB to combine formatting requests
  969. to provide elaborate displays.
  970. Below are several examples.
  971. .NH 2
  972. Formatted dump
  973. .PP
  974. The line:
  975. .P1
  976.     <b,\-1/4o4^8Cn
  977. .P2
  978. prints 4 octal words followed by their ASCII interpretation
  979. from the data space of the core image file.
  980. Broken down, the various request pieces mean:
  981. .sp
  982. .in 1.7i
  983. .ta .7i
  984. .ti -.7i
  985. <b    The base address of the data segment.
  986. .sp
  987. .ti -.7i
  988. <b,\-1    Print from the base address to the end of file.
  989. A negative count is used here and elsewhere to loop indefinitely
  990. or until some error condition (like end of file) is detected.
  991. .sp
  992. .ti -1.7i
  993. The format \fB4o4^8Cn\fR is broken down as follows:
  994. .sp
  995. .ti -.7i
  996. 4o    Print 4 octal locations.
  997. .sp
  998. .ti -.7i
  999. 4^    Backup the current address 4 locations (to the original start of the field).
  1000. .sp
  1001. .ti -.7i
  1002. 8C    Print 8 consecutive characters using an escape convention;
  1003. each character in the range 0 to 037 is printed as @ followed by the corresponding character in the range 0140 to 0177.
  1004. An @ is printed as @@.
  1005. .sp
  1006. .ti -.7i
  1007. n    Print a newline.
  1008. .in -1.7i
  1009. .fi
  1010. .sp
  1011. .PP
  1012. The request:
  1013. .P1
  1014.     <b,<d/4o4^8Cn
  1015. .P2
  1016. could have been used instead to allow the printing to stop
  1017. at the end of the data segment (<d provides the data segment size in bytes).
  1018. .PP
  1019. The formatting requests can be combined with ADB's ability
  1020. to read in a script to produce a core image dump script.
  1021. ADB is invoked as:
  1022. .P1
  1023.     adb a.out core < dump
  1024. .P2
  1025. to read in a script file,
  1026. .ul
  1027. dump,
  1028. of requests.
  1029. An example of such a script is:
  1030. .P1
  1031.     120$w
  1032.     4095$s
  1033.     $v
  1034.     =3n
  1035.     $m
  1036.     =3n"C Stack Backtrace"
  1037.     $C
  1038.     =3n"C External Variables"
  1039.     $e
  1040.     =3n"Registers"
  1041.     $r
  1042.     0$s
  1043.     =3n"Data Segment"
  1044.     <b,\-1/8ona
  1045. .P2
  1046. .PP
  1047. The request \fB120$w\fP sets the width of the output to
  1048. 120 characters
  1049. (normally, the width is 80 characters).
  1050. ADB attempts to print addresses as:
  1051. .P1
  1052.     symbol + offset
  1053. .P2
  1054. The request \fB4095$s\fP increases the maximum permissible offset
  1055. to the nearest symbolic address from 255 (default) to 4095.
  1056. The request \fB=\fP can be used to print literal strings.
  1057. Thus,
  1058. headings are provided in this
  1059. .ul
  1060. dump
  1061. program
  1062. with requests of the form:
  1063. .P1
  1064.     =3n"C Stack Backtrace"
  1065. .P2
  1066. that spaces three lines and prints the literal
  1067. string.
  1068. The request \fB$v\fP prints all non-zero ADB variables (see Figure 8).
  1069. The request
  1070. \fB0$s\fP
  1071. sets the maximum offset for symbol matches to zero thus
  1072. suppressing the printing of symbolic labels in favor
  1073. of octal values.
  1074. Note that this is only done for the printing of the data segment.
  1075. The request:
  1076. .P1
  1077.     <b,\-1/8ona
  1078. .P2
  1079. prints a dump from the base of the data segment to the end of file
  1080. with an octal address field and eight octal numbers per line.
  1081. .PP
  1082. Figure 11 shows the results of some formatting requests
  1083. on the C program of Figure 10.
  1084. .NH 2
  1085. Directory Dump
  1086. .PP
  1087. As another illustration (Figure 12) consider a set of requests to dump
  1088. the contents of a directory (which is made up
  1089. of an integer \fIinumber\fP followed by a 14 character name):
  1090. .P1
  1091.     adb dir \-
  1092.     =n8t"Inum"8t"Name"
  1093.     0,\-1? u8t14cn
  1094. .P2
  1095. In this example, the \fBu\fP prints the \fIinumber\fP as an unsigned decimal integer,
  1096. the \fB8t\fP means that ADB will space to the next
  1097. multiple of 8 on the output line, and the \fB14c\fP prints the 14 character file name.
  1098. .NH 2
  1099. Ilist Dump
  1100. .PP
  1101. Similarly the contents of the \fIilist\fP of a file system, (e.g. /dev/src,
  1102. on UNIX systems distributed by the UNIX Support Group;
  1103. see UNIX Programmer's
  1104. Manual Section V) could be dumped with the following set of 
  1105. requests:
  1106. .P1
  1107.     adb /dev/src \-
  1108.     02000>b
  1109.     ?m <b
  1110.     <b,\-1?"flags"8ton"links,uid,gid"8t3bn",size"8tbrdn"addr"8t8un"times"8t2Y2na
  1111. .P2
  1112. In this example the value of the base for the map was changed 
  1113. to 02000 (by saying \fB?m<b\fR) since that is the start of an \fIilist\fP within a file system.
  1114. An artifice (\fBbrd\fP above) was used to print the 24 bit size field
  1115. as a byte, a space, and a decimal integer.
  1116. The last access time and last modify time are printed with the
  1117. \fB2Y\fR
  1118. operator.
  1119. Figure 12 shows portions of these requests as applied to a directory
  1120. and file system.
  1121. .NH 2
  1122. Converting values
  1123. .PP
  1124. ADB may be used to convert values from one representation to
  1125. another.
  1126. For example:
  1127. .P1
  1128.     072 = odx
  1129. .P2
  1130. will print
  1131. .P1
  1132.     072    58    #3a
  1133. .P2
  1134. which is the octal, decimal and hexadecimal representations
  1135. of 072 (octal).
  1136. The format is remembered so that typing
  1137. subsequent numbers will print them in the given formats.
  1138. Character values may be converted similarly, for example:
  1139. .P1
  1140.     'a' = co
  1141. .P2
  1142. prints
  1143. .P1
  1144.     a    0141
  1145. .P2
  1146. It may also be used to evaluate expressions but be
  1147. warned that all binary operators have
  1148. the same precedence which is lower than that for unary operators.
  1149. .NH
  1150. Patching
  1151. .PP
  1152. Patching files with ADB is accomplished with the 
  1153. .ul
  1154. write,
  1155. \fBw\fP or \fBW\fP, request (which is not like the \fIed\fP editor write command).
  1156. This is often used in conjunction with the 
  1157. .ul
  1158. locate,
  1159. \fBl\fP or \fBL\fP
  1160. request.
  1161. In general, the request syntax for \fBl\fP and \fBw\fP are similar as follows:
  1162. .P1
  1163.     ?l value
  1164. .P2
  1165. The request \fBl\fP is used to match on two bytes, \fBL\fP is used for
  1166. four bytes.
  1167. The request \fBw\fP is used to write two bytes, whereas
  1168. \fBW\fP writes four bytes.
  1169. The \fBvalue\fP field in either 
  1170. .ul
  1171. locate
  1172. or
  1173. .ul
  1174. write
  1175. requests
  1176. is an expression.
  1177. Therefore, decimal and octal numbers, or character strings are supported.
  1178. .PP
  1179. In order to modify a file, ADB must be called as:
  1180. .P1
  1181.     adb \-w file1 file2
  1182. .P2
  1183. When called with this option, 
  1184. .ul
  1185. file1
  1186. and 
  1187. .ul
  1188. file2
  1189. are created if necessary and opened for both reading and writing.
  1190. .PP
  1191. For example, consider the C program shown in Figure 10.
  1192. We can change the word "This" to "The " in the executable file
  1193. for this program, \fIex7\fP, by using the following requests:
  1194. .P1
  1195.     adb \-w ex7 \-
  1196.     ?l 'Th'
  1197.     ?W 'The '
  1198. .P2
  1199. The request \fB?l\fP starts at dot and stops at the first match of "Th"
  1200. having set dot to the address of the location found.
  1201. Note the use of \fB?\fP to write to the 
  1202. .ul
  1203. a.out
  1204. file.
  1205. The form \fB?*\fP would have been used for a 411 file.
  1206. .PP
  1207. More frequently the 
  1208. request will be typed as:
  1209. .P1
  1210.     ?l 'Th'; ?s
  1211. .P2
  1212. and locates the first occurrence of "Th" and print the entire string.
  1213. Execution of this ADB request will set dot to the address of the 
  1214. "Th" characters.
  1215. .PP
  1216. As another example of the utility of the patching facility,
  1217. consider a C program that has an internal logic flag.
  1218. The flag could be set by the user through ADB and the program run.
  1219. For example:
  1220. .P1
  1221.     adb a.out \-
  1222.     :s arg1 arg2
  1223.     flag/w 1
  1224.     :c
  1225. .P2
  1226. The \fB:s\fR request is normally used to single step through a process
  1227. or start a process in single step mode.
  1228. In this case it starts
  1229. .ul
  1230. a.out
  1231. as a subprocess
  1232. with arguments \fBarg1\fP and \fBarg2\fP.
  1233. If there is a subprocess running ADB writes to it rather than to the file
  1234. so the \fBw\fP request causes \fIflag\fP to be changed in the memory of the subprocess.
  1235. .NH
  1236. Anomalies
  1237. .PP
  1238. Below is a list of some strange things that users
  1239. should be aware of.
  1240. .IP 1.
  1241. Function calls and arguments are put on the stack by the C
  1242. save routine.
  1243. Putting breakpoints at the entry point to routines
  1244. means that the function appears not to have been called
  1245. when the
  1246. breakpoint occurs.
  1247. .IP 2.
  1248. When printing addresses, ADB uses
  1249. either text or data symbols from the \fIa.out\fP file.
  1250. This sometimes causes unexpected symbol names to be printed 
  1251. with data (e.g. \fIsavr5+022\fP).
  1252. This does not happen if
  1253. \fB?\fR is used for text (instructions)
  1254. and \fB/\fP for data.
  1255. .IP 3.
  1256. ADB cannot handle C register variables
  1257. in the most recently activated function.
  1258. .LP
  1259. .NH
  1260. Acknowledgements
  1261. .PP
  1262. The authors are grateful for the thoughtful comments
  1263. on how to organize this document
  1264. from R. B. Brandt, E. N. Pinson and B. A. Tague.
  1265. D. M. Ritchie made the system changes necessary to accommodate
  1266. tracing within ADB. He also participated in discussions 
  1267. during the writing of ADB.
  1268. His earlier work with DB and CDB led to many of the 
  1269. features found in ADB.
  1270. .SG MH-8234-JFM/1273-SRB-unix
  1271. .NH
  1272. References
  1273. .LP
  1274. .IP 1.
  1275. D. M. Ritchie and K. Thompson,
  1276. ``The UNIX Time-Sharing System,''
  1277. CACM, July, 1974.
  1278. .IP 2.
  1279. B. W. Kernighan and D. M. Ritchie,
  1280. .ul
  1281. The C Programming Language,
  1282. Prentice-Hall, 1978.
  1283. .IP 3.
  1284. K. Thompson and D. M. Ritchie,
  1285. UNIX Programmer's Manual - 7th Edition,
  1286. 1978.
  1287. .IP 4.
  1288. B. W. Kernighan and P. J. Plauger,
  1289. .ul
  1290. Software Tools,
  1291. Addison-Wesley, 1976.
  1292.