home *** CD-ROM | disk | FTP | other *** search
/ Solo Programadores 21 / SOLOPROG21.iso / utillnux / info-htm / annotate.000 < prev    next >
Encoding:
Text File  |  1996-04-02  |  23.1 KB  |  746 lines
  1. <HTML>
  2. <HEAD>
  3. <!-- This HTML file has been created by TEXI.HTM 1.31
  4.      from /usr/src/devel/gdb-4.14/gdb/doc/annotate.texi on 9 June 1995 -->
  5.  
  6. <TITLE>GDB Annotations</TITLE>
  7. </HEAD>
  8. <BODY>
  9. <H1>GDB Annotations</H1>
  10. <P>
  11. Permission is granted to make and distribute verbatim copies of
  12. this manual provided the copyright notice and this permission notice
  13. are preserved on all copies.
  14. <P>
  15. Copyright (C) 1994 Free Software Foundation
  16. <P>
  17. <H1><A NAME="SEC1" HREF="ANNOTATE.HTM#SEC1">What is an Annotation?</A></H1>
  18. <P>
  19. To produce annotations, start GDB with the <CODE>--annotate=2</CODE> option.
  20. <P>
  21. Annotations start with a newline character, two <SAMP>`control-z'</SAMP>
  22. characters, and the name of the annotation.  If there is no additional
  23. information associated with this annotation, the name of the annotation
  24. is followed immediately by a newline.  If there is additional
  25. information, the name of the annotation is followed by a space, the
  26. additional information, and a newline.  The additional information
  27. cannot contain newline characters.
  28. <P>
  29. Any output not beginning with a newline and two <SAMP>`control-z'</SAMP>
  30. characters denotes literal output from GDB.  Currently there is no need
  31. for GDB to output a newline followed by two <SAMP>`control-z'</SAMP> characters,
  32. but if there was such a need, the annotations could be extended with an
  33. <SAMP>`escape'</SAMP> annotation which means those three characters as output.
  34. <P>
  35. A simple example of starting up GDB with annotations is:
  36. <P>
  37. <PRE>
  38. $ gdb --annotate=2
  39. GDB is free software and you are welcome to distribute copies of it
  40.  under certain conditions; type "show copying" to see the conditions.
  41. There is absolutely no warranty for GDB; type "show warranty" for details.
  42. GDB 4.12.3 (sparc-sun-sunos4.1.3), 
  43. Copyright 1994 Free Software Foundation, Inc.
  44.  
  45. ^Z^Zpre-prompt
  46. (gdb) 
  47. ^Z^Zprompt
  48. quit
  49.  
  50. ^Z^Zpost-prompt
  51. $ 
  52. </PRE>
  53. <P>
  54. Here <SAMP>`quit'</SAMP> is input to GDB; the rest is output from GDB.  The three
  55. lines beginning <SAMP>`^Z^Z'</SAMP> (where <SAMP>`^Z'</SAMP> denotes a <SAMP>`control-z'</SAMP>
  56. character) are annotations; the rest is output from GDB.
  57. <P>
  58. <H1><A NAME="SEC2" HREF="ANNOTATE.HTM#SEC2">The Server Prefix</A></H1>
  59. <P>
  60. To issue a command to GDB without affecting certain aspects of the state
  61. which is seen by users, prefix it with <SAMP>`server '</SAMP>.  This means that
  62. this command will not affect the command history, nor will it affect
  63. GDB's notion of which command to repeat if <KBD>RET</KBD> is pressed on a
  64. line by itself.
  65. <P>
  66. The server prefix does not affect the recording of values into the value
  67. history; to print a value without recording it into the value history,
  68. use the <CODE>output</CODE> command instead of the <CODE>print</CODE> command.
  69. <P>
  70. <H1><A NAME="SEC3" HREF="ANNOTATE.HTM#SEC3">Values</A></H1>
  71. <P>
  72. When a value is printed in various contexts, GDB uses annotations to
  73. delimit the value from the surrounding text.
  74. <A NAME="IDX1"></A>
  75. <A NAME="IDX2"></A>
  76. <A NAME="IDX3"></A>
  77. <P>
  78. If a value is printed using <CODE>print</CODE> and added to the value history,
  79. the annotation looks like
  80. <P>
  81. <PRE>
  82. ^Z^Zvalue-history-begin <VAR>history-number</VAR> <VAR>value-flags</VAR>
  83. <VAR>history-string</VAR>
  84. ^Z^Zvalue-history-value
  85. <VAR>the-value</VAR>
  86. ^Z^Zvalue-history-end
  87. </PRE>
  88. <P>
  89. where <VAR>history-number</VAR> is the number it is getting in the value
  90. history, <VAR>history-string</VAR> is a string, such as <SAMP>`$5 = '</SAMP>, which
  91. introduces the value to the user, <VAR>the-value</VAR> is the output
  92. corresponding to the value itself, and <VAR>value-flags</VAR> is <SAMP>`*'</SAMP> for
  93. a value which can be dereferenced and <SAMP>`-'</SAMP> for a value which cannot.
  94. <A NAME="IDX4"></A>
  95. <A NAME="IDX5"></A>
  96. <P>
  97. If the value is not added to the value history (it is an invalid float
  98. or it is printed with the <CODE>output</CODE> command), the annotation is similar:
  99. <P>
  100. <PRE>
  101. ^Z^Zvalue-begin <VAR>value-flags</VAR>
  102. <VAR>the-value</VAR>
  103. ^Z^Zvalue-end
  104. </PRE>
  105. <A NAME="IDX6"></A>
  106. <A NAME="IDX7"></A>
  107. <A NAME="IDX8"></A>
  108. <A NAME="IDX9"></A>
  109. <P>
  110. When GDB prints an argument to a function (for example, in the output
  111. from the <CODE>backtrace</CODE> command), it annotates it as follows:
  112. <P>
  113. <PRE>
  114. ^Z^Zarg-begin
  115. <VAR>argument-name</VAR>
  116. ^Z^Zarg-name-end
  117. <VAR>separator-string</VAR>
  118. ^Z^Zarg-value <VAR>value-flags</VAR>
  119. <VAR>the-value</VAR>
  120. ^Z^Zarg-end
  121. </PRE>
  122. <P>
  123. where <VAR>argument-name</VAR> is the name of the argument,
  124. <VAR>separator-string</VAR> is text which separates the name from the value
  125. for the user's benefit (such as <SAMP>`='</SAMP>), and <VAR>value-flags</VAR> and
  126. <VAR>the-value</VAR> have the same meanings as in a
  127. <CODE>value-history-begin</CODE> annotation.
  128. <A NAME="IDX10"></A>
  129. <A NAME="IDX11"></A>
  130. <A NAME="IDX12"></A>
  131. <A NAME="IDX13"></A>
  132. <P>
  133. When printing a structure, GDB annotates it as follows:
  134. <P>
  135. <PRE>
  136. ^Z^Zfield-begin <VAR>value-flags</VAR>
  137. <VAR>field-name</VAR>
  138. ^Z^Zfield-name-end
  139. <VAR>separator-string</VAR>
  140. ^Z^Zfield-value
  141. <VAR>the-value</VAR>
  142. ^Z^Zfield-end
  143. </PRE>
  144. <P>
  145. where <VAR>field-name</VAR> is the name of the field, <VAR>separator-string</VAR>
  146. is text which separates the name from the value for the user's benefit
  147. (such as <SAMP>`='</SAMP>), and <VAR>value-flags</VAR> and <VAR>the-value</VAR> have the
  148. same meanings as in a <CODE>value-history-begin</CODE> annotation.
  149. <P>
  150. When printing an array, GDB annotates it as follows:
  151. <P>
  152. <PRE>
  153. ^Z^Zarray-section-begin <VAR>array-index</VAR> <VAR>value-flags</VAR>
  154. </PRE>
  155. <P>
  156. where <VAR>array-index</VAR> is the index of the first element being
  157. annotated and <VAR>value-flags</VAR> has the same meaning as in a
  158. <CODE>value-history-begin</CODE> annotation.  This is followed by any number
  159. of elements, where is element can be either a single element:
  160. <A NAME="IDX14"></A>
  161. <P>
  162. <PRE>
  163. <SAMP>`,'</SAMP> <VAR>whitespace</VAR>         ; omitted for the first element
  164. <VAR>the-value</VAR>
  165. ^Z^Zelt
  166. </PRE>
  167. <P>
  168. or a repeated element
  169. <A NAME="IDX15"></A>
  170. <A NAME="IDX16"></A>
  171. <P>
  172. <PRE>
  173. <SAMP>`,'</SAMP> <VAR>whitespace</VAR>         ; omitted for the first element
  174. <VAR>the-value</VAR>
  175. ^Z^Zelt-rep <VAR>number-of-repititions</VAR>
  176. <VAR>repetition-string</VAR>
  177. ^Z^Zelt-rep-end
  178. </PRE>
  179. <P>
  180. In both cases, <VAR>the-value</VAR> is the output for the value of the
  181. element and <VAR>whitespace</VAR> can contain spaces, tabs, and newlines.  In
  182. the repeated case, <VAR>number-of-repititons</VAR> is the number of
  183. consecutive array elements which contain that value, and
  184. <VAR>repetition-string</VAR> is a string which is designed to convey to the
  185. user that repitition is being depicted.
  186. <A NAME="IDX17"></A>
  187. <P>
  188. Once all the array elements have been output, the array annotation is
  189. ended with
  190. <P>
  191. <PRE>
  192. ^Z^Zarray-section-end
  193. </PRE>
  194. <P>
  195. <H1><A NAME="SEC4" HREF="ANNOTATE.HTM#SEC4">Frames</A></H1>
  196. <P>
  197. Whenever GDB prints a frame, it annotates it.  For example, this applies
  198. to frames printed when GDB stops, output from commands such as
  199. <CODE>backtrace</CODE> or <CODE>up</CODE>, etc.
  200. <A NAME="IDX18"></A>
  201. <P>
  202. The frame annotation begins with
  203. <P>
  204. <PRE>
  205. ^Z^Zframe-begin <VAR>level</VAR> <VAR>address</VAR>
  206. <VAR>level-string</VAR>
  207. </PRE>
  208. <P>
  209. where <VAR>level</VAR> is the number of the frame (0 is the innermost frame,
  210. and other frames have positive numbers), <VAR>address</VAR> is the address of
  211. the code executing in that frame, and <VAR>level-string</VAR> is a string
  212. designed to convey the level to the user.  The frame ends with
  213. <A NAME="IDX19"></A>
  214. <P>
  215. <PRE>
  216. ^Z^Zframe-end
  217. </PRE>
  218. <P>
  219. Between these annotations is the main body of the frame, which can
  220. consist of
  221. <P>
  222. <UL>
  223. <A NAME="IDX20"></A>
  224. <LI>
  225. <PRE>
  226. ^Z^Zfunction-call
  227. <VAR>function-call-string</VAR>
  228. </PRE>
  229.  
  230. where <VAR>function-call-string</VAR> is text designed to convey to the user
  231. that this frame is associated with a function call made by GDB to a
  232. function in the program being debugged.
  233.  
  234. <A NAME="IDX21"></A>
  235. <LI>
  236. <PRE>
  237. ^Z^Zsignal-handler-caller
  238. <VAR>signal-handler-caller-string</VAR>
  239. </PRE>
  240.  
  241. where <VAR>signal-handler-caller-string</VAR> is text designed to convey to
  242. the user that this frame is associated with whatever mechanism is used
  243. by this operating system to call a signal handler (it is the frame which
  244. calls the signal handler, not the frame for the signal handler itself).
  245.  
  246. <LI>
  247. A normal frame.
  248.  
  249. <A NAME="IDX23"></A>
  250. <A NAME="IDX22"></A>
  251. This can optionally (depending on whether this is thought of as
  252. interesting information for the user to see) begin with
  253.  
  254. <PRE>
  255. ^Z^Zframe-address
  256. <VAR>address</VAR>
  257. ^Z^Zframe-address-end
  258. <VAR>separator-string</VAR>
  259. </PRE>
  260.  
  261. where <VAR>address</VAR> is the address executing in the frame (the same
  262. address as in the <CODE>frame-begin</CODE> annotation), and
  263. <VAR>separator-string</VAR> is a string intended to separate this address
  264. from what follows for the user's benefit.
  265.  
  266. <A NAME="IDX25"></A>
  267. <A NAME="IDX24"></A>
  268. Then comes
  269.  
  270. <PRE>
  271. ^Z^Zframe-function-name
  272. <VAR>function-name</VAR>
  273. ^Z^Zframe-args
  274. <VAR>arguments</VAR>
  275. </PRE>
  276.  
  277. where <VAR>function-name</VAR> is the name of the function executing in the
  278. frame, or <SAMP>`??'</SAMP> if not known, and <VAR>arguments</VAR> are the arguments
  279. to the frame, with parentheses around them (each argument is annotated
  280. individually as well see section <A HREF="ANNOTATE.000#SEC3">Values</A>).
  281.  
  282. <A NAME="IDX27"></A>
  283. <A NAME="IDX28"></A>
  284. <A NAME="IDX29"></A>
  285. <A NAME="IDX30"></A>
  286. <A NAME="IDX26"></A>
  287. If source information is available, a reference to it is then printed:
  288.  
  289. <PRE>
  290. ^Z^Zframe-source-begin
  291. <VAR>source-intro-string</VAR>
  292. ^Z^Zframe-source-file
  293. <VAR>filename</VAR>
  294. ^Z^Zframe-source-file-end
  295. :
  296. ^Z^Zframe-source-line
  297. <VAR>line-number</VAR>
  298. ^Z^Zframe-source-end
  299. </PRE>
  300.  
  301. where <VAR>source-intro-string</VAR> separates for the user's benefit the
  302. reference from the text which precedes it, <VAR>filename</VAR> is the name of
  303. the source file, and <VAR>line-number</VAR> is the line number within that
  304. file (the first line is line 1).
  305.  
  306. <A NAME="IDX31"></A>
  307. If GDB prints some information about where the frame is from (which
  308. library, which load segment, etc.; currently only done on the RS/6000),
  309. it is annotated with
  310.  
  311. <PRE>
  312. ^Z^Zframe-where
  313. <VAR>information</VAR>
  314. </PRE>
  315.  
  316. Then, if source is to actually be displayed for this frame (for example,
  317. this is not true for output from the <CODE>backtrace</CODE> command), then a
  318. <CODE>source</CODE> annotation (see section <A HREF="ANNOTATE.000#SEC11">Displaying Source</A>) is displayed.  Unlike most
  319. annotations, this is output instead of the normal text which would be
  320. output, not in addition.
  321. </UL>
  322. <P>
  323. <H1><A NAME="SEC5" HREF="ANNOTATE.HTM#SEC5">Displays</A></H1>
  324. <A NAME="IDX32"></A>
  325. <A NAME="IDX33"></A>
  326. <A NAME="IDX34"></A>
  327. <A NAME="IDX35"></A>
  328. <A NAME="IDX36"></A>
  329. <A NAME="IDX37"></A>
  330. <A NAME="IDX38"></A>
  331. <P>
  332. When GDB is told to display something using the <CODE>display</CODE> command,
  333. the results of the display are annotated:
  334. <P>
  335. <PRE>
  336. ^Z^Zdisplay-begin
  337. <VAR>number</VAR>
  338. ^Z^Zdisplay-number-end
  339. <VAR>number-separator</VAR>
  340. ^Z^Zdisplay-format
  341. <VAR>format</VAR>
  342. ^Z^Zdisplay-expression
  343. <VAR>expression</VAR>
  344. ^Z^Zdisplay-expression-end
  345. <VAR>expression-separator</VAR>
  346. ^Z^Zdisplay-value
  347. <VAR>value</VAR>
  348. ^Z^Zdisplay-end
  349. </PRE>
  350. <P>
  351. where <VAR>number</VAR> is the number of the display, <VAR>number-separator</VAR>
  352. is intended to separate the number from what follows for the user,
  353. <VAR>format</VAR> includes information such as the size, format, or other
  354. information about how the value is being displayed, <VAR>expression</VAR> is
  355. the expression being displayed, <VAR>expression-separator</VAR> is intended
  356. to separate the expression from the text that follows for the user,
  357. and <VAR>value</VAR> is the actual value being displayed.
  358. <P>
  359. <H1><A NAME="SEC6" HREF="ANNOTATE.HTM#SEC6">Annotation for GDB Input</A></H1>
  360. <P>
  361. When GDB prompts for input, it annotates this fact so it is possible
  362. to know when to send output, when the output from a given command is
  363. over, etc.
  364. <P>
  365. Different kinds of input each have a different <DFN>input type</DFN>.  Each
  366. input type has three annotations: a <CODE>pre-</CODE> annotation, which
  367. denotes the beginning of any prompt which is being output, a plain
  368. annotation, which denotes the end of the prompt, and then a <CODE>post-</CODE>
  369. annotation which denotes the end of any echo which may (or may not) be
  370. associated with the input.  For example, the <CODE>prompt</CODE> input type
  371. features the following annotations:
  372. <P>
  373. <PRE>
  374. ^Z^Zpre-prompt
  375. ^Z^Zprompt
  376. ^Z^Zpost-prompt
  377. </PRE>
  378. <P>
  379. The input types are
  380. <P>
  381. <A NAME="IDX39"></A>
  382. <A NAME="IDX40"></A>
  383. <A NAME="IDX41"></A>
  384. <DL COMPACT>
  385. <DT><CODE>prompt</CODE>
  386. <DD>When GDB is prompting for a command (the main GDB prompt).
  387.  
  388. <A NAME="IDX43"></A>
  389. <A NAME="IDX44"></A>
  390. <A NAME="IDX42"></A>
  391. <DT><CODE>commands</CODE>
  392. <DD>When GDB prompts for a set of commands, like in the <CODE>commands</CODE>
  393. command.  The annotations are repeated for each command which is input.
  394.  
  395. <A NAME="IDX46"></A>
  396. <A NAME="IDX47"></A>
  397. <A NAME="IDX45"></A>
  398. <DT><CODE>overload-choice</CODE>
  399. <DD>When GDB wants the user to select between various overloaded functions.
  400.  
  401. <A NAME="IDX49"></A>
  402. <A NAME="IDX50"></A>
  403. <A NAME="IDX48"></A>
  404. <DT><CODE>query</CODE>
  405. <DD>When GDB wants the user to confirm a potentially dangerous operation.
  406.  
  407. <A NAME="IDX52"></A>
  408. <A NAME="IDX53"></A>
  409. <A NAME="IDX51"></A>
  410. <DT><CODE>prompt-for-continue</CODE>
  411. <DD>When GDB is asking the user to press return to continue.  Note: Don't
  412. expect this to work well; instead use <CODE>set height 0</CODE> to disable
  413. prompting.  This is because the counting of lines is buggy in the
  414. presence of annotations.
  415. </DL>
  416. <P>
  417. <H1><A NAME="SEC7" HREF="ANNOTATE.HTM#SEC7">Errors</A></H1>
  418. <A NAME="IDX54"></A>
  419. <P>
  420. <PRE>
  421. ^Z^Zquit
  422. </PRE>
  423. <P>
  424. This annotation occurs right before GDB responds to an interrupt.
  425. <A NAME="IDX55"></A>
  426. <P>
  427. <PRE>
  428. ^Z^Zerror
  429. </PRE>
  430. <P>
  431. This annotation occurs right before GDB responds to an error.
  432. <P>
  433. Quit and error annotations indicate that any annotations which GDB was
  434. in the middle of may end abruptly.  For example, if a
  435. <CODE>value-history-begin</CODE> annotation is followed by a <CODE>error</CODE>, one
  436. cannot expect to receive the matching <CODE>value-history-end</CODE>.  One
  437. cannot expect not to receive it either, however; an error annotation
  438. does not necessarily mean that GDB is immediately returning all the way
  439. to the top level.
  440. <A NAME="IDX56"></A>
  441. <P>
  442. A quit or error annotation may be preceded by
  443. <P>
  444. <PRE>
  445. ^Z^Zerror-begin
  446. </PRE>
  447. <P>
  448. Any output between that and the quit or error annotation is the error
  449. message.
  450. <P>
  451. Warning messages are not yet annotated.
  452. <P>
  453. <H1><A NAME="SEC8" HREF="ANNOTATE.HTM#SEC8">Information on Breakpoints</A></H1>
  454. <P>
  455. The output from the <CODE>info breakpoints</CODE> command is annotated as follows:
  456. <A NAME="IDX57"></A>
  457. <A NAME="IDX58"></A>
  458. <P>
  459. <PRE>
  460. ^Z^Zbreakpoints-headers
  461. <VAR>header-entry</VAR>
  462. ^Z^Zbreakpoints-table
  463. </PRE>
  464. <P>
  465. where <VAR>header-entry</VAR> has the same syntax as an entry (see below) but
  466. instead of containing data, it contains strings which are intended to
  467. convey the meaning of each field to the user.  This is followed by any
  468. number of entries.  If a field does not apply for this entry, it is
  469. omitted.  Fields may contain trailing whitespace.  Each entry consists
  470. of:
  471. <A NAME="IDX59"></A>
  472. <A NAME="IDX60"></A>
  473. <P>
  474. <PRE>
  475. ^Z^Zrecord
  476. ^Z^Zfield 0
  477. <VAR>number</VAR>
  478. ^Z^Zfield 1
  479. <VAR>type</VAR>
  480. ^Z^Zfield 2
  481. <VAR>disposition</VAR>
  482. ^Z^Zfield 3
  483. <VAR>enable</VAR>
  484. ^Z^Zfield 4
  485. <VAR>address</VAR>
  486. ^Z^Zfield 5
  487. <VAR>what</VAR>
  488. ^Z^Zfield 6
  489. <VAR>frame</VAR>
  490. ^Z^Zfield 7
  491. <VAR>condition</VAR>
  492. ^Z^Zfield 8
  493. <VAR>ignore-count</VAR>
  494. ^Z^Zfield 9
  495. <VAR>commands</VAR>
  496. </PRE>
  497. <P>
  498. The output ends with
  499. <A NAME="IDX61"></A>
  500. <P>
  501. <PRE>
  502. ^Z^Zbreakpoints-table-end
  503. </PRE>
  504. <P>
  505. <H1><A NAME="SEC9" HREF="ANNOTATE.HTM#SEC9">Invalidation Notices</A></H1>
  506. <P>
  507. The following annotations say that certain pieces of state may have
  508. changed.
  509. <P>
  510. <A NAME="IDX62"></A>
  511. <DL COMPACT>
  512. <DT><CODE>^Z^Zframes-invalid</CODE>
  513. <DD>
  514. The frames (for example, output from the <CODE>backtrace</CODE> command) may
  515. have changed.
  516.  
  517. <A NAME="IDX63"></A>
  518. <DT><CODE>^Z^Zbreakpoints-invalid</CODE>
  519. <DD>
  520. The breakpoints may have changed.  For example, the user just added or
  521. deleted a breakpoint.
  522. </DL>
  523. <P>
  524. <H1><A NAME="SEC10" HREF="ANNOTATE.HTM#SEC10">Running the Program</A></H1>
  525. <A NAME="IDX64"></A>
  526. <A NAME="IDX65"></A>
  527. <P>
  528. When the program starts executing due to a GDB command such as
  529. <CODE>step</CODE> or <CODE>continue</CODE>, 
  530. <P>
  531. <PRE>
  532. ^Z^Zstarting
  533. </PRE>
  534. <P>
  535. is output.  When the program stops, 
  536. <P>
  537. <PRE>
  538. ^Z^Zstopped
  539. </PRE>
  540. <P>
  541. is output.  Before the <CODE>stopped</CODE> annotation, a variety of
  542. annotations describe how the program stopped.
  543. <P>
  544. <A NAME="IDX66"></A>
  545. <DL COMPACT>
  546. <DT><CODE>^Z^Zexited <VAR>exit-status</VAR></CODE>
  547. <DD>The program exited, and <VAR>exit-status</VAR> is the exit status (zero for
  548. successful exit, otherwise nonzero).
  549.  
  550. <A NAME="IDX68"></A>
  551. <A NAME="IDX69"></A>
  552. <A NAME="IDX70"></A>
  553. <A NAME="IDX71"></A>
  554. <A NAME="IDX67"></A>
  555. <DT><CODE>^Z^Zsignalled</CODE>
  556. <DD>The program exited with a signal.  After the <CODE>^Z^Zsignalled</CODE>, the
  557. annotation continues:
  558.  
  559. <PRE>
  560. <VAR>intro-text</VAR>
  561. ^Z^Zsignal-name
  562. <VAR>name</VAR>
  563. ^Z^Zsignal-name-end
  564. <VAR>middle-text</VAR>
  565. ^Z^Zsignal-string
  566. <VAR>string</VAR>
  567. ^Z^Zsignal-string-end
  568. <VAR>end-text</VAR>
  569. </PRE>
  570.  
  571. where <VAR>name</VAR> is the name of the signal, such as <CODE>SIGILL</CODE> or
  572. <CODE>SIGSEGV</CODE>, and <VAR>string</VAR> is the explanation of the signal, such
  573. as <CODE>Illegal Instruction</CODE> or <CODE>Segmentation fault</CODE>.
  574. <VAR>intro-text</VAR>, <VAR>middle-text</VAR>, and <VAR>end-text</VAR> are for the
  575. user's benefit and have no particular format.
  576.  
  577. <A NAME="IDX72"></A>
  578. <DT><CODE>^Z^Zsignal</CODE>
  579. <DD>The syntax of this annotation is just like <CODE>signalled</CODE>, but GDB is
  580. just saying that the program received the signal, not that it was
  581. terminated with it.
  582.  
  583. <A NAME="IDX73"></A>
  584. <DT><CODE>^Z^Zbreakpoint <VAR>number</VAR></CODE>
  585. <DD>The program hit breakpoint number <VAR>number</VAR>.
  586.  
  587. <A NAME="IDX74"></A>
  588. <DT><CODE>^Z^Zwatchpoint <VAR>number</VAR></CODE>
  589. <DD>The program hit watchpoint number <VAR>number</VAR>.
  590. </DL>
  591. <P>
  592. <H1><A NAME="SEC11" HREF="ANNOTATE.HTM#SEC11">Displaying Source</A></H1>
  593. <A NAME="IDX75"></A>
  594. <P>
  595. The following annotation is used instead of displaying source code:
  596. <P>
  597. <PRE>
  598. ^Z^Zsource <VAR>filename</VAR>:<VAR>line</VAR>:<VAR>character</VAR>:<VAR>middle</VAR>:<VAR>addr</VAR>
  599. </PRE>
  600. <P>
  601. where <VAR>filename</VAR> is an absolute file name indicating which source
  602. file, <VAR>line</VAR> is the line number within that file (where 1 is the
  603. first line in the file), <VAR>character</VAR> is the character position
  604. within the file (where 0 is the first character in the file) (for most
  605. debug formats this will necessarily point to the beginning of a line),
  606. <VAR>middle</VAR> is <SAMP>`middle'</SAMP> if <VAR>addr</VAR> is in the middle of the
  607. line, or <SAMP>`beg'</SAMP> if <VAR>addr</VAR> is at the beginning of the line, and
  608. <VAR>addr</VAR> is the address in the target program associated with the
  609. source which is being displayed.
  610. <P>
  611. <H1><A NAME="SEC12" HREF="ANNOTATE.HTM#SEC12">Annotations We Might Want in the Future</A></H1>
  612. <P>
  613. <PRE>
  614.     - target-invalid
  615.       the target might have changed (registers, heap contents, or
  616.       execution status).  For performance, we might eventually want
  617.       to hit `registers-invalid' and `all-registers-invalid' with
  618.       greater precision
  619.  
  620.     - systematic annotation for set/show parameters (including
  621.       invalidation notices).
  622.  
  623.     - similarly, `info' returns a list of candidates for invalidation
  624.       notices.
  625. </PRE>
  626. <P>
  627. <H1><A NAME="SEC13" HREF="ANNOTATE.HTM#SEC13">Index</A></H1>
  628. <P>
  629. <H2>a</H2>
  630. <DIR>
  631. <LI><A HREF="ANNOTATE.000#IDX6">arg-begin</A>
  632. <LI><A HREF="ANNOTATE.000#IDX9">arg-end</A>
  633. <LI><A HREF="ANNOTATE.000#IDX7">arg-name-end</A>
  634. <LI><A HREF="ANNOTATE.000#IDX8">arg-value</A>
  635. <LI><A HREF="ANNOTATE.000#IDX17">array-section-end</A>
  636. </DIR>
  637. <H2>b</H2>
  638. <DIR>
  639. <LI><A HREF="ANNOTATE.000#IDX73">breakpoint</A>
  640. <LI><A HREF="ANNOTATE.000#IDX57">breakpoints-headers</A>
  641. <LI><A HREF="ANNOTATE.000#IDX63">breakpoints-invalid</A>
  642. <LI><A HREF="ANNOTATE.000#IDX58">breakpoints-table</A>
  643. <LI><A HREF="ANNOTATE.000#IDX61">breakpoints-table-end</A>
  644. </DIR>
  645. <H2>c</H2>
  646. <DIR>
  647. <LI><A HREF="ANNOTATE.000#IDX43">commands</A>
  648. </DIR>
  649. <H2>d</H2>
  650. <DIR>
  651. <LI><A HREF="ANNOTATE.000#IDX32">display-begin</A>
  652. <LI><A HREF="ANNOTATE.000#IDX38">display-end</A>
  653. <LI><A HREF="ANNOTATE.000#IDX35">display-expression</A>
  654. <LI><A HREF="ANNOTATE.000#IDX36">display-expression-end</A>
  655. <LI><A HREF="ANNOTATE.000#IDX34">display-format</A>
  656. <LI><A HREF="ANNOTATE.000#IDX33">display-number-end</A>
  657. <LI><A HREF="ANNOTATE.000#IDX37">display-value</A>
  658. </DIR>
  659. <H2>e</H2>
  660. <DIR>
  661. <LI><A HREF="ANNOTATE.000#IDX14">elt</A>
  662. <LI><A HREF="ANNOTATE.000#IDX15">elt-rep</A>
  663. <LI><A HREF="ANNOTATE.000#IDX16">elt-rep-end</A>
  664. <LI><A HREF="ANNOTATE.000#IDX55">error</A>
  665. <LI><A HREF="ANNOTATE.000#IDX56">error-begin</A>
  666. <LI><A HREF="ANNOTATE.000#IDX66">exited</A>
  667. </DIR>
  668. <H2>f</H2>
  669. <DIR>
  670. <LI><A HREF="ANNOTATE.000#IDX60">field</A>
  671. <LI><A HREF="ANNOTATE.000#IDX10">field-begin</A>
  672. <LI><A HREF="ANNOTATE.000#IDX13">field-end</A>
  673. <LI><A HREF="ANNOTATE.000#IDX11">field-name-end</A>
  674. <LI><A HREF="ANNOTATE.000#IDX12">field-value</A>
  675. <LI><A HREF="ANNOTATE.000#IDX22">frame-address</A>
  676. <LI><A HREF="ANNOTATE.000#IDX23">frame-address-end</A>
  677. <LI><A HREF="ANNOTATE.000#IDX25">frame-args</A>
  678. <LI><A HREF="ANNOTATE.000#IDX18">frame-begin</A>
  679. <LI><A HREF="ANNOTATE.000#IDX19">frame-end</A>
  680. <LI><A HREF="ANNOTATE.000#IDX24">frame-function-name</A>
  681. <LI><A HREF="ANNOTATE.000#IDX26">frame-source-begin</A>
  682. <LI><A HREF="ANNOTATE.000#IDX30">frame-source-end</A>
  683. <LI><A HREF="ANNOTATE.000#IDX27">frame-source-file</A>
  684. <LI><A HREF="ANNOTATE.000#IDX28">frame-source-file-end</A>
  685. <LI><A HREF="ANNOTATE.000#IDX29">frame-source-line</A>
  686. <LI><A HREF="ANNOTATE.000#IDX31">frame-where</A>
  687. <LI><A HREF="ANNOTATE.000#IDX62">frames-invalid</A>
  688. <LI><A HREF="ANNOTATE.000#IDX20">function-call</A>
  689. </DIR>
  690. <H2>o</H2>
  691. <DIR>
  692. <LI><A HREF="ANNOTATE.000#IDX46">overload-choice</A>
  693. </DIR>
  694. <H2>p</H2>
  695. <DIR>
  696. <LI><A HREF="ANNOTATE.000#IDX44">post-commands</A>
  697. <LI><A HREF="ANNOTATE.000#IDX47">post-overload-choice</A>
  698. <LI><A HREF="ANNOTATE.000#IDX41">post-prompt</A>
  699. <LI><A HREF="ANNOTATE.000#IDX53">post-prompt-for-continue</A>
  700. <LI><A HREF="ANNOTATE.000#IDX50">post-query</A>
  701. <LI><A HREF="ANNOTATE.000#IDX42">pre-commands</A>
  702. <LI><A HREF="ANNOTATE.000#IDX45">pre-overload-choice</A>
  703. <LI><A HREF="ANNOTATE.000#IDX39">pre-prompt</A>
  704. <LI><A HREF="ANNOTATE.000#IDX51">pre-prompt-for-continue</A>
  705. <LI><A HREF="ANNOTATE.000#IDX48">pre-query</A>
  706. <LI><A HREF="ANNOTATE.000#IDX40">prompt</A>
  707. <LI><A HREF="ANNOTATE.000#IDX52">prompt-for-continue</A>
  708. </DIR>
  709. <H2>q</H2>
  710. <DIR>
  711. <LI><A HREF="ANNOTATE.000#IDX49">query</A>
  712. <LI><A HREF="ANNOTATE.000#IDX54">quit</A>
  713. </DIR>
  714. <H2>r</H2>
  715. <DIR>
  716. <LI><A HREF="ANNOTATE.000#IDX59">record</A>
  717. </DIR>
  718. <H2>s</H2>
  719. <DIR>
  720. <LI><A HREF="ANNOTATE.000#IDX72">signal</A>
  721. <LI><A HREF="ANNOTATE.000#IDX21">signal-handler-caller</A>
  722. <LI><A HREF="ANNOTATE.000#IDX68">signal-name</A>
  723. <LI><A HREF="ANNOTATE.000#IDX69">signal-name-end</A>
  724. <LI><A HREF="ANNOTATE.000#IDX70">signal-string</A>
  725. <LI><A HREF="ANNOTATE.000#IDX71">signal-string-end</A>
  726. <LI><A HREF="ANNOTATE.000#IDX67">signalled</A>
  727. <LI><A HREF="ANNOTATE.000#IDX75">source</A>
  728. <LI><A HREF="ANNOTATE.000#IDX64">starting</A>
  729. <LI><A HREF="ANNOTATE.000#IDX65">stopping</A>
  730. </DIR>
  731. <H2>v</H2>
  732. <DIR>
  733. <LI><A HREF="ANNOTATE.000#IDX4">value-begin</A>
  734. <LI><A HREF="ANNOTATE.000#IDX5">value-end</A>
  735. <LI><A HREF="ANNOTATE.000#IDX1">value-history-begin</A>
  736. <LI><A HREF="ANNOTATE.000#IDX3">value-history-end</A>
  737. <LI><A HREF="ANNOTATE.000#IDX2">value-history-value</A>
  738. </DIR>
  739. <H2>w</H2>
  740. <DIR>
  741. <LI><A HREF="ANNOTATE.000#IDX74">watchpoint</A>
  742. </DIR>
  743. <P>
  744. </BODY>
  745. </HTML>
  746.