1
0

acid.html 70 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921
  1. <html>
  2. <title>
  3. data
  4. </title>
  5. <body BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#330088" ALINK="#FF0044">
  6. <H1>Acid Manual
  7. </H1>
  8. <DL><DD><I>Phil Winterbottom<br>
  9. philw@plan9.bell-labs.com<br>
  10. </I></DL>
  11. <H4>Introduction
  12. </H4>
  13. <P>
  14. Acid is a general purpose, source level symbolic debugger.
  15. The debugger is built around a simple command language.
  16. The command language, distinct from the language of the program being debugged,
  17. provides a flexible user interface that allows the debugger
  18. interface to be customized for a specific application or architecture.
  19. Moreover, it provides an opportunity to write test and
  20. verification code independently of a program's source code.
  21. Acid is able to debug multiple
  22. processes provided they share a common set of symbols, such as the processes in
  23. a threaded program.
  24. </P>
  25. <P>
  26. Like other language-based solutions, Acid presents a poor user interface but
  27. provides a powerful debugging tool.
  28. Application of Acid to hard problems is best approached by writing functions off-line
  29. (perhaps loading them with the
  30. <TT>include</TT>
  31. function or using the support provided by
  32. <A href="/magic/man2html/1/acme"><I>acme</I>(1)),
  33. </A>rather than by trying to type intricate Acid operations
  34. at the interactive prompt.
  35. </P>
  36. <P>
  37. Acid allows the execution of a program to be controlled by operating on its
  38. state while it is stopped and by monitoring and controlling its execution
  39. when it is running. Each program action that causes a change
  40. of execution state is reflected by the execution
  41. of an Acid function, which may be user defined.
  42. A library of default functions provides the functionality of a normal debugger.
  43. </P>
  44. <P>
  45. A Plan 9 process is controlled by writing messages to a control file in the
  46. <A href="/magic/man2html/3/proc"><I>proc</I>(3)
  47. </A>file system. Each control message has a corresponding Acid function, which
  48. sends the message to the process. These functions take a process id
  49. (<I>pid</I>)
  50. as an
  51. argument. The memory and text file of the program may be manipulated using
  52. the indirection operators. The symbol table, including source cross reference,
  53. is available to an Acid program. The combination allows complex operations
  54. to be performed both in terms of control flow and data manipulation.
  55. </P>
  56. <H4>Input format and <TT>whatis</TT>
  57. </H4>
  58. <P>
  59. Comments start with
  60. <TT>//</TT>
  61. and continue to the end of the line.
  62. Input is a series of statements and expressions separated by semicolons.
  63. At the top level of the interpreter, the builtin function
  64. <TT>print</TT>
  65. is called automatically to display the result of all expressions except function calls.
  66. A unary
  67. <TT>+</TT>
  68. may be used as a shorthand to force the result of a function call to be printed.
  69. </P>
  70. <P>
  71. Also at the top level, newlines are treated as semicolons
  72. by the parser, so semicolons are unnecessary when evaluating expressions.
  73. </P>
  74. <P>
  75. When Acid starts, it loads the default program modules,
  76. enters interactive mode, and prints a prompt. In this state Acid accepts
  77. either function definitions or statements to be evaluated.
  78. In this interactive mode
  79. statements are evaluated immediately, while function definitions are
  80. stored for later invocation.
  81. </P>
  82. <P>
  83. The
  84. <TT>whatis</TT>
  85. operator can be used to report the state of identifiers known to the interpreter.
  86. With no argument,
  87. <TT>whatis</TT>
  88. reports the name of all defined Acid functions; when supplied with an identifier
  89. as an argument it reports any variable, function, or type definition
  90. associated with the identifier.
  91. Because of the way the interpreter handles semicolons,
  92. the result of a
  93. <TT>whatis</TT>
  94. statement can be returned directly to Acid without adding semicolons.
  95. A syntax error or interrupt returns Acid to the normal evaluation
  96. mode; any partially evaluated definitions are lost.
  97. </P>
  98. <H4>Using the Library Functions
  99. </H4>
  100. <P>
  101. After loading the program binary, Acid loads the portable and architecture-specific
  102. library functions that form the standard debugging environment.
  103. These files are Acid source code and are human-readable.
  104. The following example uses the standard debugging library to show how
  105. language and program interact:
  106. <DL><DT><DD><TT><PRE>
  107. % acid /bin/ls
  108. /bin/ls:mips plan 9 executable
  109. /sys/lib/acid/port
  110. /sys/lib/acid/mips
  111. acid: new()
  112. 75721: system call _main ADD <I>-0x14,R29
  113. 75721: breakpoint main+0x4 MOVW R31,0x0(R29)
  114. acid: bpset(ls)
  115. acid: cont()
  116. 75721: breakpoint ls ADD </I>-0x16c8,R29
  117. acid: stk()
  118. At pc:0x0000141c:ls /sys/src/cmd/ls.c:87
  119. ls(s=0x0000004d,multi=0x00000000) /sys/src/cmd/ls.c:87
  120. called from main+0xf4 /sys/src/cmd/ls.c:79
  121. main(argc=0x00000000,argv=0x7ffffff0) /sys/src/cmd/ls.c:48
  122. called from _main+0x20 /sys/src/libc/mips/main9.s:10
  123. acid: PC
  124. 0xc0000f60
  125. acid: *PC
  126. 0x0000141c
  127. acid: ls
  128. 0x0000141c
  129. </PRE></TT></DL>
  130. The function
  131. <TT>new()</TT>
  132. creates a new process and stops it at the first instruction.
  133. This change in state is reported by a call to the
  134. Acid function
  135. <TT>stopped</TT>,
  136. which is called by the interpreter whenever the debugged program stops.
  137. <TT>Stopped</TT>
  138. prints the status line giving the pid, the reason the program stopped
  139. and the address and instruction at the current PC.
  140. The function
  141. <TT>bpset</TT>
  142. makes an entry in the breakpoint table and plants a breakpoint in memory.
  143. The
  144. <TT>cont</TT>
  145. function continues the process, allowing it to run until some condition
  146. causes it to stop. In this case the program hits the breakpoint placed on
  147. the function
  148. <TT>ls</TT>
  149. in the C program. Once again the
  150. <TT>stopped</TT>
  151. routine is called to print the status of the program. The function
  152. <TT>stk</TT>
  153. prints a C stack trace of the current process. It is implemented using
  154. a builtin Acid function that returns the stack trace as a list; the code
  155. that formats the information is all written in Acid.
  156. The Acid variable
  157. <TT>PC</TT>
  158. holds the address of the
  159. cell where the current value of the processor register
  160. <TT>PC</TT>
  161. is stored. By indirecting through
  162. the value of
  163. <TT>PC</TT>
  164. the address where the program is stopped can be found.
  165. All of the processor registers are available by the same mechanism.
  166. </P>
  167. <H4>Types
  168. </H4>
  169. <P>
  170. An Acid variable has one of four types:
  171. <I>integer</I>,
  172. <I>float</I>,
  173. <I>list</I>,
  174. or
  175. <I>string</I>.
  176. The type of a variable is inferred from the type of the right-hand
  177. side of the assignment expression which last set its value.
  178. Referencing a variable that has not yet
  179. been assigned draws a "used but not set" error. Many of the operators may
  180. be applied to more than
  181. one type; for these operators the action of the operator is determined by
  182. the types of its operands. The action of each operator is defined in the
  183. <I>Expressions</I>
  184. section of this manual.
  185. </P>
  186. <H4>Variables
  187. </H4>
  188. <P>
  189. Acid has three kinds of variables: variables defined by the symbol table
  190. of the debugged program, variables that are defined and maintained
  191. by the interpreter as the debugged program changes state, and variables
  192. defined and used by Acid programs.
  193. </P>
  194. <P>
  195. Some examples of variables maintained by the interpreter are the register
  196. pointers listed by name in the Acid list variable
  197. <TT>registers</TT>,
  198. and the symbol table listed by name and contents in the Acid variable
  199. <TT>symbols</TT>.
  200. </P>
  201. <P>
  202. The variable
  203. <TT>pid</TT>
  204. is updated by the interpreter to select the most recently created process
  205. or the process selected by the
  206. <TT>setproc</TT>
  207. builtin function.
  208. </P>
  209. <H4>Formats
  210. </H4>
  211. <P>
  212. In addition to a type, variables have formats. The format is a code
  213. letter that determines the printing style and the effect of some of the
  214. operators on that variable. The format codes are derived from the format
  215. letters used by
  216. <A href="/magic/man2html/1/db"><I>db</I>(1).
  217. </A>By default, symbol table variables and numeric constants
  218. are assigned the format code
  219. <TT>X</TT>,
  220. which specifies 32-bit hexadecimal.
  221. Printing a variable with this code yields the output
  222. <TT>0x00123456</TT>.
  223. The format code of a variable may be changed from the default by using the
  224. builtin function
  225. <TT>fmt</TT>.
  226. This function takes two arguments, an expression and a format code. After
  227. the expression is evaluated the new format code is attached to the result
  228. and forms the return value from
  229. <TT>fmt</TT>.
  230. The backslash operator is a short form of
  231. <TT>fmt</TT>.
  232. The format supplied by the backslash operator must be the format character
  233. rather than an expression.
  234. If the result is assigned to a variable the new format code is maintained
  235. in the variable. For example:
  236. <DL><DT><DD><TT><PRE>
  237. acid: x=10
  238. acid: print(x)
  239. 0x0000000a
  240. acid: x = fmt(x, 'D')
  241. acid: print(x, fmt(x, 'X'))
  242. 10 0x0000000a
  243. acid: x
  244. 10
  245. acid: x\o
  246. 12
  247. </PRE></TT></DL>
  248. The supported format characters are:
  249. <DL><DD>
  250. </P>
  251. <DL COMPACT>
  252. <DT><TT>o</TT><DD>
  253. Print two-byte integer in octal.
  254. <DT><TT>O</TT><DD>
  255. Print four-byte integer in octal.
  256. <DT><TT>q</TT><DD>
  257. Print two-byte integer in signed octal.
  258. <DT><TT>Q</TT><DD>
  259. Print four-byte integer in signed octal.
  260. <DT><TT>B</TT><DD>
  261. Print four-byte integer in binary.
  262. <DT><TT>d</TT><DD>
  263. Print two-byte integer in signed decimal.
  264. <DT><TT>D</TT><DD>
  265. Print four-byte integer in signed decimal.
  266. <DT><TT>Y</TT><DD>
  267. Print eight-byte integer in signed decimal.
  268. <DT><TT>Z</TT><DD>
  269. Print eight-byte integer in unsigned decimal.
  270. <DT><TT>x</TT><DD>
  271. Print two-byte integer in hexadecimal.
  272. <DT><TT>X</TT><DD>
  273. Print four-byte integer in hexadecimal.
  274. <DT><TT>Y</TT><DD>
  275. Print eight-byte integer in hexadecimal.
  276. <DT><TT>u</TT><DD>
  277. Print two-byte integer in unsigned decimal.
  278. <DT><TT>U</TT><DD>
  279. Print four-byte integer in unsigned decimal.
  280. <DT><TT>f</TT><DD>
  281. Print single-precision floating point number.
  282. <DT><TT>F</TT><DD>
  283. Print double-precision floating point number.
  284. <DT><TT>g</TT><DD>
  285. Print a single precision floating point number in string format.
  286. <DT><TT>G</TT><DD>
  287. Print a double precision floating point number in string format.
  288. <DT><TT>b</TT><DD>
  289. Print byte in hexadecimal.
  290. <DT><TT>c</TT><DD>
  291. Print byte as an ASCII character.
  292. <DT><TT>C</TT><DD>
  293. Like
  294. <TT>c</TT>,
  295. with
  296. printable ASCII characters represented normally and
  297. others printed in the form <TT>\x</TT><I>nn</I>.
  298. <DT><TT>s</TT><DD>
  299. Interpret the addressed bytes as UTF characters
  300. and print successive characters until a zero byte is reached.
  301. <DT><TT>r</TT><DD>
  302. Print a two-byte integer as a rune.
  303. <DT><TT>R</TT><DD>
  304. Print successive two-byte integers as runes
  305. until a zero rune is reached.
  306. <DT><TT>i</TT><DD>
  307. Print as machine instructions.
  308. <DT><TT>I</TT><DD>
  309. As
  310. <TT>i</TT>
  311. above, but print the machine instructions in
  312. an alternate form if possible:
  313. <TT>sunsparc</TT>
  314. and
  315. <TT>mipsco</TT>
  316. reproduce the manufacturers' syntax.
  317. <DT><TT>a</TT><DD>
  318. Print the value in symbolic form.
  319. </DL>
  320. </dl>
  321. <H4>Complex types
  322. </H4>
  323. <P>
  324. Acid permits the definition of the layout of memory.
  325. The usual method is to use the
  326. <TT>-a</TT>
  327. flag of the compilers to produce Acid-language descriptions of data structures (see
  328. <A href="/magic/man2html/1/2c"><I>2c</I>(1))
  329. </A>although such definitions can be typed interactively.
  330. The keywords
  331. <TT>complex</TT>,
  332. <TT>adt</TT>,
  333. <TT>aggr</TT>,
  334. and
  335. <TT>union</TT>
  336. are all equivalent; the compiler uses the synonyms to document the declarations.
  337. A complex type is described as a set of members, each containing a format letter,
  338. an offset in the structure, and a name. For example, the C structure
  339. <DL><DT><DD><TT><PRE>
  340. struct List {
  341. int type;
  342. struct List *next;
  343. };
  344. </PRE></TT></DL>
  345. is described by the Acid statement
  346. <DL><DT><DD><TT><PRE>
  347. complex List {
  348. 'D' 0 type;
  349. 'X' 4 next;
  350. };
  351. </PRE></TT></DL>
  352. </P>
  353. <H4>Scope
  354. </H4>
  355. <P>
  356. Variables are global unless they are either parameters to functions
  357. or are declared as
  358. <TT>local</TT>
  359. in a function body. Parameters and local variables are available only in
  360. the body of the function in which they are instantiated.
  361. Variables are dynamically bound: if a function declares a local variable
  362. with the same name as a global variable, the global variable will be hidden
  363. whenever the function is executing.
  364. For example, if a function
  365. <TT>f</TT>
  366. has a local called
  367. <TT>main</TT>,
  368. any function called below
  369. <TT>f</TT>
  370. will see the local version of
  371. <TT>main</TT>,
  372. not the external symbol.
  373. </P>
  374. <H4>Addressing
  375. </H4>
  376. <P>
  377. Since the symbol table specifies addresses,
  378. to access the value of program variables
  379. an extra level of indirection
  380. is required relative to the source code.
  381. For consistency, the registers are maintained as pointers as well; Acid variables with the names
  382. of processor registers point to cells holding the saved registers.
  383. </P>
  384. <P>
  385. The location in a file or memory image associated with
  386. an address is calculated from a map
  387. associated with the file.
  388. Each map contains one or more quadruples (<I>t</I>,
  389. <I>b</I>,
  390. <I>e</I>,
  391. <I>f</I>),
  392. defining a segment named
  393. <I>t</I>
  394. (usually
  395. <TT>text</TT>,
  396. <TT>data</TT>,
  397. <TT>regs</TT>,
  398. or
  399. <TT>fpregs</TT>)
  400. mapping addresses in the range
  401. <I>b</I>
  402. through
  403. <I>e</I>
  404. to the part of the file
  405. beginning at
  406. offset
  407. <I>f</I>.
  408. The memory model of a Plan 9 process assumes
  409. that segments are disjoint. There
  410. can be more than one segment of a given type (e.g., a process
  411. may have more than one text segment) but segments
  412. may not overlap.
  413. An address
  414. <I>a</I>
  415. is translated
  416. to a file address
  417. by finding a segment
  418. for which
  419. <I>b</I>
  420. +
  421. <I>a</I>
  422. &lt;
  423. <I>e</I>;
  424. the location in the file
  425. is then
  426. <I>address</I>
  427. +
  428. <I>f</I>
  429. -
  430. <I>b</I>.
  431. </P>
  432. <P>
  433. Usually,
  434. the text and initialized data of a program
  435. are mapped by segments called
  436. <TT>text</TT>
  437. and
  438. <TT>data</TT>.
  439. Since a program file does not contain bss, stack, or register data,
  440. these data are
  441. not mapped by the data segment.
  442. The text segment is mapped similarly in the memory image of
  443. a normal (i.e., non-kernel) process.
  444. However, the segment called
  445. <TT>*data</TT>
  446. maps memory from the beginning to the end of the program's data space.
  447. This region contains the program's static data, the bss, the
  448. heap and the stack. A segment
  449. called
  450. <TT>*regs</TT>
  451. maps the registers;
  452. <TT>*fpregs</TT>
  453. maps the floating point registers.
  454. </P>
  455. <P>
  456. Sometimes it is useful to define a map with a single segment
  457. mapping the region from 0 to 0xFFFFFFFF; such a map
  458. allows the entire file to be examined
  459. without address translation. The builtin function
  460. <TT>map</TT>
  461. examines and modifies Acid's map for a process.
  462. </P>
  463. <H4>Name Conflicts
  464. </H4>
  465. <P>
  466. Name conflicts between keywords in the Acid language, symbols in the program,
  467. and previously defined functions are resolved when the interpreter starts up.
  468. Each name is made unique by prefixing enough
  469. <TT></TT><I></I><TT>
  470. characters to the front of the name to make it unique. Acid reports
  471. a list of each name change at startup. The report looks like this:
  472. <DL><DT><DD><TT><PRE>
  473. /bin/sam: mips plan 9 executable
  474. /lib/acid/port
  475. /lib/acid/mips
  476. Symbol renames:
  477. append=</TT>append T/0xa4e40
  478. acid:
  479. </PRE></TT></DL>
  480. The symbol
  481. <TT>append</TT>
  482. is both a keyword and a text symbol in the program. The message reports
  483. that the text symbol is now named
  484. <TT></TT><I>append</I><TT>.
  485. </P>
  486. </TT><H4>Expressions
  487. </H4>
  488. <P>
  489. Operators have the same
  490. binding and precedence as in C.
  491. For operators of equal precedence, expressions are evaluated from left to right.
  492. </P>
  493. <H4>Boolean expressions
  494. </H4>
  495. <P>
  496. If an expression is evaluated for a boolean condition the test
  497. performed depends on the type of the result. If the result is of
  498. <I>integer</I>
  499. or
  500. <I>floating</I>
  501. type the result is true if the value is non-zero. If the expression is a
  502. <I>list</I>
  503. the result is true if there are any members in the list.
  504. If the expression is a
  505. <I>string</I>
  506. the result is true if there are any characters in the string.
  507. <DL><DT><DD><TT><PRE>
  508. primary-expression:
  509. identifier
  510. identifier <TT>:</TT> identifier
  511. constant
  512. <TT>(</TT> expression <TT>)</TT>
  513. <TT>{</TT> elist <TT>}</TT>
  514. elist:
  515. expression
  516. elist , expression
  517. </PRE></TT></DL>
  518. An identifier may be any legal Acid variable. The colon operator returns the
  519. address of parameters or local variables in the current stack of a program.
  520. For example:
  521. <DL><DT><DD><TT><PRE>
  522. *main:argc
  523. </PRE></TT></DL>
  524. prints the number of arguments passed into main. Local variables and parameters
  525. can only be referenced after the frame has been established. It may be necessary to
  526. step a program over the first few instructions of a breakpointed function to properly set
  527. the frame.
  528. </P>
  529. <P>
  530. Constants follow the same lexical rules as C.
  531. A list of expressions delimited by braces forms a list constructor.
  532. A new list is produced by evaluating each expression when the constructor is executed.
  533. The empty list is formed from
  534. <TT>{}</TT>.
  535. <DL><DT><DD><TT><PRE>
  536. acid: x = 10
  537. acid: l = { 1, x, 2\D }
  538. acid: x = 20
  539. acid: l
  540. {0x00000001 , 0x0000000a , 2 }
  541. </PRE></TT></DL>
  542. </P>
  543. <H4>Lists
  544. </H4>
  545. <P>
  546. Several operators manipulate lists.
  547. <DL><DT><DD><TT><PRE>
  548. list-expression:
  549. primary-expression
  550. <TT>head</TT> primary-expression
  551. <TT>tail</TT> primary-expression
  552. <TT>append</TT> expression <TT>,</TT> primary-expression
  553. <TT>delete</TT> expression <TT>,</TT> primary-expression
  554. </PRE></TT></DL>
  555. The
  556. <I>primary-expression</I>
  557. for
  558. <TT>head</TT>
  559. and
  560. <TT>tail</TT>
  561. must yield a value of type
  562. <I>list</I>.
  563. If there are no elements in the list the value of
  564. <TT>head</TT>
  565. or
  566. <TT>tail</TT>
  567. will be the empty list. Otherwise
  568. <TT>head</TT>
  569. evaluates to the first element of the list and
  570. <TT>tail</TT>
  571. evaluates to the rest.
  572. <DL><DT><DD><TT><PRE>
  573. acid: head {}
  574. {}
  575. acid: head {1, 2, 3, 4}
  576. 0x00000001
  577. acid: tail {1, 2, 3, 4}
  578. {0x00000002 , 0x00000003 , 0x00000004 }
  579. </PRE></TT></DL>
  580. The first operand of
  581. <TT>append</TT>
  582. and
  583. <TT>delete</TT>
  584. must be an expression that yields a
  585. <I>list</I>.
  586. <TT>Append</TT>
  587. places the result of evaluating
  588. <I>primary-expression</I>
  589. at the end of the list.
  590. The
  591. <I>primary-expression</I>
  592. supplied to
  593. <TT>delete</TT>
  594. must evaluate to an integer;
  595. <TT>delete</TT>
  596. removes the
  597. <I>n</I>'th
  598. item from the list, where
  599. <I>n</I>
  600. is integral value of
  601. <I>primary-expression.</I>
  602. List indices are zero-based.
  603. <DL><DT><DD><TT><PRE>
  604. acid: append {1, 2}, 3
  605. {0x00000001 , 0x00000002 , 0x00000003 }
  606. acid: delete {1, 2, 3}, 1
  607. {0x00000001 , 0x00000003 }
  608. </PRE></TT></DL>
  609. </P>
  610. <P>
  611. Assigning a list to a variable copies a reference to the list; if a list variable
  612. is copied it still points at the same list. To copy a list, the elements must
  613. be copied piecewise using
  614. <TT>head</TT>
  615. and
  616. <TT>append</TT>.
  617. </P>
  618. <H4>Operators
  619. </H4>
  620. <P>
  621. <DL><DT><DD><TT><PRE>
  622. postfix-expression:
  623. list-expression
  624. postfix-expression <TT>[</TT> expression <TT>]</TT>
  625. postfix-expression <TT>(</TT> argument-list <TT>)</TT>
  626. postfix-expression <TT>.</TT> tag
  627. postfix-expression <TT>-&gt;</TT> tag
  628. postfix-expression <TT>++</TT>
  629. postfix-expression <TT>--</TT>
  630. argument-list:
  631. expression
  632. argument-list , expression
  633. </PRE></TT></DL>
  634. The
  635. <TT>[</TT>
  636. <I>expression</I>
  637. <TT>]</TT>
  638. operator performs indexing.
  639. The indexing expression must result in an expression of
  640. <I>integer</I>
  641. type, say
  642. <I>n</I>.
  643. The operation depends on the type of
  644. <I>postfix-expression</I>.
  645. If the
  646. <I>postfix-expression</I>
  647. yields an
  648. <I>integer</I>
  649. it is assumed to be the base address of an array in the memory image.
  650. The index offsets into this array; the size of the array members is
  651. determined by the format associated with the
  652. <I>postfix-expression</I>.
  653. If the
  654. <I>postfix-expression</I>
  655. yields a
  656. <I>string</I>
  657. the index operator fetches the
  658. <I>n</I>'th
  659. character
  660. of the string. If the index points beyond the end
  661. of the string, a zero is returned.
  662. If the
  663. <I>postfix-expression</I>
  664. yields a
  665. <I>list</I>
  666. then the indexing operation returns the
  667. <I>n</I>'th
  668. item of the list.
  669. If the list contains less than
  670. <I>n</I>
  671. items the empty list
  672. <TT>{}</TT>
  673. is returned.
  674. </P>
  675. <P>
  676. The
  677. <TT>++</TT>
  678. and
  679. <TT>--</TT>
  680. operators increment and decrement integer variables.
  681. The amount of increment or decrement depends on the format code. These postfix
  682. operators return the value of the variable before the increment or decrement
  683. has taken place.
  684. <DL><DT><DD><TT><PRE>
  685. unary-expression:
  686. postfix-expression
  687. <TT>++</TT> unary-expression
  688. <TT>--</TT> unary-expression
  689. unary-operator: one of
  690. <TT>*</TT> <TT>@</TT> <TT>+</TT> <TT>-</TT> ~ <TT>!</TT>
  691. </PRE></TT></DL>
  692. The operators
  693. <TT>*</TT>
  694. and
  695. <TT>@</TT>
  696. are the indirection operators.
  697. <TT>@</TT>
  698. references a value from the text file of the program being debugged.
  699. The size of the value depends on the format code. The
  700. <TT>*</TT>
  701. operator fetches a value from the memory image of a process. If either
  702. operator appears on the left-hand side of an assignment statement, either the file
  703. or memory will be written. The file can only be modified when Acid is invoked
  704. with the
  705. <TT>-w</TT>
  706. option.
  707. The prefix
  708. <TT>++</TT>
  709. and
  710. <TT>--</TT>
  711. operators perform the same operation as their postfix counterparts but
  712. return the value after the increment or decrement has been performed. Since the
  713. <TT>++</TT>
  714. and
  715. <TT>*</TT>
  716. operators fetch and increment the correct amount for the specified format,
  717. the following function prints correct machine instructions on a machine with
  718. variable length instructions, such as the 68020 or 386:
  719. <DL><DT><DD><TT><PRE>
  720. defn asm(addr)
  721. {
  722. addr = fmt(addr, 'i');
  723. loop 1, 10 do
  724. print(*addr++, "\n");
  725. }
  726. </PRE></TT></DL>
  727. The operators
  728. <TT>~</TT>
  729. and
  730. <TT>!</TT>
  731. perform bitwise and logical negation respectively. Their operands must be of
  732. <I>integer</I>
  733. type.
  734. <DL><DT><DD><TT><PRE>
  735. cast-expression:
  736. unary-expression
  737. unary-expression <TT>\</TT> format-char
  738. <TT>(</TT> complex-name <TT>)</TT> unary-expression
  739. </PRE></TT></DL>
  740. A unary expression may be preceded by a cast. The cast has the effect of
  741. associating the value of
  742. <I>unary-expression</I>
  743. with a complex type structure.
  744. The result may then be dereferenced using the
  745. <TT>.</TT>
  746. and
  747. <TT>-&gt;</TT>
  748. operators.
  749. </P>
  750. <P>
  751. An Acid variable may be associated with a complex type
  752. to enable accessing the type's members:
  753. <DL><DT><DD><TT><PRE>
  754. acid: complex List {
  755. 'D' 0 type;
  756. 'X' 4 next;
  757. };
  758. acid: complex List lhead
  759. acid: lhead.type
  760. 10
  761. acid: lhead = ((List)lhead).next
  762. acid: lhead.type
  763. -46
  764. </PRE></TT></DL>
  765. Note that the
  766. <TT>next</TT>
  767. field cannot be given a complex type automatically.
  768. </P>
  769. <P>
  770. When entered at the top level of the interpreter,
  771. an expression of complex type
  772. is treated specially.
  773. If the type is called
  774. <TT>T</TT>
  775. and an Acid function also called
  776. <TT>T</TT>
  777. exists,
  778. then that function will be called with the expression as its argument.
  779. The compiler options
  780. <TT>-a</TT>
  781. and
  782. <TT>-aa</TT>
  783. will generate Acid source code defining such complex types and functions; see
  784. <A href="/magic/man2html/1/2c"><I>2c</I>(1).
  785. </A></P>
  786. <P>
  787. A
  788. <I>unary-expression</I>
  789. may be qualified with a format specifier using the
  790. <TT>\</TT>
  791. operator. This has the same effect as passing the expression to the
  792. <TT>fmt</TT>
  793. builtin function.
  794. <DL><DT><DD><TT><PRE>
  795. multiplicative-expression:
  796. cast-expression
  797. multiplicative-expression <TT>*</TT> multiplicative-expression
  798. multiplicative-expression <TT>/</TT> multiplicative-expression
  799. multiplicative-expression <TT>%</TT> multiplicative-expression
  800. </PRE></TT></DL>
  801. These operate on
  802. <I>integer</I>
  803. and
  804. <I>float</I>
  805. types and perform the expected operations:
  806. <TT>*</TT>
  807. multiplication,
  808. <TT>/</TT>
  809. division,
  810. <TT>%</TT>
  811. modulus.
  812. <DL><DT><DD><TT><PRE>
  813. additive-expression:
  814. multiplicative-expression
  815. additive-expression <TT>+</TT> multiplicative-expression
  816. additive-expression <TT>-</TT> multiplicative-expression
  817. </PRE></TT></DL>
  818. These operators perform as expected for
  819. <I>integer</I>
  820. and
  821. <I>float</I>
  822. operands.
  823. Unlike in C,
  824. <TT>+</TT>
  825. and
  826. <TT>-</TT>
  827. do not scale the addition based on the format of the expression.
  828. This means that
  829. <TT>i=i+1</TT>
  830. will always add 1 but
  831. <TT>i++</TT>
  832. will add the size corresponding to the format stored with
  833. <TT>i</TT>.
  834. If both operands are of either
  835. <I>string</I>
  836. or
  837. <I>list</I>
  838. type then addition is defined as concatenation. Subtraction is undefined for
  839. these two types.
  840. <DL><DT><DD><TT><PRE>
  841. shift-expression:
  842. additive-expression
  843. shift-expression <TT>&lt;&lt;</TT> additive-expression
  844. shift-expression <TT>&gt;&gt;</TT> additive-expression
  845. </PRE></TT></DL>
  846. The
  847. <TT>&gt;&gt;</TT>
  848. and
  849. <TT>&lt;&lt;</TT>
  850. operators perform bitwise right and left shifts respectively. Both
  851. require operands of
  852. <I>integer</I>
  853. type.
  854. <DL><DT><DD><TT><PRE>
  855. relational-expression:
  856. relational-expression <TT>&lt;</TT> shift-expression
  857. relational-expression <TT>&gt;</TT> shift-expression
  858. relational-expression <TT>&lt;=</TT> shift-expression
  859. relational-expression <TT>&gt;=</TT> shift-expression
  860. equality-expression:
  861. relational-expression
  862. relational-expression <TT>==</TT> equality-expression
  863. relational-expression <TT>!=</TT> equality-expression
  864. </PRE></TT></DL>
  865. The comparison operators are
  866. <TT>&lt;</TT>
  867. (less than),
  868. <TT>&gt;</TT>
  869. (greater than),
  870. <TT>&lt;=</TT>
  871. (less than or equal to),
  872. <TT>&gt;=</TT>
  873. (greater than or equal to),
  874. <TT>==</TT>
  875. (equal to) and
  876. <TT>!=</TT>
  877. (not equal to). The result of a comparison is 0
  878. if the condition is false, otherwise 1. The relational operators can only be
  879. applied to operands of
  880. <I>integer</I>
  881. and
  882. <I>float</I>
  883. type. The equality operators apply to all types. Comparing mixed types is legal.
  884. Mixed integer and float compare on the integral value. Other mixtures are always unequal.
  885. Two lists are equal if they
  886. have the same number of members and a pairwise comparison of the members results
  887. in equality.
  888. <DL><DT><DD><TT><PRE>
  889. AND-expression:
  890. equality-expression
  891. AND-expression <TT>&amp;</TT> equality-expression
  892. XOR-expression:
  893. AND-expression
  894. XOR-expression <TT>^</TT> AND-expression
  895. OR-expression:
  896. XOR-expression
  897. OR-expression <TT>|</TT> XOR-expression
  898. </PRE></TT></DL>
  899. These operators perform bitwise logical operations and apply only to the
  900. <I>integer</I>
  901. type.
  902. The operators are
  903. <TT>&</TT>
  904. (logical and),
  905. <TT>^</TT>
  906. (exclusive or) and
  907. <TT>|</TT>
  908. (inclusive or).
  909. <DL><DT><DD><TT><PRE>
  910. logical-AND-expression:
  911. OR-expression
  912. logical-AND-expression <TT>&amp;&amp;</TT> OR-expression
  913. logical-OR-expression:
  914. logical-AND-expression
  915. logical-OR-expression <TT>||</TT> logical-AND-expression
  916. </PRE></TT></DL>
  917. The
  918. <TT>&&</TT>
  919. operator returns 1 if both of its operands evaluate to boolean true, otherwise 0.
  920. The
  921. <TT>||</TT>
  922. operator returns 1 if either of its operands evaluates to boolean true,
  923. otherwise 0.
  924. </P>
  925. <H4>Statements
  926. </H4>
  927. <P>
  928. <DL><DT><DD><TT><PRE>
  929. <TT>if</TT> expression <TT>then</TT> statement <TT>else</TT> statement
  930. <TT>if</TT> expression <TT>then</TT> statement
  931. </PRE></TT></DL>
  932. The
  933. <I>expression</I>
  934. is evaluated as a boolean. If its value is true the statement after
  935. the
  936. <TT>then</TT>
  937. is executed, otherwise the statement after the
  938. <TT>else</TT>
  939. is executed. The
  940. <TT>else</TT>
  941. portion may be omitted.
  942. <DL><DT><DD><TT><PRE>
  943. <TT>while</TT> expression <TT>do</TT> statement
  944. </PRE></TT></DL>
  945. In a while loop, the
  946. <I>statement</I>
  947. is executed while the boolean
  948. <I>expression</I>
  949. evaluates
  950. true.
  951. <DL><DT><DD><TT><PRE>
  952. <TT>loop</TT> startexpr, endexpr <TT>do</TT> statement
  953. </PRE></TT></DL>
  954. The two expressions
  955. <I>startexpr</I>
  956. and
  957. <I>endexpr</I>
  958. are evaluated prior to loop entry.
  959. <I>Statement</I>
  960. is evaluated while the value of
  961. <I>startexpr</I>
  962. is less than or equal to
  963. <I>endexpr</I>.
  964. Both expressions must yield
  965. <I>integer</I>
  966. values. The value of
  967. <I>startexpr</I>
  968. is
  969. incremented by one for each loop iteration.
  970. Note that there is no explicit loop variable; the
  971. <I>expressions</I>
  972. are just values.
  973. <DL><DT><DD><TT><PRE>
  974. <TT>return</TT> expression
  975. </PRE></TT></DL>
  976. <TT>return</TT>
  977. terminates execution of the current function and returns to its caller.
  978. The value of the function is given by expression. Since
  979. <TT>return</TT>
  980. requires an argument, nil-valued functions should return the empty list
  981. <TT>{}</TT>.
  982. <DL><DT><DD><TT><PRE>
  983. <TT>local</TT> variable
  984. </PRE></TT></DL>
  985. The
  986. <TT>local</TT>
  987. statement creates a local instance of
  988. <I>variable</I>,
  989. which exists for the duration
  990. of the instance of the function in which it is declared. Binding is dynamic: the local variable,
  991. rather than the previous value of
  992. <I>variable</I>,
  993. is visible to called functions.
  994. After a return from the current function the previous value of
  995. <I>variable</I>
  996. is
  997. restored.
  998. </P>
  999. <P>
  1000. If Acid is interrupted, the values of all local variables are lost,
  1001. as if the function returned.
  1002. <DL><DT><DD><TT><PRE>
  1003. <TT>defn</TT> function-name <TT>(</TT> parameter-list <TT>)</TT> body
  1004. parameter-list:
  1005. variable
  1006. parameter-list , variable
  1007. body:
  1008. <TT>{</TT> statement <TT>}</TT>
  1009. </PRE></TT></DL>
  1010. Functions are introduced by the
  1011. <TT>defn</TT>
  1012. statement. The definition of parameter names suppresses any variables
  1013. of the same name until the function returns. The body of a function is a list
  1014. of statements enclosed by braces.
  1015. </P>
  1016. <H4>Code variables
  1017. </H4>
  1018. <P>
  1019. Acid permits the delayed evaluation of a parameter to a function. The parameter
  1020. may then be evaluated at any time with the
  1021. <TT>eval</TT>
  1022. operator. Such parameters are called
  1023. <I>code variables</I>
  1024. and are defined by prefixing their name with an asterisk in their declaration.
  1025. </P>
  1026. <P>
  1027. For example, this function wraps up an expression for later evaluation:
  1028. <DL><DT><DD><TT><PRE>
  1029. acid: defn code(*e) { return e; }
  1030. acid: x = code(v+atoi("100")\D)
  1031. acid: print(x)
  1032. (v+atoi("100"))\D;
  1033. acid: eval x
  1034. &lt;stdin&gt;:5: (error) v used but not set
  1035. acid: v=5
  1036. acid: eval x
  1037. 105
  1038. </PRE></TT></DL>
  1039. </P>
  1040. <H4>Source Code Management
  1041. </H4>
  1042. <P>
  1043. Acid provides the means to examine source code. Source code is
  1044. represented by lists of strings. Builtin functions provide mapping
  1045. from address to lines and vice-versa. The default debugging environment
  1046. has the means to load and display source files.
  1047. </P>
  1048. <H4>Builtin Functions
  1049. </H4>
  1050. <P>
  1051. The Acid interpreter has a number of builtin functions, which cannot be redefined.
  1052. These functions perform machine- or operating system-specific functions such as
  1053. symbol table and process management.
  1054. The following section presents a description of each builtin function.
  1055. The notation
  1056. <TT>{}</TT>
  1057. is used to denote the empty list, which is the default value of a function that
  1058. does not execute a
  1059. <TT>return</TT>
  1060. statement.
  1061. The type and number of parameters for each function are specified in the
  1062. description; where a parameter can be of any type it is specified as type
  1063. <I>item</I>.
  1064. </P>
  1065. <br>&#32;<br>
  1066. <DL>
  1067. <DT><DT>&#32;<DD>
  1068. <TT>Access</TT>
  1069. returns the integer 1 if the file name in
  1070. <I>string</I>
  1071. can be read by the builtin functions
  1072. <TT>file</TT>,
  1073. <TT>readfile</TT>,
  1074. or
  1075. <TT>include</TT>,
  1076. otherwise 0. A typical use of this function is to follow
  1077. a search path looking for a source file; it is used by
  1078. <TT>findsrc</TT>.
  1079. <DT><DT>&#32;<DD>
  1080. <DL><DT><DD><TT><PRE>
  1081. <br>
  1082. if access("main.c") then
  1083. return file("main.c");
  1084. </PRE></TT></DL>
  1085. <br>
  1086. </dl>
  1087. <br>&#32;<br>
  1088. <DL>
  1089. <DT><DT>&#32;<DD>
  1090. <TT>atof</TT>
  1091. converts the string supplied as its argument into a floating point
  1092. number. The function accepts strings in the same format as the C
  1093. function of the same name. The value returned has the format code
  1094. <TT>f</TT>.
  1095. <TT>atof</TT>
  1096. returns the value 0.0 if it is unable to perform the conversion.
  1097. <DT><DT>&#32;<DD>
  1098. <DL><DT><DD><TT><PRE>
  1099. <br>
  1100. acid: +atof("10.4e6")
  1101. 1.04e+07
  1102. </PRE></TT></DL>
  1103. <br>
  1104. </dl>
  1105. <br>&#32;<br>
  1106. <DL>
  1107. <DT><DT>&#32;<DD>
  1108. <TT>atoi</TT>
  1109. converts the argument
  1110. to an integer value.
  1111. The function accepts strings in the same format as the C function of the
  1112. same name. The value returned has the format code
  1113. <TT>D</TT>.
  1114. <TT>atoi</TT>
  1115. returns the integer 0 if it is unable to perform a conversion.
  1116. <DT><DT>&#32;<DD>
  1117. <DL><DT><DD><TT><PRE>
  1118. <br>
  1119. acid: +atoi("-1255")
  1120. -1255
  1121. </PRE></TT></DL>
  1122. <br>
  1123. </dl>
  1124. <br>&#32;<br>
  1125. <DL>
  1126. <DT><DT>&#32;<DD>
  1127. <TT>error</TT>
  1128. generates an error message and returns the interpreter to interactive
  1129. mode. If an Acid program is running, it is aborted.
  1130. Processes being debugged are not affected. The values of all local variables are lost.
  1131. <TT>error</TT>
  1132. is commonly used to stop the debugger when some interesting condition arises
  1133. in the debugged program.
  1134. <DT><DT>&#32;<DD>
  1135. <DL><DT><DD><TT><PRE>
  1136. <br>
  1137. while 1 do {
  1138. step();
  1139. if *main != @main then
  1140. error("memory corrupted");
  1141. }
  1142. </PRE></TT></DL>
  1143. <br>
  1144. </dl>
  1145. <br>&#32;<br>
  1146. <DL>
  1147. <DT><DT>&#32;<DD>
  1148. <TT>file</TT>
  1149. reads the contents of the file specified by
  1150. <I>string</I>
  1151. into a list.
  1152. Each element in the list is a string corresponding to a line in the file.
  1153. <TT>file</TT>
  1154. breaks lines at the newline character, but the newline
  1155. characters are not returned as part each string.
  1156. <TT>file</TT>
  1157. returns the empty list if it encounters an error opening or reading the data.
  1158. <DT><DT>&#32;<DD>
  1159. <DL><DT><DD><TT><PRE>
  1160. <br>
  1161. acid: print(file("main.c")[0])
  1162. #include &lt;u.h&gt;
  1163. </PRE></TT></DL>
  1164. <br>
  1165. </dl>
  1166. <br>&#32;<br>
  1167. <DL>
  1168. <DT><DT>&#32;<DD>
  1169. <TT>filepc</TT>
  1170. interprets its
  1171. <I>string</I>
  1172. argument as a source file address in the form of a file name and line offset.
  1173. <TT>filepc</TT>
  1174. uses the symbol table to map the source address into a text address
  1175. in the debugged program. The
  1176. <I>integer</I>
  1177. return value has the format
  1178. <TT>X</TT>.
  1179. <TT>filepc</TT>
  1180. returns an address of -1 if the source address is invalid.
  1181. The source file address uses the same format as
  1182. <A href="/magic/man2html/1/acme"><I>acme</I>(1).
  1183. </A>This function is commonly used to set breakpoints from the source text.
  1184. <DT><DT>&#32;<DD>
  1185. <DL><DT><DD><TT><PRE>
  1186. <br>
  1187. acid: bpset(filepc("main:10"))
  1188. acid: bptab()
  1189. 0x00001020 usage ADD -0xc,R29
  1190. </PRE></TT></DL>
  1191. <br>
  1192. </dl>
  1193. <br>&#32;<br>
  1194. <DL>
  1195. <DT><DT>&#32;<DD>
  1196. <TT>fmt</TT>
  1197. evaluates the expression
  1198. <I>item</I>
  1199. and sets the format of the result to
  1200. <I>fmt</I>.
  1201. The format of a value determines how it will be printed and
  1202. what kind of object will be fetched by the
  1203. <TT>*</TT>
  1204. and
  1205. <TT>@</TT>
  1206. operators. The
  1207. <TT>\</TT>
  1208. operator is a short-hand form of the
  1209. <TT>fmt</TT>
  1210. builtin function. The
  1211. <TT>fmt</TT>
  1212. function leaves the format of the
  1213. <I>item</I>
  1214. unchanged.
  1215. <DT><DT>&#32;<DD>
  1216. <DL><DT><DD><TT><PRE>
  1217. <br>
  1218. acid: main=fmt(main, 'i') // as instructions
  1219. acid: print(main\X, "\t", *main)
  1220. 0x00001020 ADD <I>-64,R29
  1221. </PRE></TT></DL>
  1222. </I><br>
  1223. </dl>
  1224. <br>&#32;<br>
  1225. <DL>
  1226. <DT><DT>&#32;<DD>
  1227. <TT>fnbound</TT>
  1228. interprets its
  1229. <I>integer</I>
  1230. argument as an address in the text of the debugged program.
  1231. <TT>fnbound</TT>
  1232. returns a list containing two integers corresponding to
  1233. the start and end addresses of the function containing the supplied address.
  1234. If the
  1235. <I>integer</I>
  1236. address is not in the text segment of the program then the empty list is returned.
  1237. <TT>fnbound</TT>
  1238. is used by
  1239. <TT>next</TT>
  1240. to detect stepping into new functions.
  1241. <DT><DT>&#32;<DD>
  1242. <DL><DT><DD><TT><PRE>
  1243. <br>
  1244. acid: print(fnbound(main))
  1245. {0x00001050, 0x000014b8}
  1246. </PRE></TT></DL>
  1247. <br>
  1248. </dl>
  1249. <br>&#32;<br>
  1250. <DL>
  1251. <DT><DT>&#32;<DD>
  1252. The follow set is defined as the set of program counter values that could result
  1253. from executing an instruction.
  1254. <TT>follow</TT>
  1255. interprets its
  1256. <I>integer</I>
  1257. argument as a text address, decodes the instruction at
  1258. that address and, with the current register set, builds a list of possible
  1259. next program counter values. If the instruction at the specified address
  1260. cannot be decoded
  1261. <TT>follow</TT>
  1262. raises an error.
  1263. <TT>follow</TT>
  1264. is used to plant breakpoints on
  1265. all potential paths of execution. The following code fragment
  1266. plants breakpoints on top of all potential following instructions.
  1267. <DT><DT>&#32;<DD>
  1268. <DL><DT><DD><TT><PRE>
  1269. <br>
  1270. lst = follow(*PC);
  1271. while lst do
  1272. {
  1273. *head lst = bpinst;
  1274. lst = tail lst;
  1275. }
  1276. </PRE></TT></DL>
  1277. <br>
  1278. </dl>
  1279. <br>&#32;<br>
  1280. <DL>
  1281. <DT><DT>&#32;<DD>
  1282. <TT>include</TT>
  1283. opens the file specified by
  1284. <I>string</I>
  1285. and uses its contents as command input to the interpreter.
  1286. The interpreter restores input to its previous source when it encounters
  1287. either an end of file or an error.
  1288. <TT>include</TT>
  1289. can be used to incrementally load symbol table information without
  1290. leaving the interpreter.
  1291. <DT><DT>&#32;<DD>
  1292. <DL><DT><DD><TT><PRE>
  1293. <br>
  1294. acid: include("/sys/src/cmd/acme/syms")
  1295. </PRE></TT></DL>
  1296. <br>
  1297. </dl>
  1298. <br>&#32;<br>
  1299. <DL>
  1300. <DT><DT>&#32;<DD>
  1301. <TT>interpret</TT>
  1302. evaluates the
  1303. <I>string</I>
  1304. expression and uses its result as command input for the interpreter.
  1305. The interpreter restores input to its previous source when it encounters
  1306. either the end of string or an error. The
  1307. <TT>interpret</TT>
  1308. function allows Acid programs to write Acid code for later evaluation.
  1309. <DT><DT>&#32;<DD>
  1310. <DL><DT><DD><TT><PRE>
  1311. <br>
  1312. acid: interpret("main+10;")
  1313. 0x0000102a
  1314. </PRE></TT></DL>
  1315. <br>
  1316. </dl>
  1317. <br>&#32;<br>
  1318. <DL>
  1319. <DT><DT>&#32;<DD>
  1320. <TT>itoa</TT>
  1321. takes an integer argument and converts it into an ASCII string
  1322. in the
  1323. <TT>D</TT>
  1324. format.
  1325. an alternate format string
  1326. may be provided in the
  1327. <TT>%</TT>
  1328. style of
  1329. <A href="/magic/man2html/2/print"><I>print</I>(2).
  1330. </A>This function is commonly used to build
  1331. <TT>rc</TT>
  1332. command lines.
  1333. <DT><DT>&#32;<DD>
  1334. <DL><DT><DD><TT><PRE>
  1335. <br>
  1336. acid: rc("cat /proc/"+itoa(pid)+"/segment")
  1337. Stack 7fc00000 80000000 1
  1338. Data 00001000 00009000 1
  1339. Data 00009000 0000a000 1
  1340. Bss 0000a000 0000c000 1
  1341. </PRE></TT></DL>
  1342. <br>
  1343. </dl>
  1344. <br>&#32;<br>
  1345. <DL>
  1346. <DT><DT>&#32;<DD>
  1347. <TT>kill</TT>
  1348. writes a kill control message into the control file of the process
  1349. specified by the
  1350. <I>integer</I>
  1351. pid.
  1352. If the process was previously installed by
  1353. <TT>setproc</TT>
  1354. it will be removed from the list of active processes.
  1355. If the
  1356. <I>integer</I>
  1357. has the same value as
  1358. <TT>pid</TT>,
  1359. then
  1360. <TT>pid</TT>
  1361. will be set to 0.
  1362. To continue debugging, a new process must be selected using
  1363. <TT>setproc</TT>.
  1364. For example, to kill all the active processes:
  1365. <DT><DT>&#32;<DD>
  1366. <DL><DT><DD><TT><PRE>
  1367. <br>
  1368. while proclist do {
  1369. kill(head proclist);
  1370. proclist = tail proclist;
  1371. }
  1372. </PRE></TT></DL>
  1373. <br>
  1374. </dl>
  1375. <br>&#32;<br>
  1376. <DL>
  1377. <DT><DT>&#32;<DD>
  1378. <TT>map</TT>
  1379. either retrieves all the mappings associated with a process or sets a single
  1380. map entry to a new value.
  1381. If the
  1382. <I>list</I>
  1383. argument is omitted then
  1384. <TT>map</TT>
  1385. returns a list of lists. Each sublist has four values and describes a
  1386. single region of contiguous addresses in the
  1387. memory or file image of the debugged program. The first entry is the name of the
  1388. mapping. If the name begins with
  1389. <TT>*</TT>
  1390. it denotes a map into the memory of an active process.
  1391. The second and third values specify the base and end
  1392. address of the region and the fourth number specifies the offset in the file
  1393. corresponding to the first location of the region.
  1394. A map entry may be set by supplying a list in the same format as the sublist
  1395. described above. The name of the mapping must match a region already defined
  1396. by the current map.
  1397. Maps are set automatically for Plan 9 processes and some kernels; they may
  1398. need to be set by hand for other kernels and programs that run on bare hardware.
  1399. <DT><DT>&#32;<DD>
  1400. <DL><DT><DD><TT><PRE>
  1401. <br>
  1402. acid: map({"text", _start, end, 0x30})
  1403. </PRE></TT></DL>
  1404. <br>
  1405. </dl>
  1406. <br>&#32;<br>
  1407. <DL>
  1408. <DT><DT>&#32;<DD>
  1409. <TT>match</TT>
  1410. compares each item in
  1411. <I>list</I>
  1412. using the equality operator
  1413. <TT>==</TT>
  1414. with
  1415. <I>item</I>.
  1416. The
  1417. <I>item</I>
  1418. can be of any type. If the match succeeds the result is the integer index
  1419. of the matching value, otherwise -1.
  1420. <DT><DT>&#32;<DD>
  1421. <DL><DT><DD><TT><PRE>
  1422. <br>
  1423. acid: list={8,9,10,11}
  1424. acid: print(list[match(10, list)]\D)
  1425. 10
  1426. </PRE></TT></DL>
  1427. <br>
  1428. </dl>
  1429. <br>&#32;<br>
  1430. <DL>
  1431. <DT><DT>&#32;<DD>
  1432. <TT>newproc</TT>
  1433. starts a new process with an argument vector constructed from
  1434. <I>string</I>.
  1435. The argument vector excludes the name of the program to execute and
  1436. each argument in
  1437. <I>string</I>
  1438. must be space separated. A new process can accept no more
  1439. than 512 arguments. The internal variable
  1440. <TT>pid</TT>
  1441. is set to the pid of the newly created process. The new pid
  1442. is also appended to the list of active processes stored in the variable
  1443. <TT>proclist</TT>.
  1444. The new process is created then halted at the first instruction, causing
  1445. the debugger to call
  1446. <TT>stopped</TT>.
  1447. The library functions
  1448. <TT>new</TT>
  1449. and
  1450. <TT>win</TT>
  1451. should be used to start processes when using the standard debugging
  1452. environment.
  1453. <DT><DT>&#32;<DD>
  1454. <DL><DT><DD><TT><PRE>
  1455. <br>
  1456. acid: newproc("-l .")
  1457. 56720: system call _main ADD -0x14,R29
  1458. </PRE></TT></DL>
  1459. <br>
  1460. </dl>
  1461. <br>&#32;<br>
  1462. <DL>
  1463. <DT><DT>&#32;<DD>
  1464. <TT>pcfile</TT>
  1465. interprets its
  1466. <I>integer</I>
  1467. argument as a text address in the debugged program. The address and symbol table
  1468. are used to generate a string containing the name of the source file
  1469. corresponding to the text address. If the address does not lie within the
  1470. program the string
  1471. <TT>?file?</TT>
  1472. is returned.
  1473. <DT><DT>&#32;<DD>
  1474. <DL><DT><DD><TT><PRE>
  1475. <br>
  1476. acid: print("Now at ", pcfile(*PC), ":", pcline(*PC))
  1477. Now at ls.c:46
  1478. </PRE></TT></DL>
  1479. <br>
  1480. </dl>
  1481. <br>&#32;<br>
  1482. <DL>
  1483. <DT><DT>&#32;<DD>
  1484. <TT>pcline</TT>
  1485. interprets its
  1486. <I>integer</I>
  1487. argument as a text address in the debugged program. The address and symbol table
  1488. are used to generate an integer containing the line number in the source file
  1489. corresponding to the text address. If the address does not lie within the
  1490. program the integer 0 is returned.
  1491. <DT><DT>&#32;<DD>
  1492. <DL><DT><DD><TT><PRE>
  1493. <br>
  1494. acid: +file("main.c")[pcline(main)]
  1495. main(int argc, char *argv[])
  1496. </PRE></TT></DL>
  1497. <br>
  1498. </dl>
  1499. <br>&#32;<br>
  1500. <DL>
  1501. <DT><DT>&#32;<DD>
  1502. <TT>print</TT>
  1503. evaluates each
  1504. <I>item</I>
  1505. supplied in its argument list and prints it to standard output. Each
  1506. argument will be printed according to its associated format character.
  1507. When the interpreter is executing, output is buffered and flushed every
  1508. 5000 statements or when the interpreter returns to interactive mode.
  1509. <TT>print</TT>
  1510. accepts a maximum of 512 arguments.
  1511. <DT><DT>&#32;<DD>
  1512. <DL><DT><DD><TT><PRE>
  1513. <br>
  1514. acid: print(10, "decimal ", 10\D, "octal ", 10\o)
  1515. 0x0000000a decimal 10 octal 000000000012
  1516. acid: print({1, 2, 3})
  1517. {0x00000001 , 0x00000002 , 0x00000003 }
  1518. acid: print(main, main\a, "\t", @main\i)
  1519. 0x00001020 main ADD <I>-64,R29
  1520. </PRE></TT></DL>
  1521. </I><br>
  1522. </dl>
  1523. <br>&#32;<br>
  1524. <DL>
  1525. <DT><DT>&#32;<DD>
  1526. <TT>printto</TT>
  1527. offers a limited form of output redirection. The first
  1528. <I>string</I>
  1529. argument is used as the path name of a new file to create.
  1530. Each
  1531. <I>item</I>
  1532. is then evaluated and printed to the newly created file. When all items
  1533. have been printed the file is closed.
  1534. <TT>printto</TT>
  1535. accepts a maximum of 512 arguments.
  1536. <DT><DT>&#32;<DD>
  1537. <DL><DT><DD><TT><PRE>
  1538. <br>
  1539. acid: printto("/env/foo", "hello")
  1540. acid: rc("echo -n foo")
  1541. hello
  1542. </PRE></TT></DL>
  1543. <br>
  1544. </dl>
  1545. <br>&#32;<br>
  1546. <DL>
  1547. <DT><DT>&#32;<DD>
  1548. <TT>rc</TT>
  1549. evaluates
  1550. <I>string</I>
  1551. to form a shell command. A new command interpreter is started
  1552. to execute the command. The Acid interpreter blocks until the command
  1553. completes. The return value is the empty string
  1554. if the command succeeds, otherwise the exit status of the failed command.
  1555. <DT><DT>&#32;<DD>
  1556. <DL><DT><DD><TT><PRE>
  1557. <br>
  1558. acid: rc("B "+itoa(-pcline(addr))+" "+pcfile(addr));
  1559. </PRE></TT></DL>
  1560. <br>
  1561. </dl>
  1562. <br>&#32;<br>
  1563. <DL>
  1564. <DT><DT>&#32;<DD>
  1565. <TT>readfile</TT>
  1566. takes the contents of the file specified by
  1567. <I>string</I>
  1568. and returns its contents as a new string.
  1569. If
  1570. <TT>readfile</TT>
  1571. encounters a zero byte in the file, it terminates.
  1572. If
  1573. <TT>readfile</TT>
  1574. encounters an error opening or reading the file then the empty list
  1575. is returned.
  1576. <TT>readfile</TT>
  1577. can be used to read the contents of device files whose lines are not
  1578. terminated with newline characters.
  1579. <DT><DT>&#32;<DD>
  1580. <DL><DT><DD><TT><PRE>
  1581. <br>
  1582. acid: ""+readfile("/dev/label")
  1583. helix
  1584. </PRE></TT></DL>
  1585. <br>
  1586. </dl>
  1587. <br>&#32;<br>
  1588. <DL>
  1589. <DT><DT>&#32;<DD>
  1590. <TT>reason</TT>
  1591. uses machine-dependent information to generate a string explaining
  1592. why a process has stopped. The
  1593. <I>integer</I>
  1594. argument is the value of an architecture dependent status register,
  1595. for example
  1596. <TT>CAUSE</TT>
  1597. on the MIPS.
  1598. <DT><DT>&#32;<DD>
  1599. <DL><DT><DD><TT><PRE>
  1600. <br>
  1601. acid: print(reason(*CAUSE))
  1602. system call
  1603. </PRE></TT></DL>
  1604. <br>
  1605. </dl>
  1606. <br>&#32;<br>
  1607. <DL>
  1608. <DT><DT>&#32;<DD>
  1609. <TT>regexp</TT>
  1610. matches the
  1611. <I>pattern</I>
  1612. string supplied as its first argument with the
  1613. <I>string</I>
  1614. supplied as its second.
  1615. If the pattern matches the result is the value 1, otherwise 0.
  1616. <DT><DT>&#32;<DD>
  1617. <DL><DT><DD><TT><PRE>
  1618. <br>
  1619. acid: print(regexp(".*bar", "foobar"))
  1620. 1
  1621. </PRE></TT></DL>
  1622. <br>
  1623. </dl>
  1624. <br>&#32;<br>
  1625. <DL>
  1626. <DT><DT>&#32;<DD>
  1627. <TT>setproc</TT>
  1628. selects the default process used for memory and control operations. It effectively
  1629. shifts the focus of control between processes. The
  1630. <I>integer</I>
  1631. argument specifies the pid of the process to look at.
  1632. The variable
  1633. <TT>pid</TT>
  1634. is set to the pid of the selected process. If the process is being
  1635. selected for the first time its pid is added to the list of active
  1636. processes
  1637. <TT>proclist</TT>.
  1638. <DT><DT>&#32;<DD>
  1639. <DL><DT><DD><TT><PRE>
  1640. <br>
  1641. acid: setproc(68382)
  1642. acid: procs()
  1643. &gt;68382: Stopped at main+0x4 setproc(68382)
  1644. </PRE></TT></DL>
  1645. <br>
  1646. </dl>
  1647. <br>&#32;<br>
  1648. <DL>
  1649. <DT><DT>&#32;<DD>
  1650. <TT>start</TT>
  1651. writes a
  1652. <TT>start</TT>
  1653. message to the control file of the process specified by the pid
  1654. supplied as its
  1655. <I>integer</I>
  1656. argument.
  1657. <TT>start</TT>
  1658. draws an error if the process is not in the
  1659. <TT>Stopped</TT>
  1660. state.
  1661. <DT><DT>&#32;<DD>
  1662. <DL><DT><DD><TT><PRE>
  1663. <br>
  1664. acid: start(68382)
  1665. acid: procs()
  1666. &gt;68382: Running at main+0x4 setproc(68382)
  1667. </PRE></TT></DL>
  1668. <br>
  1669. </dl>
  1670. <br>&#32;<br>
  1671. <DL>
  1672. <DT><DT>&#32;<DD>
  1673. <TT>startstop</TT>
  1674. performs the same actions as a call to
  1675. <TT>start</TT>
  1676. followed by a call to
  1677. <TT>stop</TT>.
  1678. The
  1679. <I>integer</I>
  1680. argument specifies the pid of the process to control. The process
  1681. must be in the
  1682. <TT>Stopped</TT>
  1683. state.
  1684. Execution is restarted, the debugger then waits for the process to
  1685. return to the
  1686. <TT>Stopped</TT>
  1687. state. A process will stop if a startstop message has been written to its control
  1688. file and any of the following conditions becomes true: the process executes or returns from
  1689. a system call, the process generates a trap or the process receives a note.
  1690. <TT>startstop</TT>
  1691. is used to implement single stepping.
  1692. <DT><DT>&#32;<DD>
  1693. <DL><DT><DD><TT><PRE>
  1694. <br>
  1695. acid: startstop(pid)
  1696. 75374: breakpoint ls ADD <I>-0x16c8,R29
  1697. </PRE></TT></DL>
  1698. </I><br>
  1699. </dl>
  1700. <br>&#32;<br>
  1701. <DL>
  1702. <DT><DT>&#32;<DD>
  1703. <TT>status</TT>
  1704. uses the pid supplied by its
  1705. <I>integer</I>
  1706. argument to generate a string describing the state of the process.
  1707. The string corresponds to the state returned by the
  1708. sixth column of the
  1709. <A href="/magic/man2html/1/ps"><I>ps</I>(1)
  1710. </A>command.
  1711. A process must be in the
  1712. <TT>Stopped</TT>
  1713. state to modify its memory or registers.
  1714. <DT><DT>&#32;<DD>
  1715. <DL><DT><DD><TT><PRE>
  1716. <br>
  1717. acid: ""+status(pid)
  1718. Stopped
  1719. </PRE></TT></DL>
  1720. <br>
  1721. </dl>
  1722. <br>&#32;<br>
  1723. <DL>
  1724. <DT><DT>&#32;<DD>
  1725. <TT>stop</TT>
  1726. writes a
  1727. <TT>stop</TT>
  1728. message to the control file of the process specified by the
  1729. pid supplied as its
  1730. <I>integer</I>
  1731. argument.
  1732. The interpreter blocks until the debugged process enters the
  1733. <TT>Stopped</TT>
  1734. state.
  1735. A process will stop if a stop message has been written to its control
  1736. file and any of the following conditions becomes true: the process executes or returns from
  1737. a system call, the process generates a trap, the process is scheduled or the
  1738. process receives a note.
  1739. <TT>stop</TT>
  1740. is used to wait for a process to halt before planting a breakpoint since Plan 9
  1741. only allows a process's memory to be written while it is in the
  1742. <TT>Stopped</TT>
  1743. state.
  1744. <DT><DT>&#32;<DD>
  1745. <DL><DT><DD><TT><PRE>
  1746. <br>
  1747. defn bpset(addr) {
  1748. if (status(pid)!="Stopped") then {
  1749. print("Waiting...\n");
  1750. stop(pid);
  1751. }
  1752. ...
  1753. }
  1754. </PRE></TT></DL>
  1755. <br>
  1756. </dl>
  1757. <br>&#32;<br>
  1758. <DL>
  1759. <DT><DT>&#32;<DD>
  1760. <TT>strace</TT>
  1761. generates a list of lists corresponding to procedures called by the debugged
  1762. program. Each sublist describes a single stack frame in the active process.
  1763. The first element is an
  1764. <I>integer</I>
  1765. of format
  1766. <TT>X</TT>
  1767. specifying the address of the called function. The second element is the value
  1768. of the program counter when the function was called. The third and fourth elements
  1769. contain lists of parameter and automatic variables respectively.
  1770. Each element of these lists
  1771. contains a string with the name of the variable and an
  1772. <I>integer</I>
  1773. value of format
  1774. <TT>X</TT>
  1775. containing the current value of the variable.
  1776. The arguments to
  1777. <TT>strace</TT>
  1778. are the current value of the program counter, the current value of the
  1779. stack pointer, and the address of the link register. All three parameters
  1780. must be integers.
  1781. The setting of
  1782. <I>linkreg</I>
  1783. is architecture dependent. On the MIPS linkreg is set to the address of saved
  1784. <TT>R31</TT>,
  1785. on the SPARC to the address of saved
  1786. <TT>R15</TT>.
  1787. For the other architectures
  1788. <I>linkreg</I>
  1789. is not used, but must point to valid memory.
  1790. <DT><DT>&#32;<DD>
  1791. <DL><DT><DD><TT><PRE>
  1792. <br>
  1793. acid: print(strace(*PC, *SP, linkreg))
  1794. {{0x0000141c, 0xc0000f74,
  1795. {{"s", 0x0000004d}, {"multi", 0x00000000}},
  1796. {{"db", 0x00000000}, {"fd", 0x000010a4},
  1797. {"n", 0x00000001}, {"i", 0x00009824}}}}
  1798. </PRE></TT></DL>
  1799. <br>
  1800. </dl>
  1801. <br>&#32;<br>
  1802. <DL>
  1803. <DT><DT>&#32;<DD>
  1804. <TT>waitstop</TT>
  1805. writes a waitstop message to the control file of the process specified by the
  1806. pid supplied as its
  1807. <I>integer</I>
  1808. argument.
  1809. The interpreter will remain blocked until the debugged process enters the
  1810. <TT>Stopped</TT>
  1811. state.
  1812. A process will stop if a waitstop message has been written to its control
  1813. file and any of the following conditions becomes true: the process generates a trap
  1814. or receives a note. Unlike
  1815. <TT>stop</TT>,
  1816. the
  1817. <TT>waitstop</TT>
  1818. function is passive; it does not itself cause the program to stop.
  1819. <DT><DT>&#32;<DD>
  1820. <DL><DT><DD><TT><PRE>
  1821. <br>
  1822. acid: waitstop(pid)
  1823. 75374: breakpoint ls ADD -0x16c8,R29
  1824. </PRE></TT></DL>
  1825. <br>
  1826. </dl>
  1827. <H4>Library Functions
  1828. </H4>
  1829. <P>
  1830. A standard debugging environment is provided by modules automatically
  1831. loaded when
  1832. Acid is started.
  1833. These modules are located in the directory
  1834. <TT>/sys/lib/acid</TT>.
  1835. These functions may be overridden, personalized, or added to by code defined in
  1836. <TT></TT><I>home/lib/acid</I><TT>.
  1837. The implementation of these functions can be examined using the
  1838. </TT><TT>whatis</TT><TT>
  1839. operator and then modified during debugging sessions.
  1840. </P>
  1841. </TT><br>&#32;<br>
  1842. <DL>
  1843. <DT><DT>&#32;<DD>
  1844. <TT>Bsrc</TT>
  1845. interprets the
  1846. <I>integer</I>
  1847. argument as a text address. The text address is used to produce a pathname
  1848. and line number suitable for the
  1849. <TT>B</TT>
  1850. command
  1851. to send to the text editor
  1852. <A href="/magic/man2html/1/sam"><I>sam</I>(1)
  1853. </A>or
  1854. <A href="/magic/man2html/1/acme"><I>acme</I>(1).
  1855. </A><TT>Bsrc</TT>
  1856. builds an
  1857. <A href="/magic/man2html/1/rc"><I>rc</I>(1)
  1858. </A>command to invoke
  1859. <TT>B</TT>,
  1860. which either selects an existing source file or loads a new source file into the editor.
  1861. The line of source corresponding to the text address is then selected.
  1862. In the following example
  1863. <TT>stopped</TT>
  1864. is redefined so that the editor
  1865. follows and displays the source line currently being executed.
  1866. <DT><DT>&#32;<DD>
  1867. <DL><DT><DD><TT><PRE>
  1868. <br>
  1869. defn stopped(pid) {
  1870. pstop(pid);
  1871. Bsrc(*PC);
  1872. }
  1873. </PRE></TT></DL>
  1874. <br>
  1875. </dl>
  1876. <br>&#32;<br>
  1877. <DL>
  1878. <DT><DT>&#32;<DD>
  1879. For machines equipped with floating point,
  1880. <TT>Fpr</TT>
  1881. displays the contents of the floating point registers as double precision
  1882. values.
  1883. <DT><DT>&#32;<DD>
  1884. <DL><DT><DD><TT><PRE>
  1885. <br>
  1886. acid: Fpr()
  1887. F0 0. F2 0.
  1888. F4 0. F6 0.
  1889. F8 0. F10 0.
  1890. ...
  1891. </PRE></TT></DL>
  1892. <br>
  1893. </dl>
  1894. <br>&#32;<br>
  1895. <DL>
  1896. <DT><DT>&#32;<DD>
  1897. <TT>Ureg</TT>
  1898. interprets the integer passed as its first argument as the address of a
  1899. kernel
  1900. <TT>Ureg</TT>
  1901. structure. Each element of the structure is retrieved and printed.
  1902. The size and contents of the
  1903. <TT>Ureg</TT>
  1904. structure are architecture dependent.
  1905. This function can be used to decode the first argument passed to a
  1906. <A href="/magic/man2html/2/notify"><I>notify</I>(2)
  1907. </A>function after a process has received a note.
  1908. <DT><DT>&#32;<DD>
  1909. <DL><DT><DD><TT><PRE>
  1910. <br>
  1911. acid: Ureg(*notehandler:ur)
  1912. status 0x3000f000
  1913. pc 0x1020
  1914. sp 0x7ffffe00
  1915. cause 0x00004002
  1916. ...
  1917. </PRE></TT></DL>
  1918. <br>
  1919. </dl>
  1920. <br>&#32;<br>
  1921. <DL>
  1922. <DT><DT>&#32;<DD>
  1923. <TT>acidinit</TT>
  1924. is called by the interpreter after all
  1925. modules have been loaded at initialization time.
  1926. It is used to set up machine specific variables and the default source path.
  1927. <TT>acidinit</TT>
  1928. should not be called by user code.
  1929. </dl>
  1930. <br>&#32;<br>
  1931. <DL>
  1932. <DT><DT>&#32;<DD>
  1933. <TT>addsrcdir</TT>
  1934. interprets its string argument as a new directory
  1935. <TT>findsrc</TT>
  1936. should search when looking for source code files.
  1937. <TT>addsrcdir</TT>
  1938. draws an error if the directory is already in the source search path. The search
  1939. path may be examined by looking at the variable
  1940. <TT>srcpath</TT>.
  1941. <DT><DT>&#32;<DD>
  1942. <DL><DT><DD><TT><PRE>
  1943. <br>
  1944. acid: rc("9fs fornax")
  1945. acid: addsrcpath("/n/fornax/sys/src/cmd")
  1946. </PRE></TT></DL>
  1947. <br>
  1948. </dl>
  1949. <br>&#32;<br>
  1950. <DL>
  1951. <DT><DT>&#32;<DD>
  1952. <TT>asm</TT>
  1953. interprets its integer argument as a text address from which to disassemble
  1954. machine instructions.
  1955. <TT>asm</TT>
  1956. prints the instruction address in symbolic and hexadecimal form, then prints
  1957. the instructions with addressing modes. Up to twenty instructions will
  1958. be disassembled.
  1959. <TT>asm</TT>
  1960. stops disassembling when it reaches the end of the current function.
  1961. Instructions are read from the file image using the
  1962. <TT>@</TT>
  1963. operator.
  1964. <DT><DT>&#32;<DD>
  1965. <DL><DT><DD><TT><PRE>
  1966. <br>
  1967. acid: asm(main)
  1968. main 0x00001020 ADD -0x64,R29
  1969. main+0x4 0x00001024 MOVW R31,0x0(R29)
  1970. main+0x8 0x00001028 MOVW R1,argc+4(FP)
  1971. main+0xc 0x0000102c MOVW <I>bin(SB),R1
  1972. </PRE></TT></DL>
  1973. </I><br>
  1974. </dl>
  1975. <br>&#32;<br>
  1976. <DL>
  1977. <DT><DT>&#32;<DD>
  1978. <TT>bpdel</TT>
  1979. removes a previously set breakpoint from memory.
  1980. The
  1981. <I>integer</I>
  1982. supplied as its argument must be the address of a previously set breakpoint.
  1983. The breakpoint address is deleted from the active breakpoint list
  1984. <TT>bplist</TT>,
  1985. then the original instruction is copied from the file image to the memory
  1986. image so that the breakpoint is removed.
  1987. <DT><DT>&#32;<DD>
  1988. <DL><DT><DD><TT><PRE>
  1989. <br>
  1990. acid: bpdel(main+4)
  1991. </PRE></TT></DL>
  1992. <br>
  1993. </dl>
  1994. <br>&#32;<br>
  1995. <DL>
  1996. <DT><DT>&#32;<DD>
  1997. <TT>bpset</TT>
  1998. places a breakpoint instruction at the address specified
  1999. by its
  2000. <I>integer</I>
  2001. argument, which must be in the text segment.
  2002. <TT>bpset</TT>
  2003. draws an error if a breakpoint has already been set at the specified address.
  2004. A list of current breakpoints is maintained in the variable
  2005. <TT>bplist</TT>.
  2006. Unlike in
  2007. <A href="/magic/man2html/1/db"><I>db</I>(1),
  2008. </A>breakpoints are left in memory even when a process is stopped, and
  2009. the process must exist, perhaps by being
  2010. created by either
  2011. <TT>new</TT>
  2012. or
  2013. <TT>win</TT>,
  2014. in order to place a breakpoint.
  2015. (<TT>Db</TT>
  2016. accepts breakpoint commands before the process is started.)
  2017. On the
  2018. MIPS and SPARC architectures,
  2019. breakpoints at function entry points should be set 4 bytes into the function
  2020. because the
  2021. instruction scheduler may fill
  2022. <TT>JAL</TT>
  2023. branch delay slots with the first instruction of the function.
  2024. <DT><DT>&#32;<DD>
  2025. <DL><DT><DD><TT><PRE>
  2026. <br>
  2027. acid: bpset(main+4)
  2028. </PRE></TT></DL>
  2029. <br>
  2030. </dl>
  2031. <br>&#32;<br>
  2032. <DL>
  2033. <DT><DT>&#32;<DD>
  2034. <TT>bptab</TT>
  2035. prints a list of currently installed breakpoints. The list contains the
  2036. breakpoint address in symbolic and hexadecimal form as well as the instruction
  2037. the breakpoint replaced. Breakpoints are not maintained across process creation
  2038. using
  2039. <TT>new</TT>
  2040. and
  2041. <TT>win</TT>.
  2042. They are maintained across a fork, but care must be taken to keep control of
  2043. the child process.
  2044. <DT><DT>&#32;<DD>
  2045. <DL><DT><DD><TT><PRE>
  2046. <br>
  2047. acid: bpset(ls+4)
  2048. acid: bptab()
  2049. 0x00001420 ls+0x4 MOVW R31,0x0(R29)
  2050. </PRE></TT></DL>
  2051. <br>
  2052. </dl>
  2053. <br>&#32;<br>
  2054. <DL>
  2055. <DT><DT>&#32;<DD>
  2056. <TT>casm</TT>
  2057. continues to disassemble instructions from where the last
  2058. <TT>asm</TT>
  2059. or
  2060. <TT>casm</TT>
  2061. command stopped. Like
  2062. <TT>asm</TT>,
  2063. this command stops disassembling at function boundaries.
  2064. <DT><DT>&#32;<DD>
  2065. <DL><DT><DD><TT><PRE>
  2066. <br>
  2067. acid: casm()
  2068. main+0x10 0x00001030 MOVW 0x1,R3
  2069. main+0x14 0x00001034 MOVW R3,0x8(R29)
  2070. main+0x18 0x00001038 MOVW <I>0x1,R5
  2071. main+0x1c 0x0000103c JAL Binit(SB)
  2072. </PRE></TT></DL>
  2073. </I><br>
  2074. </dl>
  2075. <br>&#32;<br>
  2076. <DL>
  2077. <DT><DT>&#32;<DD>
  2078. <TT>cont</TT>
  2079. restarts execution of the currently active process.
  2080. If the process is stopped on a breakpoint, the breakpoint is first removed,
  2081. the program is single stepped, the breakpoint is replaced and the program
  2082. is then set executing. This may cause
  2083. <TT>stopped()</TT>
  2084. to be called twice.
  2085. <TT>cont</TT>
  2086. causes the interpreter to block until the process enters the
  2087. <TT>Stopped</TT>
  2088. state.
  2089. <DT><DT>&#32;<DD>
  2090. <DL><DT><DD><TT><PRE>
  2091. <br>
  2092. acid: cont()
  2093. 95197: breakpoint ls+0x4 MOVW R31,0x0(R29)
  2094. </PRE></TT></DL>
  2095. <br>
  2096. </dl>
  2097. <br>&#32;<br>
  2098. <DL>
  2099. <DT><DT>&#32;<DD>
  2100. <TT>dump</TT>
  2101. interprets its first argument as an address, its second argument as a
  2102. count and its third as a format string.
  2103. <TT>dump</TT>
  2104. fetches an object from memory at the current address and prints it according
  2105. to the format. The address is incremented by the number of bytes specified by
  2106. the format and the process is repeated count times. The format string is any
  2107. combination of format characters, each preceded by an optional count.
  2108. For each object,
  2109. <TT>dump</TT>
  2110. prints the address in hexadecimal, a colon, the object and then a newline.
  2111. <TT>dump</TT>
  2112. uses
  2113. <TT>mem</TT>
  2114. to fetch each object.
  2115. <DT><DT>&#32;<DD>
  2116. <DL><DT><DD><TT><PRE>
  2117. <br>
  2118. acid: dump(main+35, 4, "X2bi")
  2119. 0x00001043: 0x0c8fa700 108 143 lwc2 r0,0x528f(R4)
  2120. 0x0000104d: 0xa9006811 0 0 swc3 r0,0x0(R24)
  2121. 0x00001057: 0x2724e800 4 37 ADD -0x51,R23,R31
  2122. 0x00001061: 0xa200688d 6 0 NOOP
  2123. 0x0000106b: 0x2710c000 7 0 BREAK
  2124. </PRE></TT></DL>
  2125. <br>
  2126. </dl>
  2127. <br>&#32;<br>
  2128. <DL>
  2129. <DT><DT>&#32;<DD>
  2130. <TT>findsrc</TT>
  2131. interprets its
  2132. <I>string</I>
  2133. argument as a source file. Each directory in the source path is searched
  2134. in turn for the file. If the file is found, the source text is loaded using
  2135. <TT>file</TT>
  2136. and stored in the list of active source files called
  2137. <TT>srctext</TT>.
  2138. The name of the file is added to the source file name list
  2139. <TT>srcfiles</TT>.
  2140. Users are unlikely to call
  2141. <TT>findsrc</TT>
  2142. from the command line, but may use it from scripts to preload source files
  2143. for a debugging session. This function is used by
  2144. <TT>src</TT>
  2145. and
  2146. <TT>line</TT>
  2147. to locate and load source code. The default search path for the MIPS
  2148. is
  2149. <TT>./</TT>,
  2150. <TT>/sys/src/libc/port</TT>,
  2151. <TT>/sys/src/libc/9sys</TT>,
  2152. <TT>/sys/src/libc/mips</TT>.
  2153. <DT><DT>&#32;<DD>
  2154. <DL><DT><DD><TT><PRE>
  2155. <br>
  2156. acid: findsrc(pcfile(main));
  2157. </PRE></TT></DL>
  2158. <br>
  2159. </dl>
  2160. <br>&#32;<br>
  2161. <DL>
  2162. <DT><DT>&#32;<DD>
  2163. For machines equipped with floating point,
  2164. <TT>fpr</TT>
  2165. displays the contents of the floating point registers as single precision
  2166. values. When the interpreter stores or manipulates floating point values
  2167. it converts into double precision values.
  2168. <DT><DT>&#32;<DD>
  2169. <DL><DT><DD><TT><PRE>
  2170. <br>
  2171. acid: fpr()
  2172. F0 0. F1 0.
  2173. F2 0. F3 0.
  2174. F4 0. F5 0.
  2175. ...
  2176. </PRE></TT></DL>
  2177. <br>
  2178. </dl>
  2179. <br>&#32;<br>
  2180. <DL>
  2181. <DT><DT>&#32;<DD>
  2182. <TT>func</TT>
  2183. single steps the active process until it leaves the current function
  2184. by either calling another function or returning to its caller.
  2185. <TT>func</TT>
  2186. will execute a single instruction after leaving the current function.
  2187. <DT><DT>&#32;<DD>
  2188. <DL><DT><DD><TT><PRE>
  2189. <br>
  2190. acid: func()
  2191. 95197: breakpoint ls+0x8 MOVW R1,R8
  2192. 95197: breakpoint ls+0xc MOVW R8,R1
  2193. 95197: breakpoint ls+0x10 MOVW R8,s+4(FP)
  2194. 95197: breakpoint ls+0x14 MOVW <I>0x2f,R5
  2195. 95197: breakpoint ls+0x18 JAL utfrrune(SB)
  2196. 95197: breakpoint utfrrune ADD </I>-0x18,R29
  2197. </PRE></TT></DL>
  2198. <br>
  2199. </dl>
  2200. <br>&#32;<br>
  2201. <DL>
  2202. <DT><DT>&#32;<DD>
  2203. <TT>gpr</TT>
  2204. prints the values of the general purpose processor registers.
  2205. <DT><DT>&#32;<DD>
  2206. <DL><DT><DD><TT><PRE>
  2207. <br>
  2208. acid: gpr()
  2209. R1 0x00009562 R2 0x000010a4 R3 0x00005d08
  2210. R4 0x0000000a R5 0x0000002f R6 0x00000008
  2211. ...
  2212. </PRE></TT></DL>
  2213. <br>
  2214. </dl>
  2215. <br>&#32;<br>
  2216. <DL>
  2217. <DT><DT>&#32;<DD>
  2218. <TT>labstk</TT>
  2219. performs a stack trace from a Plan 9
  2220. <I>label.</I>
  2221. The kernel,
  2222. C compilers store continuations in a common format. Since the
  2223. compilers all use caller save conventions a continuation may be saved by
  2224. storing a
  2225. <TT>PC</TT>
  2226. and
  2227. <TT>SP</TT>
  2228. pair. This data structure is called a label and is used by the
  2229. the C function
  2230. <TT>longjmp</TT>
  2231. and the kernel to schedule threads and processes.
  2232. <TT>labstk</TT>
  2233. interprets its
  2234. <I>integer</I>
  2235. argument as the address of a label and produces a stack trace for
  2236. the thread of execution. The value of the function
  2237. <TT>ALEF_tid</TT>
  2238. is a suitable argument for
  2239. <TT>labstk</TT>.
  2240. <DT><DT>&#32;<DD>
  2241. <DL><DT><DD><TT><PRE>
  2242. <br>
  2243. acid: labstk(*mousetid)
  2244. At pc:0x00021a70:Rendez_Sleep+0x178 rendez.l:44
  2245. Rendez_Sleep(r=0xcd7d8,bool=0xcd7e0,t=0x0) rendez.l:5
  2246. called from ALEF_rcvmem+0x198 recvmem.l:45
  2247. ALEF_rcvmem(c=0x000cd764,l=0x00000010) recvmem.l:6
  2248. ...
  2249. </PRE></TT></DL>
  2250. <br>
  2251. </dl>
  2252. <br>&#32;<br>
  2253. <DL>
  2254. <DT><DT>&#32;<DD>
  2255. <TT>lstk</TT>
  2256. produces a long format stack trace.
  2257. The stack trace includes each function in the stack,
  2258. where it was called from, and the value of the parameters and automatic
  2259. variables for each function.
  2260. <TT>lstk</TT>
  2261. displays the value rather than the address of each variable and all
  2262. variables are assumed to be an integer in format
  2263. <TT>X</TT>.
  2264. To print a variable in its correct format use the
  2265. <TT>:</TT>
  2266. operator to find the address and apply the appropriate format before indirection
  2267. with the
  2268. <TT>*</TT>
  2269. operator. It may be necessary to single step a couple of instructions into
  2270. a function to get a correct stack trace because the frame pointer adjustment
  2271. instruction may get scheduled down into the body of the function.
  2272. <DT><DT>&#32;<DD>
  2273. <DL><DT><DD><TT><PRE>
  2274. <br>
  2275. acid: lstk()
  2276. At pc:0x00001024:main+0x4 ls.c:48
  2277. main(argc=0x00000001,argv=0x7fffefec) ls.c:48
  2278. called from _main+0x20 main9.s:10
  2279. _argc=0x00000000
  2280. _args=0x00000000
  2281. fd=0x00000000
  2282. buf=0x00000000
  2283. i=0x00000000
  2284. </PRE></TT></DL>
  2285. <br>
  2286. </dl>
  2287. <br>&#32;<br>
  2288. <DL>
  2289. <DT><DT>&#32;<DD>
  2290. <TT>mem</TT>
  2291. interprets its first
  2292. <I>integer</I>
  2293. argument as the address of an object to be printed according to the
  2294. format supplied in its second
  2295. <I>string</I>
  2296. argument.
  2297. The format string can be any combination of format characters, each preceded
  2298. by an optional count.
  2299. <DT><DT>&#32;<DD>
  2300. <DL><DT><DD><TT><PRE>
  2301. <br>
  2302. acid: mem(bdata+0x326, "2c2Xb")
  2303. P = 0xa94bc464 0x3e5ae44d 19
  2304. </PRE></TT></DL>
  2305. <br>
  2306. </dl>
  2307. <br>&#32;<br>
  2308. <DL>
  2309. <DT><DT>&#32;<DD>
  2310. <TT>new</TT>
  2311. starts a new copy of the debugged program. The new program is started
  2312. with the program arguments set by the variable
  2313. <TT>progargs</TT>.
  2314. The new program is stopped in the second instruction of
  2315. <TT>main</TT>.
  2316. The breakpoint list is reinitialized.
  2317. <TT>new</TT>
  2318. may be used several times to instantiate several copies of a program
  2319. simultaneously. The user can rotate between the copies using
  2320. <TT>setproc</TT>.
  2321. <DT><DT>&#32;<DD>
  2322. <DL><DT><DD><TT><PRE>
  2323. <br>
  2324. acid: progargs="-l"
  2325. acid: new()
  2326. 60: external interrupt _main ADD <I>-0x14,R29
  2327. 60: breakpoint main+0x4 MOVW R31,0x0(R29)
  2328. </PRE></TT></DL>
  2329. </I><br>
  2330. </dl>
  2331. <br>&#32;<br>
  2332. <DL>
  2333. <DT><DT>&#32;<DD>
  2334. <TT>next</TT>
  2335. steps through a single language level statement without tracing down
  2336. through each statement in a called function. For each statement,
  2337. <TT>next</TT>
  2338. prints the machine instructions executed as part of the statement. After
  2339. the statement has executed, source lines around the current program
  2340. counter are displayed.
  2341. <DT><DT>&#32;<DD>
  2342. <DL><DT><DD><TT><PRE>
  2343. <br>
  2344. acid: next()
  2345. 60: breakpoint Binit+0x4 MOVW R31,0x0(R29)
  2346. 60: breakpoint Binit+0x8 MOVW f+8(FP),R4
  2347. binit.c:93
  2348. 88
  2349. 89 int
  2350. 90 Binit(Biobuf *bp, int f, int mode)
  2351. 91 {
  2352. &gt;92 return Binits(bp, f, mode, bp-&gt;b, BSIZE);
  2353. 93 }
  2354. </PRE></TT></DL>
  2355. <br>
  2356. </dl>
  2357. <br>&#32;<br>
  2358. <DL>
  2359. <DT><DT>&#32;<DD>
  2360. <TT>notestk</TT>
  2361. interprets its
  2362. <I>integer</I>
  2363. argument as the address of a
  2364. <TT>Ureg</TT>
  2365. structure passed by the kernel to a
  2366. <A href="/magic/man2html/2/notify"><I>notify</I>(2)
  2367. </A>function during note processing.
  2368. <TT>notestk</TT>
  2369. uses the
  2370. <TT>PC</TT>,
  2371. <TT>SP</TT>,
  2372. and link register from the
  2373. <TT>Ureg</TT>
  2374. to print a stack trace corresponding to the point in the program where the note
  2375. was received.
  2376. To get a valid stack trace on the MIPS and SPARC architectures from a notify
  2377. routine, the program must stop in a new function called from the notify routine
  2378. so that the link register is valid and the notify routine's parameters are
  2379. addressable.
  2380. <DT><DT>&#32;<DD>
  2381. <DL><DT><DD><TT><PRE>
  2382. <br>
  2383. acid: notestk(*notify:ur)
  2384. Note pc:0x00001024:main+0x4 ls.c:48
  2385. main(argc=0x00000001,argv=0x7fffefec) ls.c:48
  2386. called from _main+0x20 main9.s:10
  2387. _argc=0x00000000
  2388. _args=0x00000000
  2389. </PRE></TT></DL>
  2390. <br>
  2391. </dl>
  2392. <br>&#32;<br>
  2393. <DL>
  2394. <DT><DT>&#32;<DD>
  2395. <TT>pfl</TT>
  2396. interprets its argument as a text address and uses it to print
  2397. the source file and line number corresponding to the address. The output
  2398. has the same format as file addresses in
  2399. <A href="/magic/man2html/1/acme"><I>acme</I>(1).
  2400. </A><DT><DT>&#32;<DD>
  2401. <DL><DT><DD><TT><PRE>
  2402. <br>
  2403. acid: pfl(main)
  2404. ls.c:48
  2405. </PRE></TT></DL>
  2406. <br>
  2407. </dl>
  2408. <br>&#32;<br>
  2409. <DL>
  2410. <DT><DT>&#32;<DD>
  2411. <TT>procs</TT>
  2412. prints a list of active process attached to the debugger. Each process
  2413. produces a single line of output giving the pid, process state, the address
  2414. the process is currently executing, and the
  2415. <TT>setproc</TT>
  2416. command required to make that process current.
  2417. The current process is marked in the first column with a
  2418. <TT>&gt;</TT>
  2419. character. The debugger maintains a list of processes in the variable
  2420. <TT>proclist</TT>.
  2421. <DT><DT>&#32;<DD>
  2422. <DL><DT><DD><TT><PRE>
  2423. <br>
  2424. acid: procs()
  2425. &gt;62: Stopped at main+0x4 setproc(62)
  2426. 60: Stopped at Binit+0x8 setproc(60)
  2427. </PRE></TT></DL>
  2428. <br>
  2429. </dl>
  2430. <br>&#32;<br>
  2431. <DL>
  2432. <DT><DT>&#32;<DD>
  2433. <TT>pstop</TT>
  2434. prints the status of the process specified by the
  2435. <I>integer</I>
  2436. pid supplied as its argument.
  2437. <TT>pstop</TT>
  2438. is usually called from
  2439. <TT>stopped</TT>
  2440. every time a process enters the
  2441. <TT>Stopped</TT>
  2442. state.
  2443. <DT><DT>&#32;<DD>
  2444. <DL><DT><DD><TT><PRE>
  2445. <br>
  2446. acid: pstop(62)
  2447. 0x0000003e: breakpoint main+0x4 MOVW R31,0x0(R29)
  2448. </PRE></TT></DL>
  2449. <br>
  2450. </dl>
  2451. <br>&#32;<br>
  2452. <DL>
  2453. <DT><DT>&#32;<DD>
  2454. <TT>regs</TT>
  2455. prints the contents of both the general and special purpose registers.
  2456. <TT>regs</TT>
  2457. calls
  2458. <TT>spr</TT>
  2459. then
  2460. <TT>gpr</TT>
  2461. to display the contents of the registers.
  2462. </dl>
  2463. <br>&#32;<br>
  2464. <DL>
  2465. <DT><DT>&#32;<DD>
  2466. <TT>source</TT>
  2467. prints the directory search path followed by a list of currently loaded
  2468. source files. The source management functions
  2469. <TT>src</TT>
  2470. and
  2471. <TT>findsrc</TT>
  2472. use the search path to locate and load source files. Source files are
  2473. loaded incrementally into a source data base during debugging. A list
  2474. of loaded files is stored in the variable
  2475. <TT>srcfiles</TT>
  2476. and the contents of each source file in the variable
  2477. <TT>srctext</TT>.
  2478. <DT><DT>&#32;<DD>
  2479. <DL><DT><DD><TT><PRE>
  2480. <br>
  2481. acid: source()
  2482. /n/bootes/sys/src/libbio/
  2483. /sys/src/libc/port/
  2484. /sys/src/libc/9sys/
  2485. /sys/src/libc/mips/
  2486. binit.c
  2487. </PRE></TT></DL>
  2488. <br>
  2489. </dl>
  2490. <br>&#32;<br>
  2491. <DL>
  2492. <DT><DT>&#32;<DD>
  2493. <TT>spr</TT>
  2494. prints the contents of the processor control and memory management
  2495. registers. Where possible, the contents of the registers are decoded
  2496. to provide extra information; for example the
  2497. <TT>CAUSE</TT>
  2498. register on the MIPS is
  2499. printed both in hexadecimal and using the
  2500. <TT>reason</TT>
  2501. function.
  2502. <DT><DT>&#32;<DD>
  2503. <DL><DT><DD><TT><PRE>
  2504. <br>
  2505. acid: spr()
  2506. PC 0x00001024 main+0x4 ls.c:48
  2507. SP 0x7fffef68 LINK 0x00006264 _main+0x28 main9.s:12
  2508. STATUS 0x0000ff33 CAUSE 0x00000024 breakpoint
  2509. TLBVIR 0x000000d3 BADVADR 0x00001020
  2510. HI 0x00000004 LO 0x00001ff7
  2511. </PRE></TT></DL>
  2512. <br>
  2513. </dl>
  2514. <br>&#32;<br>
  2515. <DL>
  2516. <DT><DT>&#32;<DD>
  2517. <TT>src</TT>
  2518. interprets its
  2519. <I>integer</I>
  2520. argument as a text address and uses this address to print 5 lines
  2521. of source before and after the address. The current line is marked with a
  2522. <TT>&gt;</TT>
  2523. character.
  2524. <TT>src</TT>
  2525. uses the source search path maintained by
  2526. <TT>source</TT>
  2527. and
  2528. <TT>addsrcdir</TT>
  2529. to locate the required source files.
  2530. <DT><DT>&#32;<DD>
  2531. <DL><DT><DD><TT><PRE>
  2532. <br>
  2533. acid: src(*PC)
  2534. ls.c:47
  2535. 42 Biobuf bin;
  2536. 43
  2537. 44 #define HUNK 50
  2538. 45
  2539. 46 void
  2540. &gt;47 main(int argc, char *argv[])
  2541. 48 {
  2542. 49 int i, fd;
  2543. 50 char buf[64];
  2544. 51
  2545. 52 Binit(&amp;bin, 1, OWRITE);
  2546. </PRE></TT></DL>
  2547. <br>
  2548. </dl>
  2549. <br>&#32;<br>
  2550. <DL>
  2551. <DT><DT>&#32;<DD>
  2552. <TT>step</TT>
  2553. causes the debugged process to execute a single machine level instruction.
  2554. If the program is stopped on a breakpoint set by
  2555. <TT>bpset</TT>
  2556. it is first removed, the single step executed, and the breakpoint replaced.
  2557. <TT>step</TT>
  2558. uses
  2559. <TT>follow</TT>
  2560. to predict the address of the program counter after the current instruction
  2561. has been executed. A breakpoint is placed at each of these predicted addresses
  2562. and the process is started. When the process stops the breakpoints are removed.
  2563. <DT><DT>&#32;<DD>
  2564. <DL><DT><DD><TT><PRE>
  2565. <br>
  2566. acid: step()
  2567. 62: breakpoint main+0x8 MOVW R1,argc+4(FP)
  2568. </PRE></TT></DL>
  2569. <br>
  2570. </dl>
  2571. <br>&#32;<br>
  2572. <DL>
  2573. <DT><DT>&#32;<DD>
  2574. <TT>stk</TT>
  2575. produces a short format stack trace. The stack trace includes each function
  2576. in the stack, where it was called from, and the value of the parameters.
  2577. The short format omits the values of automatic variables.
  2578. Parameters are assumed to be integer values in the format
  2579. <TT>X</TT>;
  2580. to print a parameter in the correct format use the
  2581. <TT>:</TT>
  2582. to obtain its address, apply the correct format, and use the
  2583. <TT>*</TT>
  2584. indirection operator to find its value.
  2585. It may be necessary to single step a couple of instructions into
  2586. a function to get a correct stack trace because the frame pointer adjustment
  2587. instruction may get scheduled down into the body of the function.
  2588. <DT><DT>&#32;<DD>
  2589. <DL><DT><DD><TT><PRE>
  2590. <br>
  2591. acid: stk()
  2592. At pc:0x00001028:main+0x8 ls.c:48
  2593. main(argc=0x00000002,argv=0x7fffefe4) ls.c:48
  2594. called from _main+0x20 main9.s:10
  2595. </PRE></TT></DL>
  2596. <br>
  2597. </dl>
  2598. <br>&#32;<br>
  2599. <DL>
  2600. <DT><DT>&#32;<DD>
  2601. <TT>stmnt</TT>
  2602. executes a single language level statement.
  2603. <TT>stmnt</TT>
  2604. displays each machine level instruction as it is executed. When the executed
  2605. statement is completed the source for the next statement is displayed.
  2606. Unlike
  2607. <TT>next</TT>,
  2608. the
  2609. <TT>stmnt</TT>
  2610. function will trace down through function calls.
  2611. <DT><DT>&#32;<DD>
  2612. <DL><DT><DD><TT><PRE>
  2613. <br>
  2614. acid: stmnt()
  2615. 62: breakpoint main+0x18 MOVW R5,0xc(R29)
  2616. 62: breakpoint main+0x1c JAL Binit(SB)
  2617. 62: breakpoint Binit ADD -0x18,R29
  2618. binit.c:91
  2619. 89 int
  2620. 90 Binit(Biobuf *bp, int f, int mode)
  2621. &gt;91 {
  2622. </PRE></TT></DL>
  2623. <br>
  2624. </dl>
  2625. <br>&#32;<br>
  2626. <DL>
  2627. <DT><DT>&#32;<DD>
  2628. <TT>stopped</TT>
  2629. is called automatically by the interpreter
  2630. every time a process enters the
  2631. <TT>Stopped</TT>
  2632. state, such as when it hits a breakpoint.
  2633. The pid is passed as the
  2634. <I>integer</I>
  2635. argument. The default implementation just calls
  2636. <TT>pstop</TT>,
  2637. but the function may be changed to provide more information or perform fine control
  2638. of execution. Note that
  2639. <TT>stopped</TT>
  2640. should return; for example, calling
  2641. <TT>step</TT>
  2642. in
  2643. <TT>stopped</TT>
  2644. will recur until the interpreter runs out of stack space.
  2645. <DT><DT>&#32;<DD>
  2646. <DL><DT><DD><TT><PRE>
  2647. <br>
  2648. acid: defn stopped(pid) {
  2649. if *lflag != 0 then error("lflag modified");
  2650. }
  2651. acid: progargs = "-l"
  2652. acid: new();
  2653. acid: while 1 do step();
  2654. &lt;stdin&gt;:7: (error) lflag modified
  2655. acid: stk()
  2656. At pc:0x00001220:main+0x200 ls.c:54
  2657. main(argc=0x00000001,argv=0x7fffffe8) ls.c:48
  2658. called from _main+0x20 main9.s:10
  2659. </PRE></TT></DL>
  2660. <br>
  2661. </dl>
  2662. <br>&#32;<br>
  2663. <DL>
  2664. <DT><DT>&#32;<DD>
  2665. <TT>symbols</TT>
  2666. uses the regular expression supplied by
  2667. <I>string</I>
  2668. to search the symbol table for symbols whose name matches the
  2669. regular expression.
  2670. <DT><DT>&#32;<DD>
  2671. <DL><DT><DD><TT><PRE>
  2672. <br>
  2673. acid: symbols("main")
  2674. main T 0x00001020
  2675. _main T 0x0000623c
  2676. </PRE></TT></DL>
  2677. <br>
  2678. </dl>
  2679. <br>&#32;<br>
  2680. <DL>
  2681. <DT><DT>&#32;<DD>
  2682. <TT>win</TT>
  2683. performs exactly the same function as
  2684. <TT>new</TT>
  2685. but uses the window system to create a new window for the debugged process.
  2686. The variable
  2687. <TT>progargs</TT>
  2688. supplies arguments to the new process.
  2689. The environment variable
  2690. <TT></TT><I>8&#189;srv</I><TT>
  2691. must be set to allow the interpreter to locate the mount channel for the
  2692. window system.
  2693. The window is created in the top left corner of the screen and is
  2694. 400x600 pixels in size. The
  2695. </TT><TT>win</TT><TT>
  2696. function may be modified to alter the geometry.
  2697. The window system will not be able to deliver notes in the new window
  2698. since the pid of the created process is not passed when the server is
  2699. mounted to create a new window.
  2700. <DT><DT>&#32;<DD>
  2701. </TT><DL><DT><DD><TT><PRE>
  2702. <br>
  2703. acid: win()
  2704. </PRE></TT></DL>
  2705. <br>
  2706. </dl>
  2707. <br>&#32;<br>
  2708. <A href=http://www.lucent.com/copyright.html>
  2709. Copyright</A> &#169; 2004 Lucent Technologies Inc. All rights reserved.
  2710. </body></html>