db 17 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018
  1. .TH DB 1
  2. .SH NAME
  3. db \- debugger
  4. .SH SYNOPSIS
  5. .B db
  6. [
  7. .I option ...
  8. ]
  9. [
  10. .I textfile
  11. ]
  12. [
  13. .I pid
  14. ]
  15. .SH DESCRIPTION
  16. .I Db
  17. is a general purpose debugging program.
  18. It may be used to examine files and to provide
  19. a controlled environment for the execution
  20. of Plan 9 programs.
  21. .PP
  22. A
  23. .I textfile
  24. is a file containing the text and initialized
  25. data of an executable program.
  26. A
  27. .I memfile
  28. is the memory image of an executing process. It is
  29. usually accessed via the process id
  30. .RI ( pid )
  31. of the process in
  32. .BI /proc/ pid /mem\f1.
  33. A
  34. .I memfile
  35. contains the text, data, and saved registers and
  36. process state. A
  37. .I map
  38. associated with each
  39. .I textfile
  40. or
  41. .I memfile
  42. supports accesses to instructions and data in the file;
  43. see `Addresses'.
  44. .PP
  45. An argument consisting entirely of digits is assumed
  46. to be a process id; otherwise, it is the name of a
  47. .IR textfile .
  48. When a
  49. .I textfile
  50. is given, the textfile map
  51. is associated with it.
  52. If only a
  53. .I pid
  54. is given, the textfile map is
  55. associated with
  56. .BI /proc/ pid /text\f1.
  57. When a
  58. .I pid
  59. is given, the memfile map is associated with
  60. .BI /proc/ pid /mem\f1;
  61. otherwise it is undefined and accesses to the
  62. .I memfile
  63. are not permitted.
  64. .PP
  65. Commands to
  66. .I db
  67. are read from the standard input and
  68. responses are to the standard output.
  69. The options are
  70. .TP
  71. .BI -k
  72. Use the kernel stack of process
  73. .IR pid
  74. to debug the executing kernel process.
  75. If
  76. .I textfile
  77. is not specified, file
  78. .BI / $cputype /9 type
  79. is used, where
  80. .I type
  81. is the second word in
  82. .BR $terminal .
  83. .TP
  84. .B -w
  85. Create
  86. .I textfile
  87. and
  88. .I memfile
  89. if they don't exist; open them for writing
  90. as well as reading.
  91. .TP
  92. .BI -I path
  93. Directory in which to look for relative path names in
  94. .B $<
  95. and
  96. .B $<<
  97. commands.
  98. .TP
  99. .BI -m machine
  100. Assume instructions are for the given CPU type
  101. (any standard architecture name, such as
  102. .B amd64
  103. or
  104. .BR 386 ,
  105. plus
  106. .B mipsco
  107. and
  108. .BR sunsparc ,
  109. which cause disassembly to the manufacturer's syntax)
  110. instead of using the magic number to select
  111. the CPU type.
  112. .PP
  113. Most
  114. .I db
  115. commands have the following form:
  116. .IP
  117. .RI [ address ]
  118. .RB [ ,
  119. .IR count ]
  120. .RI [ command ]
  121. .PP
  122. If
  123. .I address
  124. is present then the current position, called `dot',
  125. is set to
  126. .IR address .
  127. Initially dot
  128. is set to 0.
  129. Most commands are repeated
  130. .I count
  131. times with
  132. dot advancing between repetitions.
  133. The default
  134. .I count
  135. is 1.
  136. .I Address
  137. and
  138. .I count
  139. are expressions.
  140. Multiple commands on one line must be separated by
  141. .LR ; .
  142. .SS Expressions
  143. Expressions are evaluated as long
  144. .IR ints .
  145. .TP 7.2n
  146. .B .
  147. The value of dot.
  148. .TP 7.2n
  149. .B +
  150. The value of dot
  151. incremented by the current increment.
  152. .TP 7.2n
  153. .B ^
  154. The value of dot
  155. decremented by the current increment.
  156. .TP 7.2n
  157. .B \&"
  158. The last
  159. .I address
  160. typed.
  161. .TP 7.2n
  162. .I integer
  163. A number, in decimal radix by default.
  164. The prefixes
  165. .L 0
  166. and
  167. .L 0o
  168. and
  169. .L 0O
  170. (zero oh) force interpretation
  171. in octal radix; the prefixes
  172. .L 0t
  173. and
  174. .L 0T
  175. force interpretation in
  176. decimal radix; the prefixes
  177. .LR 0x ,
  178. .LR 0X ,
  179. and
  180. .L #
  181. force interpretation in
  182. hexadecimal radix.
  183. Thus
  184. .LR 020 ,
  185. .LR 0o20 ,
  186. .LR 0t16 ,
  187. and
  188. .L #10
  189. all represent sixteen.
  190. .TP 7.2n
  191. .IB integer . fraction
  192. A single-precision floating point number.
  193. .TP 7.2n
  194. .BI \' c\| \'
  195. The
  196. 16-bit
  197. value of a character.
  198. .L \e
  199. may be used to escape a
  200. .LR \' .
  201. .TP 7.2n
  202. .BI < name
  203. The value of
  204. .IR name ,
  205. which is a register name.
  206. The register names are
  207. those printed by the
  208. .B $r
  209. command.
  210. .TP 7.2n
  211. .I symbol
  212. A
  213. .I symbol
  214. is a sequence
  215. of upper or lower case letters, underscores or
  216. digits, not starting with a digit.
  217. .L \e
  218. may be used to escape other characters.
  219. The location of the
  220. .I symbol
  221. is calculated from the symbol table
  222. in
  223. .IR textfile .
  224. .TP 7.2n
  225. .IB routine . name
  226. The address of the variable
  227. .I name
  228. in the specified
  229. C routine.
  230. Both
  231. .I routine
  232. and
  233. .I name
  234. are
  235. .IR symbols .
  236. If
  237. .I name
  238. is omitted the value is the address of the
  239. most recently activated stack frame
  240. corresponding to
  241. .IR routine ;
  242. if
  243. .I routine
  244. is omitted,
  245. the active procedure
  246. is assumed.
  247. .TP 7.2n
  248. .IB file : integer
  249. The address of the instruction corresponding
  250. to the source statement at the indicated
  251. line number of the file. If the source line contains
  252. no executable statement, the address of the
  253. instruction associated with the nearest
  254. executable source line is returned. Files
  255. begin at line 1. If multiple files of the same
  256. name are loaded, an expression of this form resolves
  257. to the first file encountered in the symbol table.
  258. .TP 7.2n
  259. .BI ( exp )
  260. The value of the expression
  261. .IR exp .
  262. .LP
  263. .I Monadic operators
  264. .RS
  265. .TP 7.2n
  266. .BI * exp
  267. The contents of the location addressed
  268. by
  269. .I exp
  270. in
  271. .IR memfile .
  272. .TP 7.2n
  273. .BI @ exp
  274. The contents of the location addressed by
  275. .I exp
  276. in
  277. .IR textfile .
  278. .TP 7.2n
  279. .BI - exp
  280. Integer negation.
  281. .TP 7.2n
  282. .BI ~ exp
  283. Bitwise complement.
  284. .TP 7.2n
  285. .BI % exp
  286. When used as an
  287. .IR address ,
  288. .I exp
  289. is an offset into the segment named
  290. .IR ublock ;
  291. see `Addresses'.
  292. .RE
  293. .LP
  294. .I "Dyadic\ operators"
  295. are left-associative
  296. and are less binding than monadic operators.
  297. .RS
  298. .TP 7.2n
  299. .IB e1 + e2
  300. Integer addition.
  301. .TP 7.2n
  302. .IB e1 - e2
  303. Integer subtraction.
  304. .TP 7.2n
  305. .IB e1 * e2
  306. Integer multiplication.
  307. .TP 7.2n
  308. .IB e1 % e2
  309. Integer division.
  310. .TP 7.2n
  311. .IB e1 & e2
  312. Bitwise conjunction.
  313. .TP 7.2n
  314. .IB e1 | e2
  315. Bitwise disjunction.
  316. .TP 7.2n
  317. .IB e1 # e2
  318. .I E1
  319. rounded up to the next multiple of
  320. .IR e2 .
  321. .RE
  322. .DT
  323. .SS Commands
  324. Most commands have the following syntax:
  325. .TP .5i
  326. .BI ? f
  327. Locations starting at
  328. .I address
  329. in
  330. .I textfile
  331. are printed according to the format
  332. .IR f .
  333. .TP
  334. .BI / f
  335. Locations starting at
  336. .I address
  337. in
  338. .I memfile
  339. are printed according to the format
  340. .IR f .
  341. .TP
  342. .BI = f
  343. The value of
  344. .I address
  345. itself is printed according to the format
  346. .IR f .
  347. .PP
  348. A
  349. .I format
  350. consists of one or more characters that specify a style
  351. of printing.
  352. Each format character may be preceded by a decimal integer
  353. that is a repeat count for the format character.
  354. If no format is given then the last format is used.
  355. .PP
  356. Most format letters fetch some data,
  357. print it,
  358. and advance (a local copy of) dot
  359. by the number of bytes fetched.
  360. The total number of bytes in a format becomes the
  361. .IR "current increment" .
  362. .ta 2.5n .5i
  363. .RS
  364. .TP
  365. .PD 0
  366. .B o
  367. Print two-byte integer in octal.
  368. .TP
  369. .B O
  370. Print four-byte integer in octal.
  371. .TP
  372. .B q
  373. Print two-byte integer in signed octal.
  374. .TP
  375. .B Q
  376. Print four-byte integer in signed octal.
  377. .TP
  378. .B d
  379. Print two-byte integer in decimal.
  380. .TP
  381. .B D
  382. Print four-byte integer in decimal.
  383. .TP
  384. .B V
  385. Print eight-byte integer in decimal.
  386. .TP
  387. .B Z
  388. Print eight-byte integer in unsigned decimal.
  389. .TP
  390. .B x
  391. Print two-byte integer in hexadecimal.
  392. .TP
  393. .B X
  394. Print four-byte integer in hexadecimal.
  395. .TP
  396. .B Y
  397. Print eight-byte integer in hexadecimal.
  398. .TP
  399. .B u
  400. Print two-byte integer in unsigned decimal.
  401. .TP
  402. .B U
  403. Print four-byte integer in unsigned decimal.
  404. .TP
  405. .B f
  406. Print
  407. as a single-precision floating point number.
  408. .TP
  409. .B F
  410. Print double-precision floating point.
  411. .TP
  412. .B b
  413. Print the addressed byte in hexadecimal.
  414. .TP
  415. .B c
  416. Print the addressed byte as an
  417. .SM ASCII
  418. character.
  419. .TP
  420. .B C
  421. Print the addressed byte as a character.
  422. Printable
  423. .SM ASCII
  424. characters
  425. are represented normally; others
  426. are printed in the form
  427. .BR \exnn .
  428. .TP
  429. .B s
  430. Print the addressed characters, as a
  431. .SM UTF
  432. string, until a zero byte
  433. is reached.
  434. Advance dot
  435. by the length of the string,
  436. including the zero terminator.
  437. .TP
  438. .B S
  439. Print a string using
  440. the escape convention (see
  441. .B C
  442. above).
  443. .TP
  444. .B r
  445. Print as
  446. .SM UTF
  447. the addressed two-byte integer (rune).
  448. .TP
  449. .B R
  450. Print as
  451. .SM UTF
  452. the addressed two-byte integers as runes
  453. until a zero rune is reached.
  454. Advance dot
  455. by the length of the string,
  456. including the zero terminator.
  457. .TP
  458. .B i
  459. Print as machine instructions. Dot is
  460. incremented by the size of the instruction.
  461. .TP
  462. .B I
  463. As
  464. .B i
  465. above, but print the machine instructions in
  466. an alternate form if possible:
  467. .B sunsparc
  468. and
  469. .B mipsco
  470. reproduce the manufacturers' syntax.
  471. .TP
  472. .B M
  473. Print the addressed machine instruction in a
  474. machine-dependent hexadecimal form.
  475. .TP
  476. .B a
  477. Print the value of dot
  478. in symbolic form.
  479. Dot is unaffected.
  480. .TP
  481. .B A
  482. Print the value of dot
  483. in hexadecimal.
  484. Dot is unaffected.
  485. .TP
  486. .B z
  487. Print the function name, source file, and line number
  488. corresponding to dot (textfile only). Dot is unaffected.
  489. .TP
  490. .B p
  491. Print the addressed value in symbolic form.
  492. Dot is advanced by the size of a machine address.
  493. .TP
  494. .B t
  495. When preceded by an integer, tabs to the next
  496. appropriate tab stop.
  497. For example,
  498. .B 8t
  499. moves to the next 8-space tab stop.
  500. Dot is unaffected.
  501. .TP
  502. .B n
  503. Print a newline.
  504. Dot is unaffected.
  505. .tr '"
  506. .TP
  507. .BR ' ... '
  508. Print the enclosed string.
  509. Dot is unaffected.
  510. .br
  511. .tr ''
  512. .TP
  513. .B ^
  514. Dot is decremented by the current increment.
  515. Nothing is printed.
  516. .TP
  517. .B +
  518. Dot is incremented by 1.
  519. Nothing is printed.
  520. .TP
  521. .B -
  522. Dot is decremented by 1.
  523. Nothing is printed.
  524. .RE
  525. .PD
  526. .LP
  527. Other commands include:
  528. .TP
  529. newline
  530. Update dot by the current increment.
  531. Repeat the previous command with a
  532. .I count
  533. of 1.
  534. .TP
  535. .RB [ ?/ ] l "\fI value mask\fR"
  536. Words starting at dot
  537. are masked with
  538. .I mask
  539. and compared with
  540. .I value
  541. until
  542. a match is found.
  543. If
  544. .B l
  545. is used,
  546. the match is for a two-byte integer;
  547. .B L
  548. matches four bytes.
  549. If no match is found then dot
  550. is unchanged; otherwise dot
  551. is set to the matched location.
  552. If
  553. .I mask
  554. is omitted then ~0 is used.
  555. .TP
  556. .RB [ ?/ ] w "\fI value ...\fR"
  557. Write the two-byte
  558. .I value
  559. into the addressed
  560. location.
  561. If the command is
  562. .BR W ,
  563. write four bytes.
  564. .TP
  565. .RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]
  566. .br
  567. New values for
  568. .RI ( b,\ e,\ f )
  569. in the segment named
  570. .I s
  571. are recorded. Valid segment names are
  572. .IR text ,
  573. .IR data ,
  574. or
  575. .IR ublock .
  576. If less than three address expressions are given,
  577. the remaining parameters are left unchanged.
  578. If the list is terminated by
  579. .L ?
  580. or
  581. .L /
  582. then the file
  583. .RI ( textfile
  584. or
  585. .I memfile
  586. respectively) is used
  587. for subsequent requests.
  588. For example,
  589. .L /m?
  590. causes
  591. .L /
  592. to refer to
  593. .IR textfile .
  594. .TP
  595. .BI > name
  596. Dot is assigned to the variable or register named.
  597. .TP
  598. .B !
  599. The rest of the line is passed to
  600. .IR rc (1)
  601. for execution.
  602. .TP
  603. .BI $ modifier
  604. Miscellaneous commands.
  605. The available
  606. .I modifiers
  607. are:
  608. .RS
  609. .TP
  610. .PD 0
  611. .BI < f
  612. Read commands from the file
  613. .IR f .
  614. If this command is executed in a file, further commands
  615. in the file are not seen.
  616. If
  617. .I f
  618. is omitted, the current input stream is terminated.
  619. If a
  620. .I count
  621. is given, and is zero, the command is ignored.
  622. .TP
  623. .BI << f
  624. Similar to
  625. .B <
  626. except it can be used in a file of commands without
  627. causing the file to be closed.
  628. There is a (small) limit to the number of
  629. .B <<
  630. files that can be open at once.
  631. .br
  632. .ns
  633. .TP
  634. .BI > f
  635. Append output to the file
  636. .IR f ,
  637. which is created if it does not exist.
  638. If
  639. .I f
  640. is omitted, output is returned to the terminal.
  641. .TP
  642. .B ?
  643. Print process id, the condition which caused stopping or termination,
  644. the registers and the instruction addressed by
  645. .BR pc .
  646. This is the default if
  647. .I modifier
  648. is omitted.
  649. .TP
  650. .B r
  651. Print the general registers and
  652. the instruction addressed by
  653. .BR pc .
  654. Dot is set to
  655. .BR pc .
  656. .TP
  657. .B R
  658. Like
  659. .BR $r ,
  660. but include miscellaneous processor control registers
  661. and floating point registers.
  662. .TP
  663. .B f
  664. Print floating-point register values as
  665. single-precision floating point numbers.
  666. .TP
  667. .B F
  668. Print floating-point register values as
  669. double-precision floating point numbers.
  670. .TP
  671. .B b
  672. Print all breakpoints
  673. and their associated counts and commands. `B' produces the same results.
  674. .TP
  675. .B c
  676. Stack backtrace.
  677. If
  678. .I address
  679. is given, it specifies the address of a pair of 32-bit
  680. values containing the
  681. .B sp
  682. and
  683. .B pc
  684. of an active process. This allows selecting
  685. among various contexts of a multi-threaded
  686. process.
  687. If
  688. .B C
  689. is used, the names and (long) values of all
  690. parameters,
  691. automatic
  692. and static variables are printed for each active function.
  693. If
  694. .I count
  695. is given, only the first
  696. .I count
  697. frames are printed.
  698. .TP
  699. .B a
  700. Attach to the running process whose pid
  701. is contained in
  702. .IR address .
  703. .TP
  704. .B e
  705. The names and values of all
  706. external variables are printed.
  707. .TP
  708. .B w
  709. Set the page width for output to
  710. .I address
  711. (default 80).
  712. .TP
  713. .B q
  714. Exit from
  715. .IR db .
  716. .TP
  717. .B m
  718. Print the address maps.
  719. .TP
  720. .B k
  721. Simulate kernel memory management.
  722. .TP
  723. .BI M machine
  724. Set the
  725. .I machine
  726. type used for disassembling instructions.
  727. .PD
  728. .RE
  729. .TP
  730. .BI : modifier
  731. Manage a subprocess.
  732. Available modifiers are:
  733. .RS
  734. .TP
  735. .PD 0
  736. .BI h
  737. Halt
  738. an asynchronously running process to allow breakpointing.
  739. Unnecessary for processes created under
  740. .IR db ,
  741. e.g. by
  742. .BR :r .
  743. .TP
  744. .BI b c
  745. Set breakpoint at
  746. .IR address .
  747. The breakpoint is executed
  748. .IR count \-1
  749. times before
  750. causing a stop.
  751. Also, if a command
  752. .I c
  753. is given it is executed at each
  754. breakpoint and if it sets dot to zero
  755. the breakpoint causes a stop.
  756. .TP
  757. .B d
  758. Delete breakpoint at
  759. .IR address .
  760. .TP
  761. .B r
  762. Run
  763. .I textfile
  764. as a subprocess.
  765. If
  766. .I address
  767. is given the
  768. program is entered at that point; otherwise
  769. the standard entry point is used.
  770. .I Count
  771. specifies how many breakpoints are to be
  772. ignored before stopping.
  773. Arguments to the subprocess may be supplied on the
  774. same line as the command.
  775. An argument starting with < or > causes the standard
  776. input or output to be established for the command.
  777. .TP
  778. .BI c s
  779. The subprocess is continued.
  780. If
  781. .I s
  782. is omitted
  783. or nonzero,
  784. the subprocess
  785. is sent the note that caused it to stop.
  786. If 0
  787. is specified,
  788. no note is sent.
  789. (If the stop was due to a breakpoint or single-step,
  790. the corresponding note is elided before continuing.)
  791. Breakpoint skipping is the same
  792. as for
  793. .BR r .
  794. .TP
  795. .BI s s
  796. As for
  797. .B c
  798. except that
  799. the subprocess is single stepped for
  800. .I count
  801. machine instructions.
  802. If a note is pending,
  803. it is received
  804. before the first instruction is executed.
  805. If there is no current subprocess then
  806. .I textfile
  807. is run
  808. as a subprocess as for
  809. .BR r .
  810. In this case no note can be sent; the remainder of the line
  811. is treated as arguments to the subprocess.
  812. .TP
  813. .BI S s
  814. Identical to
  815. .B s
  816. except the subprocess is single stepped for
  817. .I count
  818. lines of C source. In optimized code, the correspondence
  819. between C source and the machine instructions is
  820. approximate at best.
  821. .TP
  822. .BI x
  823. The current subprocess, if any, is released by
  824. .I db
  825. and allowed to continue executing normally.
  826. .TP
  827. .B k
  828. The current subprocess, if any, is terminated.
  829. .TP
  830. .BI n c
  831. Display the pending notes for the process.
  832. If
  833. .I c
  834. is specified, first delete
  835. .I c'th
  836. pending note.
  837. .PD
  838. .RE
  839. .SS Addresses
  840. The location in a file or memory image associated with
  841. an address is calculated from a map
  842. associated with the file.
  843. Each map contains one or more quadruples
  844. .RI ( "t, b, e, f" ),
  845. defining a segment named
  846. .I t
  847. (usually,
  848. .IR text ,
  849. .IR data ,
  850. or
  851. .IR ublock )
  852. mapping addresses in the range
  853. .I b
  854. through
  855. .I e
  856. to the part of the file
  857. beginning at
  858. offset
  859. .IR f .
  860. The memory model of a Plan 9 process assumes
  861. that segments are disjoint. There
  862. can be more than one segment of a given type (e.g., a process
  863. may have more than one text segment) but segments
  864. may not overlap.
  865. An address
  866. .I a
  867. is translated
  868. to a file address
  869. by finding a segment
  870. for which
  871. .IR b ≤ a < e ;
  872. the location in the file
  873. is then
  874. .IR address + f \- b .
  875. .PP
  876. Usually,
  877. the text and initialized data of a program
  878. are mapped by segments called
  879. .I text
  880. and
  881. .IR data .
  882. Since a program file does not contain bss, stack or ublock data,
  883. these data are
  884. not mapped by the data segment.
  885. The text segment is mapped similarly in
  886. a normal (i.e., non-kernel)
  887. .IR memfile .
  888. However, the segment called
  889. .I data
  890. maps memory from the beginning of the program's data space to
  891. the base of the ublock.
  892. This region contains the program's static data, the bss, the
  893. heap and the stack. A segment
  894. called
  895. .I ublock
  896. maps the page containing its registers and process state.
  897. .PP
  898. Sometimes it is useful to define a map with a single segment
  899. mapping the region from 0 to 0xFFFFFFFF; a map of this type
  900. allows the entire file to be examined
  901. without address translation.
  902. .PP
  903. Registers are saved at a machine-dependent offset in the ublock.
  904. It is usually not necessary to know this offset; the
  905. .BR $r ,
  906. .BR $R ,
  907. .BR $f ,
  908. and
  909. .BR $F
  910. commands calculate it and display the register contents.
  911. .PP
  912. The
  913. .B $m
  914. command dumps the currently active maps. The
  915. .B ?m
  916. and
  917. .B /m
  918. commands modify the segment parameters in the
  919. .I textfile
  920. and
  921. .I memfile
  922. maps, respectively.
  923. .SH EXAMPLES
  924. To set a breakpoint at the beginning of
  925. .B write()
  926. in extant process 27:
  927. .IP
  928. .EX
  929. % db 27
  930. :h
  931. write:b
  932. :c
  933. .EE
  934. .PP
  935. To examine the Plan 9 kernel stack for process 27:
  936. .IP
  937. .EX
  938. % db -k 27
  939. $C
  940. .EE
  941. .PP
  942. Similar, but using a kernel named
  943. .BR test :
  944. .IP
  945. .EX
  946. % db -k test 27
  947. $C
  948. .EE
  949. .PP
  950. To set a breakpoint at the entry of function
  951. .B parse
  952. when the local variable
  953. .B argc
  954. in
  955. .B main
  956. is equal to 1:
  957. .IP
  958. .EX
  959. parse:b *main.argc-1=X
  960. .EE
  961. .PP
  962. This prints the value of
  963. .B argc-1
  964. which as a side effect sets dot; when
  965. .B argc
  966. is one the breakpoint will fire.
  967. Beware that local variables may be stored in registers; see the
  968. BUGS section.
  969. .PP
  970. Debug process 127 on remote machine
  971. .BR kremvax :
  972. .IP
  973. .EX
  974. % import kremvax /proc
  975. % db 127
  976. $C
  977. .EE
  978. .SH FILES
  979. .B /proc/*/text
  980. .br
  981. .B /proc/*/mem
  982. .br
  983. .B /proc/*/ctl
  984. .br
  985. .B /proc/*/note
  986. .SH "SEE ALSO"
  987. .IR acid (1),
  988. .IR nm (1),
  989. .IR proc (3)
  990. .SH SOURCE
  991. .B /sys/src/cmd/db
  992. .SH DIAGNOSTICS
  993. Exit status is null, unless the last command failed or
  994. returned non-null status.
  995. .SH BUGS
  996. Examining a local variable with
  997. .I routine.name
  998. returns the contents of the memory allocated for the variable, but
  999. with optimization (suppressed by the
  1000. .B -N
  1001. compiler flag) variables often reside in registers.
  1002. Also, on some architectures, the first argument is always
  1003. passed in a register.
  1004. .PP
  1005. Variables and parameters that have been
  1006. optimized away do not appear in the
  1007. symbol table, returning the error
  1008. .IR "bad local variable"
  1009. when accessed by
  1010. .IR db .
  1011. .PP
  1012. Because of alignment incompatibilities, Motorola 68000
  1013. series machines can not be debugged remotely from a
  1014. processor of a different type.
  1015. .PP
  1016. Breakpoints should not be set on instructions scheduled
  1017. in delay slots. When a program stops on such a breakpoint,
  1018. it is usually impossible to continue its execution.