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