Commit | Line | Data |
---|---|---|
e6f672d2 AC |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename annotate.info | |
afe157ca EZ |
4 | |
5 | @c This is a dir.info fragment to support semi-automated addition of | |
6 | @c manuals to an info tree. | |
03727ca6 | 7 | @dircategory Software development |
afe157ca EZ |
8 | @direntry |
9 | * Annotate: (annotate). The obsolete annotation interface. | |
10 | @end direntry | |
11 | ||
e6f672d2 AC |
12 | @c |
13 | @include gdb-cfg.texi | |
14 | @c | |
15 | @settitle @value{GDBN}'s Obsolete Annotations | |
16 | @setchapternewpage off | |
17 | @c %**end of header | |
18 | ||
19 | @set EDITION 1.0 | |
20 | @set DATE July 2003 | |
21 | ||
22 | @c NOTE: cagney/2003-07-28: | |
d3e8051b | 23 | @c Don't make this migration document an appendix of GDB's user guide. |
e6f672d2 AC |
24 | @c By keeping this separate, the size of the user guide is contained. If |
25 | @c the user guide to get much bigger it would need to switch to a larger, | |
26 | @c more expensive, form factor and would drive up the manuals publication | |
27 | @c cost. Having a smaller cheaper manual helps the GNU Press with its sales. | |
28 | ||
a67ec3f4 JM |
29 | @copying |
30 | Copyright @copyright{} 1994, 1995, 2000, 2001, 2003, 2004, 2005, 2007, | |
44944448 | 31 | 2008, 2009, 2010, 2011 Free Software Foundation, Inc. |
e6f672d2 AC |
32 | |
33 | Permission is granted to copy, distribute and/or modify this document | |
4f5d9f07 | 34 | under the terms of the GNU Free Documentation License, Version 1.3 or |
e6f672d2 AC |
35 | any later version published by the Free Software Foundation; with no |
36 | Invariant Sections, with no Front-Cover Texts, and with no Back-Cover | |
37 | Texts. A copy of the license is included in the section entitled ``GNU | |
38 | Free Documentation License''. | |
a67ec3f4 JM |
39 | @end copying |
40 | ||
41 | @ifnottex | |
42 | This file documents @value{GDBN}'s obsolete annotations. | |
e6f672d2 | 43 | |
a67ec3f4 JM |
44 | @insertcopying |
45 | @end ifnottex | |
e6f672d2 AC |
46 | |
47 | @titlepage | |
48 | @title @value{GDBN}'s Obsolete Annotations | |
49 | @subtitle Edition @value{EDITION} | |
50 | @subtitle @value{DATE} | |
51 | @author Free Software Foundation | |
52 | @page | |
53 | @vskip 0pt plus 1filll | |
a67ec3f4 | 54 | @insertcopying |
e6f672d2 AC |
55 | @end titlepage |
56 | ||
a67ec3f4 | 57 | @ifnottex |
e6f672d2 AC |
58 | @node Top |
59 | @top GDB Annotations | |
60 | ||
61 | This document describes the obsolete level two annotation interface | |
62 | implemented in older @value{GDBN} versions. | |
c906108c | 63 | |
d700128c | 64 | @ignore |
c906108c | 65 | This is Edition @value{EDITION}, @value{DATE}. |
d700128c | 66 | @end ignore |
a67ec3f4 | 67 | @end ifnottex |
c906108c SS |
68 | |
69 | @menu | |
d700128c | 70 | * Annotations Overview:: What annotations are; the general syntax. |
e6f672d2 AC |
71 | * Limitations:: Limitations of the annotation interface. |
72 | * Migrating to GDB/MI:: Migrating to GDB/MI | |
d700128c EZ |
73 | * Server Prefix:: Issuing a command without affecting user state. |
74 | * Value Annotations:: Values are marked as such. | |
75 | * Frame Annotations:: Stack frames are annotated. | |
76 | * Displays:: @value{GDBN} can be told to display something periodically. | |
77 | * Prompting:: Annotations marking @value{GDBN}'s need for input. | |
c906108c SS |
78 | * Errors:: Annotations for error messages. |
79 | * Breakpoint Info:: Information on breakpoints. | |
80 | * Invalidation:: Some annotations describe things now invalid. | |
d700128c EZ |
81 | * Annotations for Running:: |
82 | Whether the program is running, how it stopped, etc. | |
83 | * Source Annotations:: Annotations describing source code. | |
17314269 | 84 | * Multi-threaded Apps:: An annotation that reports multi-threadedness. |
e6f672d2 AC |
85 | |
86 | * GNU Free Documentation License:: | |
c906108c | 87 | @end menu |
c906108c | 88 | |
e6f672d2 AC |
89 | @contents |
90 | ||
d700128c | 91 | @node Annotations Overview |
e6f672d2 | 92 | @chapter What is an Annotation? |
d700128c | 93 | @cindex annotations |
c906108c | 94 | |
e6f672d2 AC |
95 | To produce obsolete level two annotations, start @value{GDBN} with the |
96 | @code{--annotate=2} option. | |
c906108c SS |
97 | |
98 | Annotations start with a newline character, two @samp{control-z} | |
99 | characters, and the name of the annotation. If there is no additional | |
100 | information associated with this annotation, the name of the annotation | |
101 | is followed immediately by a newline. If there is additional | |
102 | information, the name of the annotation is followed by a space, the | |
103 | additional information, and a newline. The additional information | |
104 | cannot contain newline characters. | |
105 | ||
106 | Any output not beginning with a newline and two @samp{control-z} | |
6d2ebf8b SS |
107 | characters denotes literal output from @value{GDBN}. Currently there is |
108 | no need for @value{GDBN} to output a newline followed by two | |
109 | @samp{control-z} characters, but if there was such a need, the | |
110 | annotations could be extended with an @samp{escape} annotation which | |
111 | means those three characters as output. | |
c906108c | 112 | |
d700128c | 113 | A simple example of starting up @value{GDBN} with annotations is: |
c906108c | 114 | |
d700128c | 115 | @smallexample |
c906108c | 116 | $ gdb --annotate=2 |
d700128c EZ |
117 | GNU GDB 5.0 |
118 | Copyright 2000 Free Software Foundation, Inc. | |
6d2ebf8b SS |
119 | GDB is free software, covered by the GNU General Public License, |
120 | and you are welcome to change it and/or distribute copies of it | |
121 | under certain conditions. | |
d700128c | 122 | Type "show copying" to see the conditions. |
6d2ebf8b SS |
123 | There is absolutely no warranty for GDB. Type "show warranty" |
124 | for details. | |
d700128c | 125 | This GDB was configured as "sparc-sun-sunos4.1.3" |
c906108c SS |
126 | |
127 | ^Z^Zpre-prompt | |
128 | (gdb) | |
129 | ^Z^Zprompt | |
130 | quit | |
131 | ||
132 | ^Z^Zpost-prompt | |
133 | $ | |
d700128c | 134 | @end smallexample |
c906108c | 135 | |
6d2ebf8b SS |
136 | Here @samp{quit} is input to @value{GDBN}; the rest is output from |
137 | @value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} | |
138 | denotes a @samp{control-z} character) are annotations; the rest is | |
139 | output from @value{GDBN}. | |
c906108c | 140 | |
e6f672d2 AC |
141 | @node Limitations |
142 | @chapter Limitations of the Annotation Interface | |
143 | ||
144 | The level two annotations mechanism is known to have a number of | |
145 | technical and architectural limitations. As a consequence, in 2001, | |
146 | with the release of @value{GDBN} 5.1 and the addition of @sc{gdb/mi}, | |
147 | the annotation interface was marked as deprecated. | |
148 | ||
149 | This chapter discusses the known problems. | |
150 | ||
151 | @section Dependant on @sc{cli} output | |
152 | ||
153 | The annotation interface works by interspersing markups with | |
ce2826aa | 154 | @value{GDBN} normal command-line interpreter output. Unfortunately, this |
e6f672d2 AC |
155 | makes the annotation client dependant on not just the annotations, but |
156 | also the @sc{cli} output. This is because the client is forced to | |
157 | assume that specific @value{GDBN} commands provide specific information. | |
158 | Any change to @value{GDBN}'s @sc{cli} output modifies or removes that | |
159 | information and, consequently, likely breaks the client. | |
160 | ||
d3e8051b | 161 | Since the @sc{gdb/mi} output is independent of the @sc{cli}, it does not |
e6f672d2 AC |
162 | have this problem. |
163 | ||
164 | @section Scalability | |
165 | ||
166 | The annotation interface relies on value annotations (@pxref{Value | |
167 | Annotations}) and the display mechanism as a way of obtaining up-to-date | |
168 | value information. These mechanisms are not scalable. | |
169 | ||
170 | In a graphical environment, where many values can be displayed | |
171 | simultaneously, a serious performance problem occurs when the client | |
172 | tries to first extract from @value{GDBN}, and then re-display, all those | |
173 | values. The client should instead only request and update the values | |
174 | that changed. | |
175 | ||
176 | The @sc{gdb/mi} Variable Objects provide just that mechanism. | |
177 | ||
178 | @section Correctness | |
179 | ||
180 | The annotation interface assumes that a variable's value can only be | |
181 | changed when the target is running. This assumption is not correct. A | |
182 | single assignment to a single variable can result in the entire target, | |
183 | and all displayed values, needing an update. | |
184 | ||
185 | The @sc{gdb/mi} Variable Objects include a mechanism for efficiently | |
186 | reporting such changes. | |
187 | ||
188 | @section Reliability | |
189 | ||
190 | The @sc{gdb/mi} interface includes a dedicated test directory | |
191 | (@file{gdb/gdb.mi}), and any addition or fix to @sc{gdb/mi} must include | |
192 | testsuite changes. | |
193 | ||
194 | @section Maintainability | |
195 | ||
196 | The annotation mechanism was implemented by interspersing @sc{cli} print | |
197 | statements with various annotations. As a consequence, any @sc{cli} | |
198 | output change can alter the annotation output. | |
199 | ||
d3e8051b EZ |
200 | Since the @sc{gdb/mi} output is independent of the @sc{cli}, and the |
201 | @sc{gdb/mi} is increasingly implemented independent of the @sc{cli} | |
e6f672d2 AC |
202 | code, its long term maintenance is much easier. |
203 | ||
204 | @node Migrating to GDB/MI | |
205 | @chapter Migrating to @sc{gdb/mi} | |
206 | ||
207 | By using the @samp{interp mi} command, it is possible for annotation | |
208 | clients to invoke @sc{gdb/mi} commands, and hence access the | |
209 | @sc{gdb/mi}. By doing this, existing annotation clients have a | |
210 | migration path from this obsolete interface to @sc{gdb/mi}. | |
211 | ||
d700128c | 212 | @node Server Prefix |
e6f672d2 | 213 | @chapter The Server Prefix |
d700128c | 214 | @cindex server prefix for annotations |
c906108c | 215 | |
6d2ebf8b SS |
216 | To issue a command to @value{GDBN} without affecting certain aspects of |
217 | the state which is seen by users, prefix it with @samp{server }. This | |
218 | means that this command will not affect the command history, nor will it | |
219 | affect @value{GDBN}'s notion of which command to repeat if @key{RET} is | |
220 | pressed on a line by itself. | |
c906108c SS |
221 | |
222 | The server prefix does not affect the recording of values into the value | |
223 | history; to print a value without recording it into the value history, | |
224 | use the @code{output} command instead of the @code{print} command. | |
225 | ||
d700128c | 226 | @node Value Annotations |
e6f672d2 AC |
227 | @chapter Values |
228 | ||
229 | @emph{Value Annotations have been removed. @sc{gdb/mi} instead provides | |
230 | Variable Objects.} | |
c906108c | 231 | |
d700128c | 232 | @cindex annotations for values |
6d2ebf8b SS |
233 | When a value is printed in various contexts, @value{GDBN} uses |
234 | annotations to delimit the value from the surrounding text. | |
c906108c SS |
235 | |
236 | @findex value-history-begin | |
237 | @findex value-history-value | |
238 | @findex value-history-end | |
239 | If a value is printed using @code{print} and added to the value history, | |
240 | the annotation looks like | |
241 | ||
6d2ebf8b | 242 | @smallexample |
c906108c SS |
243 | ^Z^Zvalue-history-begin @var{history-number} @var{value-flags} |
244 | @var{history-string} | |
245 | ^Z^Zvalue-history-value | |
246 | @var{the-value} | |
247 | ^Z^Zvalue-history-end | |
6d2ebf8b | 248 | @end smallexample |
c906108c | 249 | |
cb51c4e0 | 250 | @noindent |
c906108c SS |
251 | where @var{history-number} is the number it is getting in the value |
252 | history, @var{history-string} is a string, such as @samp{$5 = }, which | |
253 | introduces the value to the user, @var{the-value} is the output | |
254 | corresponding to the value itself, and @var{value-flags} is @samp{*} for | |
255 | a value which can be dereferenced and @samp{-} for a value which cannot. | |
256 | ||
257 | @findex value-begin | |
258 | @findex value-end | |
259 | If the value is not added to the value history (it is an invalid float | |
260 | or it is printed with the @code{output} command), the annotation is similar: | |
261 | ||
6d2ebf8b | 262 | @smallexample |
c906108c SS |
263 | ^Z^Zvalue-begin @var{value-flags} |
264 | @var{the-value} | |
265 | ^Z^Zvalue-end | |
6d2ebf8b | 266 | @end smallexample |
c906108c SS |
267 | |
268 | @findex arg-begin | |
269 | @findex arg-name-end | |
270 | @findex arg-value | |
271 | @findex arg-end | |
d700128c | 272 | When @value{GDBN} prints an argument to a function (for example, in the output |
c906108c SS |
273 | from the @code{backtrace} command), it annotates it as follows: |
274 | ||
6d2ebf8b | 275 | @smallexample |
c906108c SS |
276 | ^Z^Zarg-begin |
277 | @var{argument-name} | |
278 | ^Z^Zarg-name-end | |
279 | @var{separator-string} | |
280 | ^Z^Zarg-value @var{value-flags} | |
281 | @var{the-value} | |
282 | ^Z^Zarg-end | |
6d2ebf8b | 283 | @end smallexample |
c906108c | 284 | |
cb51c4e0 | 285 | @noindent |
c906108c SS |
286 | where @var{argument-name} is the name of the argument, |
287 | @var{separator-string} is text which separates the name from the value | |
288 | for the user's benefit (such as @samp{=}), and @var{value-flags} and | |
289 | @var{the-value} have the same meanings as in a | |
290 | @code{value-history-begin} annotation. | |
291 | ||
292 | @findex field-begin | |
293 | @findex field-name-end | |
294 | @findex field-value | |
295 | @findex field-end | |
d700128c | 296 | When printing a structure, @value{GDBN} annotates it as follows: |
c906108c | 297 | |
6d2ebf8b | 298 | @smallexample |
c906108c SS |
299 | ^Z^Zfield-begin @var{value-flags} |
300 | @var{field-name} | |
301 | ^Z^Zfield-name-end | |
302 | @var{separator-string} | |
303 | ^Z^Zfield-value | |
304 | @var{the-value} | |
305 | ^Z^Zfield-end | |
6d2ebf8b | 306 | @end smallexample |
c906108c | 307 | |
cb51c4e0 | 308 | @noindent |
c906108c SS |
309 | where @var{field-name} is the name of the field, @var{separator-string} |
310 | is text which separates the name from the value for the user's benefit | |
311 | (such as @samp{=}), and @var{value-flags} and @var{the-value} have the | |
312 | same meanings as in a @code{value-history-begin} annotation. | |
313 | ||
d700128c | 314 | When printing an array, @value{GDBN} annotates it as follows: |
c906108c | 315 | |
6d2ebf8b | 316 | @smallexample |
c906108c | 317 | ^Z^Zarray-section-begin @var{array-index} @var{value-flags} |
6d2ebf8b | 318 | @end smallexample |
c906108c | 319 | |
cb51c4e0 | 320 | @noindent |
c906108c SS |
321 | where @var{array-index} is the index of the first element being |
322 | annotated and @var{value-flags} has the same meaning as in a | |
323 | @code{value-history-begin} annotation. This is followed by any number | |
324 | of elements, where is element can be either a single element: | |
325 | ||
326 | @findex elt | |
6d2ebf8b | 327 | @smallexample |
c906108c SS |
328 | @samp{,} @var{whitespace} ; @r{omitted for the first element} |
329 | @var{the-value} | |
330 | ^Z^Zelt | |
6d2ebf8b | 331 | @end smallexample |
c906108c SS |
332 | |
333 | or a repeated element | |
334 | ||
335 | @findex elt-rep | |
336 | @findex elt-rep-end | |
6d2ebf8b | 337 | @smallexample |
c906108c SS |
338 | @samp{,} @var{whitespace} ; @r{omitted for the first element} |
339 | @var{the-value} | |
f821f325 | 340 | ^Z^Zelt-rep @var{number-of-repetitions} |
c906108c SS |
341 | @var{repetition-string} |
342 | ^Z^Zelt-rep-end | |
6d2ebf8b | 343 | @end smallexample |
c906108c SS |
344 | |
345 | In both cases, @var{the-value} is the output for the value of the | |
346 | element and @var{whitespace} can contain spaces, tabs, and newlines. In | |
f821f325 | 347 | the repeated case, @var{number-of-repetitions} is the number of |
c906108c SS |
348 | consecutive array elements which contain that value, and |
349 | @var{repetition-string} is a string which is designed to convey to the | |
f821f325 | 350 | user that repetition is being depicted. |
c906108c SS |
351 | |
352 | @findex array-section-end | |
353 | Once all the array elements have been output, the array annotation is | |
354 | ended with | |
355 | ||
6d2ebf8b | 356 | @smallexample |
c906108c | 357 | ^Z^Zarray-section-end |
6d2ebf8b | 358 | @end smallexample |
c906108c | 359 | |
d700128c | 360 | @node Frame Annotations |
e6f672d2 AC |
361 | @chapter Frames |
362 | ||
363 | @emph{Value Annotations have been removed. @sc{gdb/mi} instead provides | |
364 | a number of frame commands.} | |
365 | ||
366 | @emph{Frame annotations are no longer available. The @sc{gdb/mi} | |
367 | provides @samp{-stack-list-arguments}, @samp{-stack-list-locals}, and | |
368 | @samp{-stack-list-frames} commands.} | |
c906108c | 369 | |
d700128c EZ |
370 | @cindex annotations for frames |
371 | Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies | |
372 | to frames printed when @value{GDBN} stops, output from commands such as | |
c906108c SS |
373 | @code{backtrace} or @code{up}, etc. |
374 | ||
375 | @findex frame-begin | |
376 | The frame annotation begins with | |
377 | ||
6d2ebf8b | 378 | @smallexample |
c906108c SS |
379 | ^Z^Zframe-begin @var{level} @var{address} |
380 | @var{level-string} | |
6d2ebf8b | 381 | @end smallexample |
c906108c | 382 | |
cb51c4e0 | 383 | @noindent |
c906108c SS |
384 | where @var{level} is the number of the frame (0 is the innermost frame, |
385 | and other frames have positive numbers), @var{address} is the address of | |
386 | the code executing in that frame, and @var{level-string} is a string | |
387 | designed to convey the level to the user. @var{address} is in the form | |
388 | @samp{0x} followed by one or more lowercase hex digits (note that this | |
389 | does not depend on the language). The frame ends with | |
390 | ||
391 | @findex frame-end | |
6d2ebf8b | 392 | @smallexample |
c906108c | 393 | ^Z^Zframe-end |
6d2ebf8b | 394 | @end smallexample |
c906108c SS |
395 | |
396 | Between these annotations is the main body of the frame, which can | |
397 | consist of | |
398 | ||
399 | @itemize @bullet | |
400 | @item | |
401 | @findex function-call | |
6d2ebf8b | 402 | @smallexample |
c906108c SS |
403 | ^Z^Zfunction-call |
404 | @var{function-call-string} | |
6d2ebf8b | 405 | @end smallexample |
c906108c SS |
406 | |
407 | where @var{function-call-string} is text designed to convey to the user | |
d700128c | 408 | that this frame is associated with a function call made by @value{GDBN} to a |
c906108c SS |
409 | function in the program being debugged. |
410 | ||
411 | @item | |
412 | @findex signal-handler-caller | |
6d2ebf8b | 413 | @smallexample |
c906108c SS |
414 | ^Z^Zsignal-handler-caller |
415 | @var{signal-handler-caller-string} | |
6d2ebf8b | 416 | @end smallexample |
c906108c SS |
417 | |
418 | where @var{signal-handler-caller-string} is text designed to convey to | |
419 | the user that this frame is associated with whatever mechanism is used | |
420 | by this operating system to call a signal handler (it is the frame which | |
421 | calls the signal handler, not the frame for the signal handler itself). | |
422 | ||
423 | @item | |
424 | A normal frame. | |
425 | ||
426 | @findex frame-address | |
427 | @findex frame-address-end | |
428 | This can optionally (depending on whether this is thought of as | |
429 | interesting information for the user to see) begin with | |
430 | ||
6d2ebf8b | 431 | @smallexample |
c906108c SS |
432 | ^Z^Zframe-address |
433 | @var{address} | |
434 | ^Z^Zframe-address-end | |
435 | @var{separator-string} | |
6d2ebf8b | 436 | @end smallexample |
c906108c SS |
437 | |
438 | where @var{address} is the address executing in the frame (the same | |
439 | address as in the @code{frame-begin} annotation, but printed in a form | |
440 | which is intended for user consumption---in particular, the syntax varies | |
441 | depending on the language), and @var{separator-string} is a string | |
442 | intended to separate this address from what follows for the user's | |
443 | benefit. | |
444 | ||
445 | @findex frame-function-name | |
446 | @findex frame-args | |
447 | Then comes | |
448 | ||
6d2ebf8b | 449 | @smallexample |
c906108c SS |
450 | ^Z^Zframe-function-name |
451 | @var{function-name} | |
452 | ^Z^Zframe-args | |
453 | @var{arguments} | |
6d2ebf8b | 454 | @end smallexample |
c906108c SS |
455 | |
456 | where @var{function-name} is the name of the function executing in the | |
457 | frame, or @samp{??} if not known, and @var{arguments} are the arguments | |
458 | to the frame, with parentheses around them (each argument is annotated | |
d700128c | 459 | individually as well, @pxref{Value Annotations}). |
c906108c SS |
460 | |
461 | @findex frame-source-begin | |
462 | @findex frame-source-file | |
463 | @findex frame-source-file-end | |
464 | @findex frame-source-line | |
465 | @findex frame-source-end | |
466 | If source information is available, a reference to it is then printed: | |
467 | ||
6d2ebf8b | 468 | @smallexample |
c906108c SS |
469 | ^Z^Zframe-source-begin |
470 | @var{source-intro-string} | |
471 | ^Z^Zframe-source-file | |
472 | @var{filename} | |
473 | ^Z^Zframe-source-file-end | |
474 | : | |
475 | ^Z^Zframe-source-line | |
476 | @var{line-number} | |
477 | ^Z^Zframe-source-end | |
6d2ebf8b | 478 | @end smallexample |
c906108c SS |
479 | |
480 | where @var{source-intro-string} separates for the user's benefit the | |
481 | reference from the text which precedes it, @var{filename} is the name of | |
482 | the source file, and @var{line-number} is the line number within that | |
483 | file (the first line is line 1). | |
484 | ||
485 | @findex frame-where | |
d700128c | 486 | If @value{GDBN} prints some information about where the frame is from (which |
c906108c SS |
487 | library, which load segment, etc.; currently only done on the RS/6000), |
488 | it is annotated with | |
489 | ||
6d2ebf8b | 490 | @smallexample |
c906108c SS |
491 | ^Z^Zframe-where |
492 | @var{information} | |
6d2ebf8b | 493 | @end smallexample |
c906108c SS |
494 | |
495 | Then, if source is to actually be displayed for this frame (for example, | |
496 | this is not true for output from the @code{backtrace} command), then a | |
a984817e EZ |
497 | @code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike |
498 | most annotations, this is output instead of the normal text which would be | |
c906108c SS |
499 | output, not in addition. |
500 | @end itemize | |
501 | ||
502 | @node Displays | |
e6f672d2 AC |
503 | @chapter Displays |
504 | ||
505 | @emph{Display Annotations have been removed. @sc{gdb/mi} instead | |
506 | provides Variable Objects.} | |
c906108c SS |
507 | |
508 | @findex display-begin | |
509 | @findex display-number-end | |
510 | @findex display-format | |
511 | @findex display-expression | |
512 | @findex display-expression-end | |
513 | @findex display-value | |
514 | @findex display-end | |
d700128c EZ |
515 | @cindex annotations for display |
516 | When @value{GDBN} is told to display something using the @code{display} command, | |
c906108c SS |
517 | the results of the display are annotated: |
518 | ||
6d2ebf8b | 519 | @smallexample |
c906108c SS |
520 | ^Z^Zdisplay-begin |
521 | @var{number} | |
522 | ^Z^Zdisplay-number-end | |
523 | @var{number-separator} | |
524 | ^Z^Zdisplay-format | |
525 | @var{format} | |
526 | ^Z^Zdisplay-expression | |
527 | @var{expression} | |
528 | ^Z^Zdisplay-expression-end | |
529 | @var{expression-separator} | |
530 | ^Z^Zdisplay-value | |
531 | @var{value} | |
532 | ^Z^Zdisplay-end | |
6d2ebf8b | 533 | @end smallexample |
c906108c | 534 | |
cb51c4e0 | 535 | @noindent |
c906108c SS |
536 | where @var{number} is the number of the display, @var{number-separator} |
537 | is intended to separate the number from what follows for the user, | |
538 | @var{format} includes information such as the size, format, or other | |
539 | information about how the value is being displayed, @var{expression} is | |
540 | the expression being displayed, @var{expression-separator} is intended | |
541 | to separate the expression from the text that follows for the user, | |
542 | and @var{value} is the actual value being displayed. | |
543 | ||
544 | @node Prompting | |
e6f672d2 | 545 | @chapter Annotation for @value{GDBN} Input |
c906108c | 546 | |
d700128c EZ |
547 | @cindex annotations for prompts |
548 | When @value{GDBN} prompts for input, it annotates this fact so it is possible | |
c906108c SS |
549 | to know when to send output, when the output from a given command is |
550 | over, etc. | |
551 | ||
552 | Different kinds of input each have a different @dfn{input type}. Each | |
553 | input type has three annotations: a @code{pre-} annotation, which | |
554 | denotes the beginning of any prompt which is being output, a plain | |
555 | annotation, which denotes the end of the prompt, and then a @code{post-} | |
556 | annotation which denotes the end of any echo which may (or may not) be | |
557 | associated with the input. For example, the @code{prompt} input type | |
558 | features the following annotations: | |
559 | ||
6d2ebf8b | 560 | @smallexample |
c906108c SS |
561 | ^Z^Zpre-prompt |
562 | ^Z^Zprompt | |
563 | ^Z^Zpost-prompt | |
6d2ebf8b | 564 | @end smallexample |
c906108c SS |
565 | |
566 | The input types are | |
567 | ||
568 | @table @code | |
569 | @findex pre-prompt | |
570 | @findex prompt | |
571 | @findex post-prompt | |
572 | @item prompt | |
d700128c | 573 | When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). |
c906108c SS |
574 | |
575 | @findex pre-commands | |
576 | @findex commands | |
577 | @findex post-commands | |
578 | @item commands | |
d700128c | 579 | When @value{GDBN} prompts for a set of commands, like in the @code{commands} |
c906108c SS |
580 | command. The annotations are repeated for each command which is input. |
581 | ||
582 | @findex pre-overload-choice | |
583 | @findex overload-choice | |
584 | @findex post-overload-choice | |
585 | @item overload-choice | |
d700128c | 586 | When @value{GDBN} wants the user to select between various overloaded functions. |
c906108c SS |
587 | |
588 | @findex pre-query | |
589 | @findex query | |
590 | @findex post-query | |
591 | @item query | |
d700128c | 592 | When @value{GDBN} wants the user to confirm a potentially dangerous operation. |
c906108c SS |
593 | |
594 | @findex pre-prompt-for-continue | |
595 | @findex prompt-for-continue | |
596 | @findex post-prompt-for-continue | |
597 | @item prompt-for-continue | |
d700128c | 598 | When @value{GDBN} is asking the user to press return to continue. Note: Don't |
c906108c SS |
599 | expect this to work well; instead use @code{set height 0} to disable |
600 | prompting. This is because the counting of lines is buggy in the | |
601 | presence of annotations. | |
602 | @end table | |
603 | ||
604 | @node Errors | |
e6f672d2 | 605 | @chapter Errors |
d700128c | 606 | @cindex annotations for errors, warnings and interrupts |
c906108c SS |
607 | |
608 | @findex quit | |
6d2ebf8b | 609 | @smallexample |
c906108c | 610 | ^Z^Zquit |
6d2ebf8b | 611 | @end smallexample |
c906108c | 612 | |
d700128c | 613 | This annotation occurs right before @value{GDBN} responds to an interrupt. |
c906108c SS |
614 | |
615 | @findex error | |
6d2ebf8b | 616 | @smallexample |
c906108c | 617 | ^Z^Zerror |
6d2ebf8b | 618 | @end smallexample |
c906108c | 619 | |
d700128c | 620 | This annotation occurs right before @value{GDBN} responds to an error. |
c906108c | 621 | |
d700128c | 622 | Quit and error annotations indicate that any annotations which @value{GDBN} was |
c906108c SS |
623 | in the middle of may end abruptly. For example, if a |
624 | @code{value-history-begin} annotation is followed by a @code{error}, one | |
625 | cannot expect to receive the matching @code{value-history-end}. One | |
626 | cannot expect not to receive it either, however; an error annotation | |
d700128c | 627 | does not necessarily mean that @value{GDBN} is immediately returning all the way |
c906108c SS |
628 | to the top level. |
629 | ||
630 | @findex error-begin | |
631 | A quit or error annotation may be preceded by | |
632 | ||
6d2ebf8b | 633 | @smallexample |
c906108c | 634 | ^Z^Zerror-begin |
6d2ebf8b | 635 | @end smallexample |
c906108c SS |
636 | |
637 | Any output between that and the quit or error annotation is the error | |
638 | message. | |
639 | ||
640 | Warning messages are not yet annotated. | |
641 | @c If we want to change that, need to fix warning(), type_error(), | |
642 | @c range_error(), and possibly other places. | |
643 | ||
644 | @node Breakpoint Info | |
e6f672d2 AC |
645 | @chapter Information on Breakpoints |
646 | ||
647 | @emph{Breakpoint Annotations have been removed. @sc{gdb/mi} instead | |
648 | provides breakpoint commands.} | |
c906108c | 649 | |
d700128c | 650 | @cindex annotations for breakpoints |
c906108c SS |
651 | The output from the @code{info breakpoints} command is annotated as follows: |
652 | ||
653 | @findex breakpoints-headers | |
654 | @findex breakpoints-table | |
6d2ebf8b | 655 | @smallexample |
c906108c SS |
656 | ^Z^Zbreakpoints-headers |
657 | @var{header-entry} | |
658 | ^Z^Zbreakpoints-table | |
6d2ebf8b | 659 | @end smallexample |
c906108c | 660 | |
cb51c4e0 | 661 | @noindent |
c906108c SS |
662 | where @var{header-entry} has the same syntax as an entry (see below) but |
663 | instead of containing data, it contains strings which are intended to | |
664 | convey the meaning of each field to the user. This is followed by any | |
665 | number of entries. If a field does not apply for this entry, it is | |
666 | omitted. Fields may contain trailing whitespace. Each entry consists | |
667 | of: | |
668 | ||
669 | @findex record | |
670 | @findex field | |
6d2ebf8b | 671 | @smallexample |
c906108c SS |
672 | ^Z^Zrecord |
673 | ^Z^Zfield 0 | |
674 | @var{number} | |
675 | ^Z^Zfield 1 | |
676 | @var{type} | |
677 | ^Z^Zfield 2 | |
678 | @var{disposition} | |
679 | ^Z^Zfield 3 | |
680 | @var{enable} | |
681 | ^Z^Zfield 4 | |
682 | @var{address} | |
683 | ^Z^Zfield 5 | |
684 | @var{what} | |
685 | ^Z^Zfield 6 | |
686 | @var{frame} | |
687 | ^Z^Zfield 7 | |
688 | @var{condition} | |
689 | ^Z^Zfield 8 | |
690 | @var{ignore-count} | |
691 | ^Z^Zfield 9 | |
692 | @var{commands} | |
6d2ebf8b | 693 | @end smallexample |
c906108c SS |
694 | |
695 | Note that @var{address} is intended for user consumption---the syntax | |
696 | varies depending on the language. | |
697 | ||
698 | The output ends with | |
699 | ||
700 | @findex breakpoints-table-end | |
6d2ebf8b | 701 | @smallexample |
c906108c | 702 | ^Z^Zbreakpoints-table-end |
6d2ebf8b | 703 | @end smallexample |
c906108c SS |
704 | |
705 | @node Invalidation | |
e6f672d2 | 706 | @chapter Invalidation Notices |
c906108c | 707 | |
d700128c | 708 | @cindex annotations for invalidation messages |
c906108c SS |
709 | The following annotations say that certain pieces of state may have |
710 | changed. | |
711 | ||
712 | @table @code | |
713 | @findex frames-invalid | |
714 | @item ^Z^Zframes-invalid | |
715 | ||
716 | The frames (for example, output from the @code{backtrace} command) may | |
717 | have changed. | |
718 | ||
719 | @findex breakpoints-invalid | |
720 | @item ^Z^Zbreakpoints-invalid | |
721 | ||
722 | The breakpoints may have changed. For example, the user just added or | |
723 | deleted a breakpoint. | |
724 | @end table | |
725 | ||
d700128c | 726 | @node Annotations for Running |
e6f672d2 | 727 | @chapter Running the Program |
d700128c | 728 | @cindex annotations for running programs |
c906108c SS |
729 | |
730 | @findex starting | |
731 | @findex stopping | |
d700128c | 732 | When the program starts executing due to a @value{GDBN} command such as |
c906108c SS |
733 | @code{step} or @code{continue}, |
734 | ||
6d2ebf8b | 735 | @smallexample |
c906108c | 736 | ^Z^Zstarting |
6d2ebf8b | 737 | @end smallexample |
c906108c SS |
738 | |
739 | is output. When the program stops, | |
740 | ||
6d2ebf8b | 741 | @smallexample |
c906108c | 742 | ^Z^Zstopped |
6d2ebf8b | 743 | @end smallexample |
c906108c SS |
744 | |
745 | is output. Before the @code{stopped} annotation, a variety of | |
746 | annotations describe how the program stopped. | |
747 | ||
748 | @table @code | |
749 | @findex exited | |
750 | @item ^Z^Zexited @var{exit-status} | |
751 | The program exited, and @var{exit-status} is the exit status (zero for | |
752 | successful exit, otherwise nonzero). | |
753 | ||
754 | @findex signalled | |
755 | @findex signal-name | |
756 | @findex signal-name-end | |
757 | @findex signal-string | |
758 | @findex signal-string-end | |
759 | @item ^Z^Zsignalled | |
760 | The program exited with a signal. After the @code{^Z^Zsignalled}, the | |
761 | annotation continues: | |
762 | ||
6d2ebf8b | 763 | @smallexample |
c906108c SS |
764 | @var{intro-text} |
765 | ^Z^Zsignal-name | |
766 | @var{name} | |
767 | ^Z^Zsignal-name-end | |
768 | @var{middle-text} | |
769 | ^Z^Zsignal-string | |
770 | @var{string} | |
771 | ^Z^Zsignal-string-end | |
772 | @var{end-text} | |
6d2ebf8b | 773 | @end smallexample |
c906108c | 774 | |
cb51c4e0 | 775 | @noindent |
c906108c SS |
776 | where @var{name} is the name of the signal, such as @code{SIGILL} or |
777 | @code{SIGSEGV}, and @var{string} is the explanation of the signal, such | |
778 | as @code{Illegal Instruction} or @code{Segmentation fault}. | |
779 | @var{intro-text}, @var{middle-text}, and @var{end-text} are for the | |
780 | user's benefit and have no particular format. | |
781 | ||
782 | @findex signal | |
783 | @item ^Z^Zsignal | |
d700128c | 784 | The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is |
c906108c SS |
785 | just saying that the program received the signal, not that it was |
786 | terminated with it. | |
787 | ||
788 | @findex breakpoint | |
789 | @item ^Z^Zbreakpoint @var{number} | |
790 | The program hit breakpoint number @var{number}. | |
791 | ||
792 | @findex watchpoint | |
793 | @item ^Z^Zwatchpoint @var{number} | |
794 | The program hit watchpoint number @var{number}. | |
795 | @end table | |
796 | ||
d700128c | 797 | @node Source Annotations |
e6f672d2 | 798 | @chapter Displaying Source |
d700128c | 799 | @cindex annotations for source display |
c906108c SS |
800 | |
801 | @findex source | |
802 | The following annotation is used instead of displaying source code: | |
803 | ||
6d2ebf8b | 804 | @smallexample |
c906108c | 805 | ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} |
6d2ebf8b | 806 | @end smallexample |
c906108c SS |
807 | |
808 | where @var{filename} is an absolute file name indicating which source | |
809 | file, @var{line} is the line number within that file (where 1 is the | |
810 | first line in the file), @var{character} is the character position | |
811 | within the file (where 0 is the first character in the file) (for most | |
812 | debug formats this will necessarily point to the beginning of a line), | |
813 | @var{middle} is @samp{middle} if @var{addr} is in the middle of the | |
814 | line, or @samp{beg} if @var{addr} is at the beginning of the line, and | |
815 | @var{addr} is the address in the target program associated with the | |
816 | source which is being displayed. @var{addr} is in the form @samp{0x} | |
817 | followed by one or more lowercase hex digits (note that this does not | |
818 | depend on the language). | |
819 | ||
17314269 NR |
820 | @node Multi-threaded Apps |
821 | @chapter Multi-threaded Applications | |
822 | @cindex annotations for multi-threaded apps | |
823 | ||
aeac2181 | 824 | The following annotations report thread related changes of state. |
17314269 | 825 | |
aeac2181 NR |
826 | @table @code |
827 | @findex new-thread@r{, annotation} | |
828 | @item ^Z^Znew-thread | |
17314269 NR |
829 | |
830 | This annotation is issued once for each thread that is created apart from | |
831 | the main thread, which is not reported. | |
832 | ||
aeac2181 NR |
833 | @findex thread-changed@r{, annotation} |
834 | @item ^Z^Zthread-changed | |
835 | ||
836 | The selected thread has changed. This may occur at the request of the | |
837 | user with the @code{thread} command, or as a result of execution, | |
838 | e.g., another thread hits a breakpoint. | |
839 | ||
840 | @end table | |
841 | ||
e4c0cfae SS |
842 | @node GNU Free Documentation License |
843 | @appendix GNU Free Documentation License | |
e6f672d2 | 844 | @include fdl.texi |
c906108c | 845 | |
d700128c | 846 | @ignore |
c906108c SS |
847 | @node Index |
848 | @unnumbered Index | |
849 | ||
850 | @printindex fn | |
d700128c | 851 | @end ignore |
c906108c | 852 | |
e6f672d2 | 853 | @bye |