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