1 This is gdb.info, produced by makeinfo version 5.1 from gdb.texinfo.
3 Copyright (C) 1988-2014 Free Software Foundation, Inc.
5 Permission is granted to copy, distribute and/or modify this document
6 under the terms of the GNU Free Documentation License, Version 1.3 or
7 any later version published by the Free Software Foundation; with the
8 Invariant Sections being "Free Software" and "Free Software Needs Free
9 Documentation", with the Front-Cover Texts being "A GNU Manual," and
10 with the Back-Cover Texts as in (a) below.
12 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
13 this GNU Manual. Buying copies from GNU Press supports the FSF in
14 developing GNU and promoting software freedom."
15 INFO-DIR-SECTION Software development
17 * Gdb: (gdb). The GNU debugger.
18 * gdbserver: (gdb) Server. The GNU debugging server.
22 File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data
24 10.4 Artificial Arrays
25 ======================
27 It is often useful to print out several successive objects of the same
28 type in memory; a section of an array, or an array of dynamically
29 determined size for which only a pointer exists in the program.
31 You can do this by referring to a contiguous span of memory as an
32 "artificial array", using the binary operator '@'. The left operand of
33 '@' should be the first element of the desired array and be an
34 individual object. The right operand should be the desired length of
35 the array. The result is an array value whose elements are all of the
36 type of the left argument. The first element is actually the left
37 argument; the second element comes from bytes of memory immediately
38 following those that hold the first element, and so on. Here is an
39 example. If a program says
41 int *array = (int *) malloc (len * sizeof (int));
43 you can print the contents of 'array' with
47 The left operand of '@' must reside in memory. Array values made
48 with '@' in this way behave just like other arrays in terms of
49 subscripting, and are coerced to pointers when used in expressions.
50 Artificial arrays most often appear in expressions via the value history
51 (*note Value History: Value History.), after printing one out.
53 Another way to create an artificial array is to use a cast. This
54 re-interprets a value as if it were an array. The value need not be in
56 (gdb) p/x (short[2])0x12345678
59 As a convenience, if you leave the array length out (as in
60 '(TYPE[])VALUE') GDB calculates the size to fill the value (as
61 'sizeof(VALUE)/sizeof(TYPE)':
62 (gdb) p/x (short[])0x12345678
65 Sometimes the artificial array mechanism is not quite enough; in
66 moderately complex data structures, the elements of interest may not
67 actually be adjacent--for example, if you are interested in the values
68 of pointers in an array. One useful work-around in this situation is to
69 use a convenience variable (*note Convenience Variables: Convenience
70 Vars.) as a counter in an expression that prints the first interesting
71 value, and then repeat that expression via <RET>. For instance, suppose
72 you have an array 'dtab' of pointers to structures, and you are
73 interested in the values of a field 'fv' in each structure. Here is an
74 example of what you might type:
83 File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data
88 By default, GDB prints a value according to its data type. Sometimes
89 this is not what you want. For example, you might want to print a
90 number in hex, or a pointer in decimal. Or you might want to view data
91 in memory at a certain address as a character string or as an
92 instruction. To do these things, specify an "output format" when you
95 The simplest use of output formats is to say how to print a value
96 already computed. This is done by starting the arguments of the 'print'
97 command with a slash and a format letter. The format letters supported
101 Regard the bits of the value as an integer, and print the integer
105 Print as integer in signed decimal.
108 Print as integer in unsigned decimal.
111 Print as integer in octal.
114 Print as integer in binary. The letter 't' stands for "two". (1)
117 Print as an address, both absolute in hexadecimal and as an offset
118 from the nearest preceding symbol. You can use this format used to
119 discover where (in what function) an unknown address is located:
122 $3 = 0x54320 <_initialize_vx+396>
124 The command 'info symbol 0x54320' yields similar results. *Note
125 info symbol: Symbols.
128 Regard as an integer and print it as a character constant. This
129 prints both the numerical value and its character representation.
130 The character representation is replaced with the octal escape
131 '\nnn' for characters outside the 7-bit ASCII range.
133 Without this format, GDB displays 'char', 'unsigned char', and 'signed char'
134 data as character constants. Single-byte members of vectors are
135 displayed as integer data.
138 Regard the bits of the value as a floating point number and print
139 using typical floating point syntax.
142 Regard as a string, if possible. With this format, pointers to
143 single-byte data are displayed as null-terminated strings and
144 arrays of single-byte data are displayed as fixed-length strings.
145 Other values are displayed in their natural types.
147 Without this format, GDB displays pointers to and arrays of 'char',
148 'unsigned char', and 'signed char' as strings. Single-byte members
149 of a vector are displayed as an integer array.
152 Like 'x' formatting, the value is treated as an integer and printed
153 as hexadecimal, but leading zeros are printed to pad the value to
154 the size of the integer type.
157 Print using the 'raw' formatting. By default, GDB will use a
158 Python-based pretty-printer, if one is available (*note Pretty
159 Printing::). This typically results in a higher-level display of
160 the value's contents. The 'r' format bypasses any Python
161 pretty-printer which might exist.
163 For example, to print the program counter in hex (*note Registers::),
168 Note that no space is required before the slash; this is because command
169 names in GDB cannot contain a slash.
171 To reprint the last value in the value history with a different
172 format, you can use the 'print' command with just a format and no
173 expression. For example, 'p/x' reprints the last value in hex.
175 ---------- Footnotes ----------
177 (1) 'b' cannot be used because these format letters are also used
178 with the 'x' command, where 'b' stands for "byte"; see *note Examining
182 File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data
184 10.6 Examining Memory
185 =====================
187 You can use the command 'x' (for "examine") to examine memory in any of
188 several formats, independently of your program's data types.
193 Use the 'x' command to examine memory.
195 N, F, and U are all optional parameters that specify how much memory
196 to display and how to format it; ADDR is an expression giving the
197 address where you want to start displaying memory. If you use defaults
198 for NFU, you need not type the slash '/'. Several commands set
199 convenient defaults for ADDR.
202 The repeat count is a decimal integer; the default is 1. It
203 specifies how much memory (counting by units U) to display.
205 F, the display format
206 The display format is one of the formats used by 'print' ('x', 'd',
207 'u', 'o', 't', 'a', 'c', 'f', 's'), and in addition 'i' (for
208 machine instructions). The default is 'x' (hexadecimal) initially.
209 The default changes each time you use either 'x' or 'print'.
212 The unit size is any of
217 Halfwords (two bytes).
219 Words (four bytes). This is the initial default.
221 Giant words (eight bytes).
223 Each time you specify a unit size with 'x', that size becomes the
224 default unit the next time you use 'x'. For the 'i' format, the
225 unit size is ignored and is normally not written. For the 's'
226 format, the unit size defaults to 'b', unless it is explicitly
227 given. Use 'x /hs' to display 16-bit char strings and 'x /ws' to
228 display 32-bit strings. The next use of 'x /s' will again display
229 8-bit strings. Note that the results depend on the programming
230 language of the current compilation unit. If the language is C,
231 the 's' modifier will use the UTF-16 encoding while 'w' will use
232 UTF-32. The encoding is set by the programming language and cannot
235 ADDR, starting display address
236 ADDR is the address where you want GDB to begin displaying memory.
237 The expression need not have a pointer value (though it may); it is
238 always interpreted as an integer address of a byte of memory.
239 *Note Expressions: Expressions, for more information on
240 expressions. The default for ADDR is usually just after the last
241 address examined--but several other commands also set the default
242 address: 'info breakpoints' (to the address of the last breakpoint
243 listed), 'info line' (to the starting address of a line), and
244 'print' (if you use it to display a value from memory).
246 For example, 'x/3uh 0x54320' is a request to display three halfwords
247 ('h') of memory, formatted as unsigned decimal integers ('u'), starting
248 at address '0x54320'. 'x/4xw $sp' prints the four words ('w') of memory
249 above the stack pointer (here, '$sp'; *note Registers: Registers.) in
252 Since the letters indicating unit sizes are all distinct from the
253 letters specifying output formats, you do not have to remember whether
254 unit size or format comes first; either order works. The output
255 specifications '4xw' and '4wx' mean exactly the same thing. (However,
256 the count N must come first; 'wx4' does not work.)
258 Even though the unit size U is ignored for the formats 's' and 'i',
259 you might still want to use a count N; for example, '3i' specifies that
260 you want to see three machine instructions, including any operands. For
261 convenience, especially when used with the 'display' command, the 'i'
262 format also prints branch delay slot instructions, if any, beyond the
263 count specified, which immediately follow the last instruction that is
264 within the count. The command 'disassemble' gives an alternative way of
265 inspecting machine instructions; see *note Source and Machine Code:
268 All the defaults for the arguments to 'x' are designed to make it
269 easy to continue scanning memory with minimal specifications each time
270 you use 'x'. For example, after you have inspected three machine
271 instructions with 'x/3i ADDR', you can inspect the next seven with just
272 'x/7'. If you use <RET> to repeat the 'x' command, the repeat count N
273 is used again; the other arguments default as for successive uses of
276 When examining machine instructions, the instruction at current
277 program counter is shown with a '=>' marker. For example:
280 0x804837f <main+11>: mov %esp,%ebp
281 0x8048381 <main+13>: push %ecx
282 0x8048382 <main+14>: sub $0x4,%esp
283 => 0x8048385 <main+17>: movl $0x8048460,(%esp)
284 0x804838c <main+24>: call 0x80482d4 <puts@plt>
286 The addresses and contents printed by the 'x' command are not saved
287 in the value history because there is often too much of them and they
288 would get in the way. Instead, GDB makes these values available for
289 subsequent use in expressions as values of the convenience variables
290 '$_' and '$__'. After an 'x' command, the last address examined is
291 available for use in expressions in the convenience variable '$_'. The
292 contents of that address, as examined, are available in the convenience
295 If the 'x' command has a repeat count, the address and contents saved
296 are from the last memory unit printed; this is not the same as the last
297 address printed if several units were printed on the last line of
300 When you are debugging a program running on a remote target machine
301 (*note Remote Debugging::), you may wish to verify the program's image
302 in the remote machine's memory against the executable file you
303 downloaded to the target. The 'compare-sections' command is provided
306 'compare-sections [SECTION-NAME]'
307 Compare the data of a loadable section SECTION-NAME in the
308 executable file of the program being debugged with the same section
309 in the remote machine's memory, and report any mismatches. With no
310 arguments, compares all loadable sections. This command's
311 availability depends on the target's support for the '"qCRC"'
315 File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data
317 10.7 Automatic Display
318 ======================
320 If you find that you want to print the value of an expression frequently
321 (to see how it changes), you might want to add it to the "automatic
322 display list" so that GDB prints its value each time your program stops.
323 Each expression added to the list is given a number to identify it; to
324 remove an expression from the list, you specify that number. The
325 automatic display looks like this:
328 3: bar[5] = (struct hack *) 0x3804
330 This display shows item numbers, expressions and their current values.
331 As with displays you request manually using 'x' or 'print', you can
332 specify the output format you prefer; in fact, 'display' decides whether
333 to use 'print' or 'x' depending your format specification--it uses 'x'
334 if you specify either the 'i' or 's' format, or a unit size; otherwise
338 Add the expression EXPR to the list of expressions to display each
339 time your program stops. *Note Expressions: Expressions.
341 'display' does not repeat if you press <RET> again after using it.
344 For FMT specifying only a display format and not a size or count,
345 add the expression EXPR to the auto-display list but arrange to
346 display it each time in the specified format FMT. *Note Output
347 Formats: Output Formats.
350 For FMT 'i' or 's', or including a unit-size or a number of units,
351 add the expression ADDR as a memory address to be examined each
352 time your program stops. Examining means in effect doing 'x/FMT
353 ADDR'. *Note Examining Memory: Memory.
355 For example, 'display/i $pc' can be helpful, to see the machine
356 instruction about to be executed each time execution stops ('$pc' is a
357 common name for the program counter; *note Registers: Registers.).
360 'delete display DNUMS...'
361 Remove items from the list of expressions to display. Specify the
362 numbers of the displays that you want affected with the command
363 argument DNUMS. It can be a single display number, one of the
364 numbers shown in the first field of the 'info display' display; or
365 it could be a range of display numbers, as in '2-4'.
367 'undisplay' does not repeat if you press <RET> after using it.
368 (Otherwise you would just get the error 'No display number ...'.)
370 'disable display DNUMS...'
371 Disable the display of item numbers DNUMS. A disabled display item
372 is not printed automatically, but is not forgotten. It may be
373 enabled again later. Specify the numbers of the displays that you
374 want affected with the command argument DNUMS. It can be a single
375 display number, one of the numbers shown in the first field of the
376 'info display' display; or it could be a range of display numbers,
379 'enable display DNUMS...'
380 Enable display of item numbers DNUMS. It becomes effective once
381 again in auto display of its expression, until you specify
382 otherwise. Specify the numbers of the displays that you want
383 affected with the command argument DNUMS. It can be a single
384 display number, one of the numbers shown in the first field of the
385 'info display' display; or it could be a range of display numbers,
389 Display the current values of the expressions on the list, just as
390 is done when your program stops.
393 Print the list of expressions previously set up to display
394 automatically, each one with its item number, but without showing
395 the values. This includes disabled expressions, which are marked
396 as such. It also includes expressions which would not be displayed
397 right now because they refer to automatic variables not currently
400 If a display expression refers to local variables, then it does not
401 make sense outside the lexical context for which it was set up. Such an
402 expression is disabled when execution enters a context where one of its
403 variables is not defined. For example, if you give the command 'display
404 last_char' while inside a function with an argument 'last_char', GDB
405 displays this argument while your program continues to stop inside that
406 function. When it stops elsewhere--where there is no variable
407 'last_char'--the display is disabled automatically. The next time your
408 program stops where 'last_char' is meaningful, you can enable the
409 display expression once again.
412 File: gdb.info, Node: Print Settings, Next: Pretty Printing, Prev: Auto Display, Up: Data
417 GDB provides the following ways to control how arrays, structures, and
420 These settings are useful for debugging programs in any language:
423 'set print address on'
424 GDB prints memory addresses showing the location of stack traces,
425 structure values, pointer values, breakpoints, and so forth, even
426 when it also displays the contents of those addresses. The default
427 is 'on'. For example, this is what a stack frame display looks
428 like with 'set print address on':
431 #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
433 530 if (lquote != def_lquote)
435 'set print address off'
436 Do not print addresses when displaying their contents. For
437 example, this is the same stack frame displayed with 'set print
440 (gdb) set print addr off
442 #0 set_quotes (lq="<<", rq=">>") at input.c:530
443 530 if (lquote != def_lquote)
445 You can use 'set print address off' to eliminate all machine
446 dependent displays from the GDB interface. For example, with
447 'print address off', you should get the same text for backtraces on
448 all machines--whether or not they involve pointer arguments.
451 Show whether or not addresses are to be printed.
453 When GDB prints a symbolic address, it normally prints the closest
454 earlier symbol plus an offset. If that symbol does not uniquely
455 identify the address (for example, it is a name whose scope is a single
456 source file), you may need to clarify. One way to do this is with 'info
457 line', for example 'info line *0x4537'. Alternately, you can set GDB to
458 print the source file and line number when it prints a symbolic address:
460 'set print symbol-filename on'
461 Tell GDB to print the source file name and line number of a symbol
462 in the symbolic form of an address.
464 'set print symbol-filename off'
465 Do not print source file name and line number of a symbol. This is
468 'show print symbol-filename'
469 Show whether or not GDB will print the source file name and line
470 number of a symbol in the symbolic form of an address.
472 Another situation where it is helpful to show symbol filenames and
473 line numbers is when disassembling code; GDB shows you the line number
474 and source file that corresponds to each instruction.
476 Also, you may wish to see the symbolic form only if the address being
477 printed is reasonably close to the closest earlier symbol:
479 'set print max-symbolic-offset MAX-OFFSET'
480 'set print max-symbolic-offset unlimited'
481 Tell GDB to only display the symbolic form of an address if the
482 offset between the closest earlier symbol and the address is less
483 than MAX-OFFSET. The default is 'unlimited', which tells GDB to
484 always print the symbolic form of an address if any symbol precedes
485 it. Zero is equivalent to 'unlimited'.
487 'show print max-symbolic-offset'
488 Ask how large the maximum offset is that GDB prints in a symbolic
491 If you have a pointer and you are not sure where it points, try 'set
492 print symbol-filename on'. Then you can determine the name and source
493 file location of the variable where it points, using 'p/a POINTER'.
494 This interprets the address in symbolic form. For example, here GDB
495 shows that a variable 'ptt' points at another variable 't', defined in
498 (gdb) set print symbol-filename on
500 $4 = 0xe008 <t in hi2.c>
502 _Warning:_ For pointers that point to a local variable, 'p/a' does
503 not show the symbol name and filename of the referent, even with
504 the appropriate 'set print' options turned on.
506 You can also enable '/a'-like formatting all the time using 'set
509 'set print symbol on'
510 Tell GDB to print the symbol corresponding to an address, if one
513 'set print symbol off'
514 Tell GDB not to print the symbol corresponding to an address. In
515 this mode, GDB will still print the symbol corresponding to
516 pointers to functions. This is the default.
519 Show whether GDB will display the symbol corresponding to an
522 Other settings control how different kinds of objects are printed:
526 Pretty print arrays. This format is more convenient to read, but
527 uses more space. The default is off.
529 'set print array off'
530 Return to compressed format for arrays.
533 Show whether compressed or pretty format is selected for displaying
536 'set print array-indexes'
537 'set print array-indexes on'
538 Print the index of each element when displaying arrays. May be
539 more convenient to locate a given element in the array or quickly
540 find the index of a given element in that printed array. The
543 'set print array-indexes off'
544 Stop printing element indexes when displaying arrays.
546 'show print array-indexes'
547 Show whether the index of each element is printed when displaying
550 'set print elements NUMBER-OF-ELEMENTS'
551 'set print elements unlimited'
552 Set a limit on how many elements of an array GDB will print. If
553 GDB is printing a large array, it stops printing after it has
554 printed the number of elements set by the 'set print elements'
555 command. This limit also applies to the display of strings. When
556 GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS
557 to 'unlimited' or zero means that the number of elements to print
560 'show print elements'
561 Display the number of elements of a large array that GDB will
562 print. If the number is 0, then the printing is unlimited.
564 'set print frame-arguments VALUE'
565 This command allows to control how the values of arguments are
566 printed when the debugger prints a frame (*note Frames::). The
570 The values of all arguments are printed.
573 Print the value of an argument only if it is a scalar. The
574 value of more complex arguments such as arrays, structures,
575 unions, etc, is replaced by '...'. This is the default. Here
576 is an example where only scalar arguments are shown:
578 #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green)
582 None of the argument values are printed. Instead, the value
583 of each argument is replaced by '...'. In this case, the
584 example above now becomes:
586 #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...)
589 By default, only scalar arguments are printed. This command can be
590 used to configure the debugger to print the value of all arguments,
591 regardless of their type. However, it is often advantageous to not
592 print the value of more complex parameters. For instance, it
593 reduces the amount of information printed in each frame, making the
594 backtrace more readable. Also, it improves performance when
595 displaying Ada frames, because the computation of large arguments
596 can sometimes be CPU-intensive, especially in large applications.
597 Setting 'print frame-arguments' to 'scalars' (the default) or
598 'none' avoids this computation, thus speeding up the display of
601 'show print frame-arguments'
602 Show how the value of arguments should be displayed when printing a
605 'set print raw frame-arguments on'
606 Print frame arguments in raw, non pretty-printed, form.
608 'set print raw frame-arguments off'
609 Print frame arguments in pretty-printed form, if there is a
610 pretty-printer for the value (*note Pretty Printing::), otherwise
611 print the value in raw form. This is the default.
613 'show print raw frame-arguments'
614 Show whether to print frame arguments in raw form.
616 'set print entry-values VALUE'
617 Set printing of frame argument values at function entry. In some
618 cases GDB can determine the value of function argument which was
619 passed by the function caller, even if the value was modified
620 inside the called function and therefore is different. With
621 optimized code, the current value could be unavailable, but the
622 entry value may still be known.
624 The default value is 'default' (see below for its description).
625 Older GDB behaved as with the setting 'no'. Compilers not
626 supporting this feature will behave in the 'default' setting the
627 same way as with the 'no' setting.
629 This functionality is currently supported only by DWARF 2 debugging
630 format and the compiler has to produce 'DW_TAG_GNU_call_site' tags.
631 With GCC, you need to specify '-O -g' during compilation, to get
634 The VALUE parameter can be one of the following:
637 Print only actual parameter values, never print values from
638 function entry point.
641 #0 lost (val=<optimized out>)
643 #0 invalid (val=<optimized out>)
646 Print only parameter values from function entry point. The
647 actual parameter values are never printed.
648 #0 equal (val@entry=5)
649 #0 different (val@entry=5)
650 #0 lost (val@entry=5)
651 #0 born (val@entry=<optimized out>)
652 #0 invalid (val@entry=<optimized out>)
655 Print only parameter values from function entry point. If
656 value from function entry point is not known while the actual
657 value is known, print the actual value for such parameter.
658 #0 equal (val@entry=5)
659 #0 different (val@entry=5)
660 #0 lost (val@entry=5)
662 #0 invalid (val@entry=<optimized out>)
665 Print actual parameter values. If actual parameter value is
666 not known while value from function entry point is known,
667 print the entry point value for such parameter.
670 #0 lost (val@entry=5)
672 #0 invalid (val=<optimized out>)
675 Always print both the actual parameter value and its value
676 from function entry point, even if values of one or both are
677 not available due to compiler optimizations.
678 #0 equal (val=5, val@entry=5)
679 #0 different (val=6, val@entry=5)
680 #0 lost (val=<optimized out>, val@entry=5)
681 #0 born (val=10, val@entry=<optimized out>)
682 #0 invalid (val=<optimized out>, val@entry=<optimized out>)
685 Print the actual parameter value if it is known and also its
686 value from function entry point if it is known. If neither is
687 known, print for the actual value '<optimized out>'. If not
688 in MI mode (*note GDB/MI::) and if both values are known and
689 identical, print the shortened 'param=param@entry=VALUE'
691 #0 equal (val=val@entry=5)
692 #0 different (val=6, val@entry=5)
693 #0 lost (val@entry=5)
695 #0 invalid (val=<optimized out>)
698 Always print the actual parameter value. Print also its value
699 from function entry point, but only if it is known. If not in
700 MI mode (*note GDB/MI::) and if both values are known and
701 identical, print the shortened 'param=param@entry=VALUE'
703 #0 equal (val=val@entry=5)
704 #0 different (val=6, val@entry=5)
705 #0 lost (val=<optimized out>, val@entry=5)
707 #0 invalid (val=<optimized out>)
709 For analysis messages on possible failures of frame argument values
710 at function entry resolution see *note set debug entry-values::.
712 'show print entry-values'
713 Show the method being used for printing of frame argument values at
716 'set print repeats NUMBER-OF-REPEATS'
717 'set print repeats unlimited'
718 Set the threshold for suppressing display of repeated array
719 elements. When the number of consecutive identical elements of an
720 array exceeds the threshold, GDB prints the string '"<repeats N
721 times>"', where N is the number of identical repetitions, instead
722 of displaying the identical elements themselves. Setting the
723 threshold to 'unlimited' or zero will cause all elements to be
724 individually printed. The default threshold is 10.
727 Display the current threshold for printing repeated identical
730 'set print null-stop'
731 Cause GDB to stop printing the characters of an array when the
732 first NULL is encountered. This is useful when large arrays
733 actually contain only short strings. The default is off.
735 'show print null-stop'
736 Show whether GDB stops printing an array on the first NULL
739 'set print pretty on'
740 Cause GDB to print structures in an indented format with one member
752 'set print pretty off'
753 Cause GDB to print structures in a compact format, like this:
755 $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \
758 This is the default format.
761 Show which format GDB is using to print structures.
763 'set print sevenbit-strings on'
764 Print using only seven-bit characters; if this option is set, GDB
765 displays any eight-bit characters (in strings or character values)
766 using the notation '\'NNN. This setting is best if you are working
767 in English (ASCII) and you use the high-order bit of characters as
768 a marker or "meta" bit.
770 'set print sevenbit-strings off'
771 Print full eight-bit characters. This allows the use of more
772 international character sets, and is the default.
774 'show print sevenbit-strings'
775 Show whether or not GDB is printing only seven-bit characters.
778 Tell GDB to print unions which are contained in structures and
779 other unions. This is the default setting.
781 'set print union off'
782 Tell GDB not to print unions which are contained in structures and
783 other unions. GDB will print '"{...}"' instead.
786 Ask GDB whether or not it will print unions which are contained in
787 structures and other unions.
789 For example, given the declarations
791 typedef enum {Tree, Bug} Species;
792 typedef enum {Big_tree, Acorn, Seedling} Tree_forms;
793 typedef enum {Caterpillar, Cocoon, Butterfly}
804 struct thing foo = {Tree, {Acorn}};
806 with 'set print union on' in effect 'p foo' would print
808 $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}}
810 and with 'set print union off' in effect it would print
812 $1 = {it = Tree, form = {...}}
814 'set print union' affects programs written in C-like languages and
817 These settings are of interest when debugging C++ programs:
820 'set print demangle on'
821 Print C++ names in their source form rather than in the encoded
822 ("mangled") form passed to the assembler and linker for type-safe
823 linkage. The default is on.
825 'show print demangle'
826 Show whether C++ names are printed in mangled or demangled form.
828 'set print asm-demangle'
829 'set print asm-demangle on'
830 Print C++ names in their source form rather than their mangled
831 form, even in assembler code printouts such as instruction
832 disassemblies. The default is off.
834 'show print asm-demangle'
835 Show whether C++ names in assembly listings are printed in mangled
838 'set demangle-style STYLE'
839 Choose among several encoding schemes used by different compilers
840 to represent C++ names. The choices for STYLE are currently:
843 Allow GDB to choose a decoding style by inspecting your
844 program. This is the default.
847 Decode based on the GNU C++ compiler ('g++') encoding
851 Decode based on the HP ANSI C++ ('aCC') encoding algorithm.
854 Decode based on the Lucid C++ compiler ('lcc') encoding
858 Decode using the algorithm in the 'C++ Annotated Reference
859 Manual'. *Warning:* this setting alone is not sufficient to
860 allow debugging 'cfront'-generated executables. GDB would
861 require further enhancement to permit that.
863 If you omit STYLE, you will see a list of possible formats.
865 'show demangle-style'
866 Display the encoding style currently in use for decoding C++
870 'set print object on'
871 When displaying a pointer to an object, identify the _actual_
872 (derived) type of the object rather than the _declared_ type, using
873 the virtual function table. Note that the virtual function table
874 is required--this feature can only work for objects that have
875 run-time type identification; a single virtual method in the
876 object's declared type is sufficient. Note that this setting is
877 also taken into account when working with variable objects via MI
880 'set print object off'
881 Display only the declared type of objects, without reference to the
882 virtual function table. This is the default setting.
885 Show whether actual, or declared, object types are displayed.
887 'set print static-members'
888 'set print static-members on'
889 Print static members when displaying a C++ object. The default is
892 'set print static-members off'
893 Do not print static members when displaying a C++ object.
895 'show print static-members'
896 Show whether C++ static members are printed or not.
898 'set print pascal_static-members'
899 'set print pascal_static-members on'
900 Print static members when displaying a Pascal object. The default
903 'set print pascal_static-members off'
904 Do not print static members when displaying a Pascal object.
906 'show print pascal_static-members'
907 Show whether Pascal static members are printed or not.
911 Pretty print C++ virtual function tables. The default is off.
912 (The 'vtbl' commands do not work on programs compiled with the HP
913 ANSI C++ compiler ('aCC').)
916 Do not pretty print C++ virtual function tables.
919 Show whether C++ virtual function tables are pretty printed, or
923 File: gdb.info, Node: Pretty Printing, Next: Value History, Prev: Print Settings, Up: Data
928 GDB provides a mechanism to allow pretty-printing of values using Python
929 code. It greatly simplifies the display of complex objects. This
930 mechanism works for both MI and the CLI.
934 * Pretty-Printer Introduction:: Introduction to pretty-printers
935 * Pretty-Printer Example:: An example pretty-printer
936 * Pretty-Printer Commands:: Pretty-printer commands
939 File: gdb.info, Node: Pretty-Printer Introduction, Next: Pretty-Printer Example, Up: Pretty Printing
941 10.9.1 Pretty-Printer Introduction
942 ----------------------------------
944 When GDB prints a value, it first sees if there is a pretty-printer
945 registered for the value. If there is then GDB invokes the
946 pretty-printer to print the value. Otherwise the value is printed
949 Pretty-printers are normally named. This makes them easy to manage.
950 The 'info pretty-printer' command will list all the installed
951 pretty-printers with their names. If a pretty-printer can handle
952 multiple data types, then its "subprinters" are the printers for the
953 individual data types. Each such subprinter has its own name. The
954 format of the name is PRINTER-NAME;SUBPRINTER-NAME.
956 Pretty-printers are installed by "registering" them with GDB.
957 Typically they are automatically loaded and registered when the
958 corresponding debug information is loaded, thus making them available
959 without having to do anything special.
961 There are three places where a pretty-printer can be registered.
963 * Pretty-printers registered globally are available when debugging
966 * Pretty-printers registered with a program space are available only
967 when debugging that program. *Note Progspaces In Python::, for
968 more details on program spaces in Python.
970 * Pretty-printers registered with an objfile are loaded and unloaded
971 with the corresponding objfile (e.g., shared library). *Note
972 Objfiles In Python::, for more details on objfiles in Python.
974 *Note Selecting Pretty-Printers::, for further information on how
975 pretty-printers are selected,
977 *Note Writing a Pretty-Printer::, for implementing pretty printers
981 File: gdb.info, Node: Pretty-Printer Example, Next: Pretty-Printer Commands, Prev: Pretty-Printer Introduction, Up: Pretty Printing
983 10.9.2 Pretty-Printer Example
984 -----------------------------
986 Here is how a C++ 'std::string' looks without a pretty-printer:
990 static npos = 4294967295,
992 <std::allocator<char>> = {
993 <__gnu_cxx::new_allocator<char>> = {
994 <No data fields>}, <No data fields>
996 members of std::basic_string<char, std::char_traits<char>,
997 std::allocator<char> >::_Alloc_hider:
998 _M_p = 0x804a014 "abcd"
1002 With a pretty-printer for 'std::string' only the contents are
1009 File: gdb.info, Node: Pretty-Printer Commands, Prev: Pretty-Printer Example, Up: Pretty Printing
1011 10.9.3 Pretty-Printer Commands
1012 ------------------------------
1014 'info pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]'
1015 Print the list of installed pretty-printers. This includes
1016 disabled pretty-printers, which are marked as such.
1018 OBJECT-REGEXP is a regular expression matching the objects whose
1019 pretty-printers to list. Objects can be 'global', the program
1020 space's file (*note Progspaces In Python::), and the object files
1021 within that program space (*note Objfiles In Python::). *Note
1022 Selecting Pretty-Printers::, for details on how GDB looks up a
1023 printer from these three objects.
1025 NAME-REGEXP is a regular expression matching the name of the
1028 'disable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]'
1029 Disable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. A
1030 disabled pretty-printer is not forgotten, it may be enabled again
1033 'enable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]'
1034 Enable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP.
1038 Suppose we have three pretty-printers installed: one from library1.so
1039 named 'foo' that prints objects of type 'foo', and another from
1040 library2.so named 'bar' that prints two types of objects, 'bar1' and
1043 (gdb) info pretty-printer
1050 (gdb) info pretty-printer library2
1055 (gdb) disable pretty-printer library1
1057 2 of 3 printers enabled
1058 (gdb) info pretty-printer
1065 (gdb) disable pretty-printer library2 bar:bar1
1067 1 of 3 printers enabled
1068 (gdb) info pretty-printer library2
1075 (gdb) disable pretty-printer library2 bar
1077 0 of 3 printers enabled
1078 (gdb) info pretty-printer library2
1086 Note that for 'bar' the entire printer can be disabled, as can each
1087 individual subprinter.
1090 File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Pretty Printing, Up: Data
1095 Values printed by the 'print' command are saved in the GDB "value
1096 history". This allows you to refer to them in other expressions.
1097 Values are kept until the symbol table is re-read or discarded (for
1098 example with the 'file' or 'symbol-file' commands). When the symbol
1099 table changes, the value history is discarded, since the values may
1100 contain pointers back to the types defined in the symbol table.
1102 The values printed are given "history numbers" by which you can refer
1103 to them. These are successive integers starting with one. 'print'
1104 shows you the history number assigned to a value by printing '$NUM = '
1105 before the value; here NUM is the history number.
1107 To refer to any previous value, use '$' followed by the value's
1108 history number. The way 'print' labels its output is designed to remind
1109 you of this. Just '$' refers to the most recent value in the history,
1110 and '$$' refers to the value before that. '$$N' refers to the Nth value
1111 from the end; '$$2' is the value just prior to '$$', '$$1' is equivalent
1112 to '$$', and '$$0' is equivalent to '$'.
1114 For example, suppose you have just printed a pointer to a structure
1115 and want to see the contents of the structure. It suffices to type
1119 If you have a chain of structures where the component 'next' points
1120 to the next one, you can print the contents of the next one with this:
1124 You can print successive links in the chain by repeating this
1125 command--which you can do by just typing <RET>.
1127 Note that the history records values, not expressions. If the value
1128 of 'x' is 4 and you type these commands:
1133 then the value recorded in the value history by the 'print' command
1134 remains 4 even though the value of 'x' has changed.
1137 Print the last ten values in the value history, with their item
1138 numbers. This is like 'p $$9' repeated ten times, except that
1139 'show values' does not change the history.
1142 Print ten history values centered on history item number N.
1145 Print ten history values just after the values last printed. If no
1146 more values are available, 'show values +' produces no display.
1148 Pressing <RET> to repeat 'show values N' has exactly the same effect
1152 File: gdb.info, Node: Convenience Vars, Next: Convenience Funs, Prev: Value History, Up: Data
1154 10.11 Convenience Variables
1155 ===========================
1157 GDB provides "convenience variables" that you can use within GDB to hold
1158 on to a value and refer to it later. These variables exist entirely
1159 within GDB; they are not part of your program, and setting a convenience
1160 variable has no direct effect on further execution of your program.
1161 That is why you can use them freely.
1163 Convenience variables are prefixed with '$'. Any name preceded by
1164 '$' can be used for a convenience variable, unless it is one of the
1165 predefined machine-specific register names (*note Registers:
1166 Registers.). (Value history references, in contrast, are _numbers_
1167 preceded by '$'. *Note Value History: Value History.)
1169 You can save a value in a convenience variable with an assignment
1170 expression, just as you would set a variable in your program. For
1173 set $foo = *object_ptr
1175 would save in '$foo' the value contained in the object pointed to by
1178 Using a convenience variable for the first time creates it, but its
1179 value is 'void' until you assign a new value. You can alter the value
1180 with another assignment at any time.
1182 Convenience variables have no fixed types. You can assign a
1183 convenience variable any type of value, including structures and arrays,
1184 even if that variable already has a value of a different type. The
1185 convenience variable, when used as an expression, has the type of its
1189 Print a list of convenience variables used so far, and their
1190 values, as well as a list of the convenience functions.
1191 Abbreviated 'show conv'.
1193 'init-if-undefined $VARIABLE = EXPRESSION'
1194 Set a convenience variable if it has not already been set. This is
1195 useful for user-defined commands that keep some state. It is
1196 similar, in concept, to using local static variables with
1197 initializers in C (except that convenience variables are global).
1198 It can also be used to allow users to override default values used
1199 in a command script.
1201 If the variable is already defined then the expression is not
1202 evaluated so any side-effects do not occur.
1204 One of the ways to use a convenience variable is as a counter to be
1205 incremented or a pointer to be advanced. For example, to print a field
1206 from successive elements of an array of structures:
1209 print bar[$i++]->contents
1211 Repeat that command by typing <RET>.
1213 Some convenience variables are created automatically by GDB and given
1214 values likely to be useful.
1217 The variable '$_' is automatically set by the 'x' command to the
1218 last address examined (*note Examining Memory: Memory.). Other
1219 commands which provide a default address for 'x' to examine also
1220 set '$_' to that address; these commands include 'info line' and
1221 'info breakpoint'. The type of '$_' is 'void *' except when set by
1222 the 'x' command, in which case it is a pointer to the type of
1226 The variable '$__' is automatically set by the 'x' command to the
1227 value found in the last address examined. Its type is chosen to
1228 match the format in which the data was printed.
1231 When the program being debugged terminates normally, GDB
1232 automatically sets this variable to the exit code of the program,
1233 and resets '$_exitsignal' to 'void'.
1236 When the program being debugged dies due to an uncaught signal, GDB
1237 automatically sets this variable to that signal's number, and
1238 resets '$_exitcode' to 'void'.
1240 To distinguish between whether the program being debugged has
1241 exited (i.e., '$_exitcode' is not 'void') or signalled (i.e.,
1242 '$_exitsignal' is not 'void'), the convenience function '$_isvoid'
1243 can be used (*note Convenience Functions: Convenience Funs.). For
1244 example, considering the following source code:
1249 main (int argc, char *argv[])
1255 A valid way of telling whether the program being debugged has
1256 exited or signalled would be:
1258 (gdb) define has_exited_or_signalled
1259 Type commands for definition of ``has_exited_or_signalled''.
1260 End with a line saying just ``end''.
1261 >if $_isvoid ($_exitsignal)
1262 >echo The program has exited\n
1264 >echo The program has signalled\n
1270 Program terminated with signal SIGALRM, Alarm clock.
1271 The program no longer exists.
1272 (gdb) has_exited_or_signalled
1273 The program has signalled
1275 As can be seen, GDB correctly informs that the program being
1276 debugged has signalled, since it calls 'raise' and raises a
1277 'SIGALRM' signal. If the program being debugged had not called
1278 'raise', then GDB would report a normal exit:
1280 (gdb) has_exited_or_signalled
1281 The program has exited
1284 The variable '$_exception' is set to the exception object being
1285 thrown at an exception-related catchpoint. *Note Set
1289 '$_probe_arg0...$_probe_arg11'
1290 Arguments to a static probe. *Note Static Probe Points::.
1293 The variable '$_sdata' contains extra collected static tracepoint
1294 data. *Note Tracepoint Action Lists: Tracepoint Actions. Note
1295 that '$_sdata' could be empty, if not inspecting a trace buffer, or
1296 if extra static tracepoint data has not been collected.
1299 The variable '$_siginfo' contains extra signal information (*note
1300 extra signal information::). Note that '$_siginfo' could be empty,
1301 if the application has not yet received any signals. For example,
1302 it will be empty before you execute the 'run' command.
1305 The variable '$_tlb' is automatically set when debugging
1306 applications running on MS-Windows in native mode or connected to
1307 gdbserver that supports the 'qGetTIBAddr' request. *Note General
1308 Query Packets::. This variable contains the address of the thread
1311 On HP-UX systems, if you refer to a function or variable name that
1312 begins with a dollar sign, GDB searches for a user or system name first,
1313 before it searches for a convenience variable.
1316 File: gdb.info, Node: Convenience Funs, Next: Registers, Prev: Convenience Vars, Up: Data
1318 10.12 Convenience Functions
1319 ===========================
1321 GDB also supplies some "convenience functions". These have a syntax
1322 similar to convenience variables. A convenience function can be used in
1323 an expression just like an ordinary function; however, a convenience
1324 function is implemented internally to GDB.
1326 These functions do not require GDB to be configured with 'Python'
1327 support, which means that they are always available.
1330 Return one if the expression EXPR is 'void'. Otherwise it returns
1333 A 'void' expression is an expression where the type of the result
1334 is 'void'. For example, you can examine a convenience variable
1335 (see *note Convenience Variables: Convenience Vars.) to check
1336 whether it is 'void':
1338 (gdb) print $_exitcode
1340 (gdb) print $_isvoid ($_exitcode)
1343 Starting program: ./a.out
1344 [Inferior 1 (process 29572) exited normally]
1345 (gdb) print $_exitcode
1347 (gdb) print $_isvoid ($_exitcode)
1350 In the example above, we used '$_isvoid' to check whether
1351 '$_exitcode' is 'void' before and after the execution of the
1352 program being debugged. Before the execution there is no exit code
1353 to be examined, therefore '$_exitcode' is 'void'. After the
1354 execution the program being debugged returned zero, therefore
1355 '$_exitcode' is zero, which means that it is not 'void' anymore.
1357 The 'void' expression can also be a call of a function from the
1358 program being debugged. For example, given the following function:
1365 The result of calling it inside GDB is 'void':
1369 (gdb) print $_isvoid (foo ())
1371 (gdb) set $v = foo ()
1374 (gdb) print $_isvoid ($v)
1377 These functions require GDB to be configured with 'Python' support.
1379 '$_memeq(BUF1, BUF2, LENGTH)'
1380 Returns one if the LENGTH bytes at the addresses given by BUF1 and
1381 BUF2 are equal. Otherwise it returns zero.
1383 '$_regex(STR, REGEX)'
1384 Returns one if the string STR matches the regular expression REGEX.
1385 Otherwise it returns zero. The syntax of the regular expression is
1386 that specified by 'Python''s regular expression support.
1388 '$_streq(STR1, STR2)'
1389 Returns one if the strings STR1 and STR2 are equal. Otherwise it
1393 Returns the length of string STR.
1395 GDB provides the ability to list and get help on convenience
1399 Print a list of all convenience functions.
1402 File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Funs, Up: Data
1407 You can refer to machine register contents, in expressions, as variables
1408 with names starting with '$'. The names of registers are different for
1409 each machine; use 'info registers' to see the names used on your
1413 Print the names and values of all registers except floating-point
1414 and vector registers (in the selected stack frame).
1416 'info all-registers'
1417 Print the names and values of all registers, including
1418 floating-point and vector registers (in the selected stack frame).
1420 'info registers REGNAME ...'
1421 Print the "relativized" value of each specified register REGNAME.
1422 As discussed in detail below, register values are normally relative
1423 to the selected stack frame. REGNAME may be any register name
1424 valid on the machine you are using, with or without the initial
1427 GDB has four "standard" register names that are available (in
1428 expressions) on most machines--whenever they do not conflict with an
1429 architecture's canonical mnemonics for registers. The register names
1430 '$pc' and '$sp' are used for the program counter register and the stack
1431 pointer. '$fp' is used for a register that contains a pointer to the
1432 current stack frame, and '$ps' is used for a register that contains the
1433 processor status. For example, you could print the program counter in
1438 or print the instruction to be executed next with
1442 or add four to the stack pointer(1) with
1446 Whenever possible, these four standard register names are available
1447 on your machine even though the machine has different canonical
1448 mnemonics, so long as there is no conflict. The 'info registers'
1449 command shows the canonical names. For example, on the SPARC, 'info
1450 registers' displays the processor status register as '$psr' but you can
1451 also refer to it as '$ps'; and on x86-based machines '$ps' is an alias
1452 for the EFLAGS register.
1454 GDB always considers the contents of an ordinary register as an
1455 integer when the register is examined in this way. Some machines have
1456 special registers which can hold nothing but floating point; these
1457 registers are considered to have floating point values. There is no way
1458 to refer to the contents of an ordinary register as floating point value
1459 (although you can _print_ it as a floating point value with 'print/f
1462 Some registers have distinct "raw" and "virtual" data formats. This
1463 means that the data format in which the register contents are saved by
1464 the operating system is not the same one that your program normally
1465 sees. For example, the registers of the 68881 floating point
1466 coprocessor are always saved in "extended" (raw) format, but all C
1467 programs expect to work with "double" (virtual) format. In such cases,
1468 GDB normally works with the virtual format only (the format that makes
1469 sense for your program), but the 'info registers' command prints the
1470 data in both formats.
1472 Some machines have special registers whose contents can be
1473 interpreted in several different ways. For example, modern x86-based
1474 machines have SSE and MMX registers that can hold several values packed
1475 together in several different formats. GDB refers to such registers in
1480 v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044},
1481 v2_double = {9.92129282474342e-303, 2.7585945287983262e-313},
1482 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000",
1483 v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0},
1484 v4_int32 = {0, 20657912, 11, 13},
1485 v2_int64 = {88725056443645952, 55834574859},
1486 uint128 = 0x0000000d0000000b013b36f800000000
1489 To set values of such registers, you need to tell GDB which view of the
1490 register you wish to change, as if you were assigning value to a
1493 (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF
1495 Normally, register values are relative to the selected stack frame
1496 (*note Selecting a Frame: Selection.). This means that you get the
1497 value that the register would contain if all stack frames farther in
1498 were exited and their saved registers restored. In order to see the
1499 true contents of hardware registers, you must select the innermost frame
1502 Usually ABIs reserve some registers as not needed to be saved by the
1503 callee (a.k.a.: "caller-saved", "call-clobbered" or "volatile"
1504 registers). It may therefore not be possible for GDB to know the value
1505 a register had before the call (in other words, in the outer frame), if
1506 the register value has since been changed by the callee. GDB tries to
1507 deduce where the inner frame saved ("callee-saved") registers, from the
1508 debug info, unwind info, or the machine code generated by your compiler.
1509 If some register is not saved, and GDB knows the register is
1510 "caller-saved" (via its own knowledge of the ABI, or because the
1511 debug/unwind info explicitly says the register's value is undefined),
1512 GDB displays '<not saved>' as the register's value. With targets that
1513 GDB has no knowledge of the register saving convention, if a register
1514 was not saved by the callee, then its value and location in the outer
1515 frame are assumed to be the same of the inner frame. This is usually
1516 harmless, because if the register is call-clobbered, the caller either
1517 does not care what is in the register after the call, or has code to
1518 restore the value that it does care about. Note, however, that if you
1519 change such a register in the outer frame, you may also be affecting the
1520 inner frame. Also, the more "outer" the frame is you're looking at, the
1521 more likely a call-clobbered register's value is to be wrong, in the
1522 sense that it doesn't actually represent the value the register had just
1525 ---------- Footnotes ----------
1527 (1) This is a way of removing one word from the stack, on machines
1528 where stacks grow downward in memory (most machines, nowadays). This
1529 assumes that the innermost stack frame is selected; setting '$sp' is not
1530 allowed when other stack frames are selected. To pop entire frames off
1531 the stack, regardless of machine architecture, use 'return'; see *note
1532 Returning from a Function: Returning.
1535 File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data
1537 10.14 Floating Point Hardware
1538 =============================
1540 Depending on the configuration, GDB may be able to give you more
1541 information about the status of the floating point hardware.
1544 Display hardware-dependent information about the floating point
1545 unit. The exact contents and layout vary depending on the floating
1546 point chip. Currently, 'info float' is supported on the ARM and
1550 File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data
1555 Depending on the configuration, GDB may be able to give you more
1556 information about the status of the vector unit.
1559 Display information about the vector unit. The exact contents and
1560 layout vary depending on the hardware.
1563 File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data
1565 10.16 Operating System Auxiliary Information
1566 ============================================
1568 GDB provides interfaces to useful OS facilities that can help you debug
1571 Some operating systems supply an "auxiliary vector" to programs at
1572 startup. This is akin to the arguments and environment that you specify
1573 for a program, but contains a system-dependent variety of binary values
1574 that tell system libraries important details about the hardware,
1575 operating system, and process. Each value's purpose is identified by an
1576 integer tag; the meanings are well-known but system-specific. Depending
1577 on the configuration and operating system facilities, GDB may be able to
1578 show you this information. For remote targets, this functionality may
1579 further depend on the remote stub's support of the 'qXfer:auxv:read'
1580 packet, see *note qXfer auxiliary vector read::.
1583 Display the auxiliary vector of the inferior, which can be either a
1584 live process or a core dump file. GDB prints each tag value
1585 numerically, and also shows names and text descriptions for
1586 recognized tags. Some values in the vector are numbers, some bit
1587 masks, and some pointers to strings or other data. GDB displays
1588 each value in the most appropriate form for a recognized tag, and
1589 in hexadecimal for an unrecognized tag.
1591 On some targets, GDB can access operating system-specific information
1592 and show it to you. The types of information available will differ
1593 depending on the type of operating system running on the target. The
1594 mechanism used to fetch the data is described in *note Operating System
1595 Information::. For remote targets, this functionality depends on the
1596 remote stub's support of the 'qXfer:osdata:read' packet, see *note qXfer
1601 Display OS information of the requested type.
1603 On GNU/Linux, the following values of INFOTYPE are valid:
1606 Display the list of processes on the target. For each
1607 process, GDB prints the process identifier, the name of the
1608 user, the command corresponding to the process, and the list
1609 of processor cores that the process is currently running on.
1610 (To understand what these properties mean, for this and the
1611 following info types, please consult the general GNU/Linux
1615 Display the list of process groups on the target. For each
1616 process, GDB prints the identifier of the process group that
1617 it belongs to, the command corresponding to the process group
1618 leader, the process identifier, and the command line of the
1619 process. The list is sorted first by the process group
1620 identifier, then by the process identifier, so that processes
1621 belonging to the same process group are grouped together and
1622 the process group leader is listed first.
1625 Display the list of threads running on the target. For each
1626 thread, GDB prints the identifier of the process that the
1627 thread belongs to, the command of the process, the thread
1628 identifier, and the processor core that it is currently
1629 running on. The main thread of a process is not listed.
1632 Display the list of open file descriptors on the target. For
1633 each file descriptor, GDB prints the identifier of the process
1634 owning the descriptor, the command of the owning process, the
1635 value of the descriptor, and the target of the descriptor.
1638 Display the list of Internet-domain sockets on the target.
1639 For each socket, GDB prints the address and port of the local
1640 and remote endpoints, the current state of the connection, the
1641 creator of the socket, the IP address family of the socket,
1642 and the type of the connection.
1645 Display the list of all System V shared-memory regions on the
1646 target. For each shared-memory region, GDB prints the region
1647 key, the shared-memory identifier, the access permissions, the
1648 size of the region, the process that created the region, the
1649 process that last attached to or detached from the region, the
1650 current number of live attaches to the region, and the times
1651 at which the region was last attached to, detach from, and
1655 Display the list of all System V semaphore sets on the target.
1656 For each semaphore set, GDB prints the semaphore set key, the
1657 semaphore set identifier, the access permissions, the number
1658 of semaphores in the set, the user and group of the owner and
1659 creator of the semaphore set, and the times at which the
1660 semaphore set was operated upon and changed.
1663 Display the list of all System V message queues on the target.
1664 For each message queue, GDB prints the message queue key, the
1665 message queue identifier, the access permissions, the current
1666 number of bytes on the queue, the current number of messages
1667 on the queue, the processes that last sent and received a
1668 message on the queue, the user and group of the owner and
1669 creator of the message queue, the times at which a message was
1670 last sent and received on the queue, and the time at which the
1671 message queue was last changed.
1674 Display the list of all loaded kernel modules on the target.
1675 For each module, GDB prints the module name, the size of the
1676 module in bytes, the number of times the module is used, the
1677 dependencies of the module, the status of the module, and the
1678 address of the loaded module in memory.
1681 If INFOTYPE is omitted, then list the possible values for INFOTYPE
1682 and the kind of OS information available for each INFOTYPE. If the
1683 target does not return a list of possible types, this command will
1687 File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data
1689 10.17 Memory Region Attributes
1690 ==============================
1692 "Memory region attributes" allow you to describe special handling
1693 required by regions of your target's memory. GDB uses attributes to
1694 determine whether to allow certain types of memory accesses; whether to
1695 use specific width accesses; and whether to cache target memory. By
1696 default the description of memory regions is fetched from the target (if
1697 the current target supports this), but the user can override the fetched
1700 Defined memory regions can be individually enabled and disabled.
1701 When a memory region is disabled, GDB uses the default attributes when
1702 accessing memory in that region. Similarly, if no memory regions have
1703 been defined, GDB uses the default attributes when accessing all memory.
1705 When a memory region is defined, it is given a number to identify it;
1706 to enable, disable, or remove a memory region, you specify that number.
1708 'mem LOWER UPPER ATTRIBUTES...'
1709 Define a memory region bounded by LOWER and UPPER with attributes
1710 ATTRIBUTES..., and add it to the list of regions monitored by GDB.
1711 Note that UPPER == 0 is a special case: it is treated as the
1712 target's maximum memory address. (0xffff on 16 bit targets,
1713 0xffffffff on 32 bit targets, etc.)
1716 Discard any user changes to the memory regions and use
1717 target-supplied regions, if available, or no regions if the target
1720 'delete mem NUMS...'
1721 Remove memory regions NUMS... from the list of regions monitored by
1724 'disable mem NUMS...'
1725 Disable monitoring of memory regions NUMS.... A disabled memory
1726 region is not forgotten. It may be enabled again later.
1728 'enable mem NUMS...'
1729 Enable monitoring of memory regions NUMS....
1732 Print a table of all defined memory regions, with the following
1733 columns for each region:
1735 _Memory Region Number_
1736 _Enabled or Disabled._
1737 Enabled memory regions are marked with 'y'. Disabled memory
1738 regions are marked with 'n'.
1741 The address defining the inclusive lower bound of the memory
1745 The address defining the exclusive upper bound of the memory
1749 The list of attributes set for this memory region.
1754 10.17.1.1 Memory Access Mode
1755 ............................
1757 The access mode attributes set whether GDB may make read or write
1758 accesses to a memory region.
1760 While these attributes prevent GDB from performing invalid memory
1761 accesses, they do nothing to prevent the target system, I/O DMA, etc.
1762 from accessing memory.
1765 Memory is read only.
1767 Memory is write only.
1769 Memory is read/write. This is the default.
1771 10.17.1.2 Memory Access Size
1772 ............................
1774 The access size attribute tells GDB to use specific sized accesses in
1775 the memory region. Often memory mapped device registers require
1776 specific sized accesses. If no access size attribute is specified, GDB
1777 may use accesses of any size.
1780 Use 8 bit memory accesses.
1782 Use 16 bit memory accesses.
1784 Use 32 bit memory accesses.
1786 Use 64 bit memory accesses.
1788 10.17.1.3 Data Cache
1789 ....................
1791 The data cache attributes set whether GDB will cache target memory.
1792 While this generally improves performance by reducing debug protocol
1793 overhead, it can lead to incorrect results because GDB does not know
1794 about volatile variables or memory mapped device registers.
1797 Enable GDB to cache target memory.
1799 Disable GDB from caching target memory. This is the default.
1801 10.17.2 Memory Access Checking
1802 ------------------------------
1804 GDB can be instructed to refuse accesses to memory that is not
1805 explicitly described. This can be useful if accessing such regions has
1806 undesired effects for a specific target, or to provide better error
1807 checking. The following commands control this behaviour.
1809 'set mem inaccessible-by-default [on|off]'
1810 If 'on' is specified, make GDB treat memory not explicitly
1811 described by the memory ranges as non-existent and refuse accesses
1812 to such memory. The checks are only performed if there's at least
1813 one memory range defined. If 'off' is specified, make GDB treat
1814 the memory not explicitly described by the memory ranges as RAM.
1815 The default value is 'on'.
1816 'show mem inaccessible-by-default'
1817 Show the current handling of accesses to unknown memory.
1820 File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data
1822 10.18 Copy Between Memory and a File
1823 ====================================
1825 You can use the commands 'dump', 'append', and 'restore' to copy data
1826 between target memory and a file. The 'dump' and 'append' commands
1827 write data to a file, and the 'restore' command reads data from a file
1828 back into the inferior's memory. Files may be in binary, Motorola
1829 S-record, Intel hex, or Tektronix Hex format; however, GDB can only
1830 append to binary files.
1832 'dump [FORMAT] memory FILENAME START_ADDR END_ADDR'
1833 'dump [FORMAT] value FILENAME EXPR'
1834 Dump the contents of memory from START_ADDR to END_ADDR, or the
1835 value of EXPR, to FILENAME in the given format.
1837 The FORMAT parameter may be any one of:
1843 Motorola S-record format.
1845 Tektronix Hex format.
1847 GDB uses the same definitions of these formats as the GNU binary
1848 utilities, like 'objdump' and 'objcopy'. If FORMAT is omitted, GDB
1849 dumps the data in raw binary form.
1851 'append [binary] memory FILENAME START_ADDR END_ADDR'
1852 'append [binary] value FILENAME EXPR'
1853 Append the contents of memory from START_ADDR to END_ADDR, or the
1854 value of EXPR, to the file FILENAME, in raw binary form. (GDB can
1855 only append data to files in raw binary form.)
1857 'restore FILENAME [binary] BIAS START END'
1858 Restore the contents of file FILENAME into memory. The 'restore'
1859 command can automatically recognize any known BFD file format,
1860 except for raw binary. To restore a raw binary file you must
1861 specify the optional keyword 'binary' after the filename.
1863 If BIAS is non-zero, its value will be added to the addresses
1864 contained in the file. Binary files always start at address zero,
1865 so they will be restored at address BIAS. Other bfd files have a
1866 built-in location; they will be restored at offset BIAS from that
1869 If START and/or END are non-zero, then only data between file
1870 offset START and file offset END will be restored. These offsets
1871 are relative to the addresses in the file, before the BIAS argument
1875 File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data
1877 10.19 How to Produce a Core File from Your Program
1878 ==================================================
1880 A "core file" or "core dump" is a file that records the memory image of
1881 a running process and its process status (register values etc.). Its
1882 primary use is post-mortem debugging of a program that crashed while it
1883 ran outside a debugger. A program that crashes automatically produces a
1884 core file, unless this feature is disabled by the user. *Note Files::,
1885 for information on invoking GDB in the post-mortem debugging mode.
1887 Occasionally, you may wish to produce a core file of the program you
1888 are debugging in order to preserve a snapshot of its state. GDB has a
1889 special command for that.
1891 'generate-core-file [FILE]'
1893 Produce a core dump of the inferior process. The optional argument
1894 FILE specifies the file name where to put the core dump. If not
1895 specified, the file name defaults to 'core.PID', where PID is the
1896 inferior process ID.
1898 Note that this command is implemented only for some systems (as of
1899 this writing, GNU/Linux, FreeBSD, Solaris, and S390).
1902 File: gdb.info, Node: Character Sets, Next: Caching Target Data, Prev: Core File Generation, Up: Data
1904 10.20 Character Sets
1905 ====================
1907 If the program you are debugging uses a different character set to
1908 represent characters and strings than the one GDB uses itself, GDB can
1909 automatically translate between the character sets for you. The
1910 character set GDB uses we call the "host character set"; the one the
1911 inferior program uses we call the "target character set".
1913 For example, if you are running GDB on a GNU/Linux system, which uses
1914 the ISO Latin 1 character set, but you are using GDB's remote protocol
1915 (*note Remote Debugging::) to debug a program running on an IBM
1916 mainframe, which uses the EBCDIC character set, then the host character
1917 set is Latin-1, and the target character set is EBCDIC. If you give GDB
1918 the command 'set target-charset EBCDIC-US', then GDB translates between
1919 EBCDIC and Latin 1 as you print character or string values, or use
1920 character and string literals in expressions.
1922 GDB has no way to automatically recognize which character set the
1923 inferior program uses; you must tell it, using the 'set target-charset'
1924 command, described below.
1926 Here are the commands for controlling GDB's character set support:
1928 'set target-charset CHARSET'
1929 Set the current target character set to CHARSET. To display the
1930 list of supported target character sets, type
1931 'set target-charset <TAB><TAB>'.
1933 'set host-charset CHARSET'
1934 Set the current host character set to CHARSET.
1936 By default, GDB uses a host character set appropriate to the system
1937 it is running on; you can override that default using the 'set
1938 host-charset' command. On some systems, GDB cannot automatically
1939 determine the appropriate host character set. In this case, GDB
1942 GDB can only use certain character sets as its host character set.
1943 If you type 'set host-charset <TAB><TAB>', GDB will list the host
1944 character sets it supports.
1946 'set charset CHARSET'
1947 Set the current host and target character sets to CHARSET. As
1948 above, if you type 'set charset <TAB><TAB>', GDB will list the
1949 names of the character sets that can be used for both host and
1953 Show the names of the current host and target character sets.
1956 Show the name of the current host character set.
1958 'show target-charset'
1959 Show the name of the current target character set.
1961 'set target-wide-charset CHARSET'
1962 Set the current target's wide character set to CHARSET. This is
1963 the character set used by the target's 'wchar_t' type. To display
1964 the list of supported wide character sets, type
1965 'set target-wide-charset <TAB><TAB>'.
1967 'show target-wide-charset'
1968 Show the name of the current target's wide character set.
1970 Here is an example of GDB's character set support in action. Assume
1971 that the following source code has been placed in the file
1977 = {72, 101, 108, 108, 111, 44, 32, 119,
1978 111, 114, 108, 100, 33, 10, 0};
1979 char ibm1047_hello[]
1980 = {200, 133, 147, 147, 150, 107, 64, 166,
1981 150, 153, 147, 132, 90, 37, 0};
1985 printf ("Hello, world!\n");
1988 In this program, 'ascii_hello' and 'ibm1047_hello' are arrays
1989 containing the string 'Hello, world!' followed by a newline, encoded in
1990 the ASCII and IBM1047 character sets.
1992 We compile the program, and invoke the debugger on it:
1994 $ gcc -g charset-test.c -o charset-test
1995 $ gdb -nw charset-test
1996 GNU gdb 2001-12-19-cvs
1997 Copyright 2001 Free Software Foundation, Inc.
2001 We can use the 'show charset' command to see what character sets GDB
2002 is currently using to interpret and display characters and strings:
2005 The current host and target character set is `ISO-8859-1'.
2008 For the sake of printing this manual, let's use ASCII as our initial
2010 (gdb) set charset ASCII
2012 The current host and target character set is `ASCII'.
2015 Let's assume that ASCII is indeed the correct character set for our
2016 host system -- in other words, let's assume that if GDB prints
2017 characters using the ASCII character set, our terminal will display them
2018 properly. Since our current target character set is also ASCII, the
2019 contents of 'ascii_hello' print legibly:
2021 (gdb) print ascii_hello
2022 $1 = 0x401698 "Hello, world!\n"
2023 (gdb) print ascii_hello[0]
2027 GDB uses the target character set for character and string literals
2028 you use in expressions:
2034 The ASCII character set uses the number 43 to encode the '+'
2037 GDB relies on the user to tell it which character set the target
2038 program uses. If we print 'ibm1047_hello' while our target character
2039 set is still ASCII, we get jibberish:
2041 (gdb) print ibm1047_hello
2042 $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%"
2043 (gdb) print ibm1047_hello[0]
2047 If we invoke the 'set target-charset' followed by <TAB><TAB>, GDB
2048 tells us the character sets it supports:
2050 (gdb) set target-charset
2051 ASCII EBCDIC-US IBM1047 ISO-8859-1
2052 (gdb) set target-charset
2054 We can select IBM1047 as our target character set, and examine the
2055 program's strings again. Now the ASCII string is wrong, but GDB
2056 translates the contents of 'ibm1047_hello' from the target character
2057 set, IBM1047, to the host character set, ASCII, and they display
2060 (gdb) set target-charset IBM1047
2062 The current host character set is `ASCII'.
2063 The current target character set is `IBM1047'.
2064 (gdb) print ascii_hello
2065 $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
2066 (gdb) print ascii_hello[0]
2068 (gdb) print ibm1047_hello
2069 $8 = 0x4016a8 "Hello, world!\n"
2070 (gdb) print ibm1047_hello[0]
2074 As above, GDB uses the target character set for character and string
2075 literals you use in expressions:
2081 The IBM1047 character set uses the number 78 to encode the '+'
2085 File: gdb.info, Node: Caching Target Data, Next: Searching Memory, Prev: Character Sets, Up: Data
2087 10.21 Caching Data of Targets
2088 =============================
2090 GDB caches data exchanged between the debugger and a target. Each cache
2091 is associated with the address space of the inferior. *Note Inferiors
2092 and Programs::, about inferior and address space. Such caching
2093 generally improves performance in remote debugging (*note Remote
2094 Debugging::), because it reduces the overhead of the remote protocol by
2095 bundling memory reads and writes into large chunks. Unfortunately,
2096 simply caching everything would lead to incorrect results, since GDB
2097 does not necessarily know anything about volatile values, memory-mapped
2098 I/O addresses, etc. Furthermore, in non-stop mode (*note Non-Stop
2099 Mode::) memory can be changed _while_ a gdb command is executing.
2100 Therefore, by default, GDB only caches data known to be on the stack(1)
2101 or in the code segment. Other regions of memory can be explicitly
2102 marked as cacheable; *note Memory Region Attributes::.
2104 'set remotecache on'
2105 'set remotecache off'
2106 This option no longer does anything; it exists for compatibility
2110 Show the current state of the obsolete remotecache flag.
2112 'set stack-cache on'
2113 'set stack-cache off'
2114 Enable or disable caching of stack accesses. When 'on', use
2115 caching. By default, this option is 'on'.
2118 Show the current state of data caching for memory accesses.
2121 'set code-cache off'
2122 Enable or disable caching of code segment accesses. When 'on', use
2123 caching. By default, this option is 'on'. This improves
2124 performance of disassembly in remote debugging.
2127 Show the current state of target memory cache for code segment
2130 'info dcache [line]'
2131 Print the information about the performance of data cache of the
2132 current inferior's address space. The information displayed
2133 includes the dcache width and depth, and for each cache line, its
2134 number, address, and how many times it was referenced. This
2135 command is useful for debugging the data cache operation.
2137 If a line number is specified, the contents of that line will be
2140 'set dcache size SIZE'
2141 Set maximum number of entries in dcache (dcache depth above).
2143 'set dcache line-size LINE-SIZE'
2144 Set number of bytes each dcache entry caches (dcache width above).
2145 Must be a power of 2.
2148 Show maximum number of dcache entries. *Note info dcache: Caching
2151 'show dcache line-size'
2152 Show default size of dcache lines.
2154 ---------- Footnotes ----------
2156 (1) In non-stop mode, it is moderately rare for a running thread to
2157 modify the stack of a stopped thread in a way that would interfere with
2158 a backtrace, and caching of stack reads provides a significant speed up
2159 of remote backtraces.
2162 File: gdb.info, Node: Searching Memory, Prev: Caching Target Data, Up: Data
2167 Memory can be searched for a particular sequence of bytes with the
2170 'find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]'
2171 'find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]'
2172 Search memory for the sequence of bytes specified by VAL1, VAL2,
2173 etc. The search begins at address START_ADDR and continues for
2174 either LEN bytes or through to END_ADDR inclusive.
2176 S and N are optional parameters. They may be specified in either
2177 order, apart or together.
2179 S, search query size
2180 The size of each search query value.
2185 halfwords (two bytes)
2189 giant words (eight bytes)
2191 All values are interpreted in the current language. This means,
2192 for example, that if the current source language is C/C++ then
2193 searching for the string "hello" includes the trailing '\0'.
2195 If the value size is not specified, it is taken from the value's
2196 type in the current language. This is useful when one wants to
2197 specify the search pattern as a mixture of types. Note that this
2198 means, for example, that in the case of C-like languages a search
2199 for an untyped 0x42 will search for '(int) 0x42' which is typically
2202 N, maximum number of finds
2203 The maximum number of matches to print. The default is to print
2206 You can use strings as search values. Quote them with double-quotes
2207 ('"'). The string value is copied into the search pattern byte by byte,
2208 regardless of the endianness of the target and the size specification.
2210 The address of each match found is printed as well as a count of the
2211 number of matches found.
2213 The address of the last value found is stored in convenience variable
2214 '$_'. A count of the number of matches is stored in '$numfound'.
2216 For example, if stopped at the 'printf' in this function:
2221 static char hello[] = "hello-hello";
2222 static struct { char c; short s; int i; }
2223 __attribute__ ((packed)) mixed
2224 = { 'c', 0x1234, 0x87654321 };
2225 printf ("%s\n", hello);
2228 you get during debugging:
2230 (gdb) find &hello[0], +sizeof(hello), "hello"
2231 0x804956d <hello.1620+6>
2233 (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
2234 0x8049567 <hello.1620>
2235 0x804956d <hello.1620+6>
2237 (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
2238 0x8049567 <hello.1620>
2240 (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
2241 0x8049560 <mixed.1625>
2243 (gdb) print $numfound
2246 $2 = (void *) 0x8049560
2249 File: gdb.info, Node: Optimized Code, Next: Macros, Prev: Data, Up: Top
2251 11 Debugging Optimized Code
2252 ***************************
2254 Almost all compilers support optimization. With optimization disabled,
2255 the compiler generates assembly code that corresponds directly to your
2256 source code, in a simplistic way. As the compiler applies more powerful
2257 optimizations, the generated assembly code diverges from your original
2258 source code. With help from debugging information generated by the
2259 compiler, GDB can map from the running program back to constructs from
2260 your original source.
2262 GDB is more accurate with optimization disabled. If you can
2263 recompile without optimization, it is easier to follow the progress of
2264 your program during debugging. But, there are many cases where you may
2265 need to debug an optimized version.
2267 When you debug a program compiled with '-g -O', remember that the
2268 optimizer has rearranged your code; the debugger shows you what is
2269 really there. Do not be too surprised when the execution path does not
2270 exactly match your source file! An extreme example: if you define a
2271 variable, but never use it, GDB never sees that variable--because the
2272 compiler optimizes it out of existence.
2274 Some things do not work as well with '-g -O' as with just '-g',
2275 particularly on machines with instruction scheduling. If in doubt,
2276 recompile with '-g' alone, and if this fixes the problem, please report
2277 it to us as a bug (including a test case!). *Note Variables::, for more
2278 information about debugging optimized code.
2282 * Inline Functions:: How GDB presents inlining
2283 * Tail Call Frames:: GDB analysis of jumps to functions
2286 File: gdb.info, Node: Inline Functions, Next: Tail Call Frames, Up: Optimized Code
2288 11.1 Inline Functions
2289 =====================
2291 "Inlining" is an optimization that inserts a copy of the function body
2292 directly at each call site, instead of jumping to a shared routine. GDB
2293 displays inlined functions just like non-inlined functions. They appear
2294 in backtraces. You can view their arguments and local variables, step
2295 into them with 'step', skip them with 'next', and escape from them with
2296 'finish'. You can check whether a function was inlined by using the
2297 'info frame' command.
2299 For GDB to support inlined functions, the compiler must record
2300 information about inlining in the debug information -- GCC using the
2301 DWARF 2 format does this, and several other compilers do also. GDB only
2302 supports inlined functions when using DWARF 2. Versions of GCC before
2303 4.1 do not emit two required attributes ('DW_AT_call_file' and
2304 'DW_AT_call_line'); GDB does not display inlined function calls with
2305 earlier versions of GCC. It instead displays the arguments and local
2306 variables of inlined functions as local variables in the caller.
2308 The body of an inlined function is directly included at its call
2309 site; unlike a non-inlined function, there are no instructions devoted
2310 to the call. GDB still pretends that the call site and the start of the
2311 inlined function are different instructions. Stepping to the call site
2312 shows the call site, and then stepping again shows the first line of the
2313 inlined function, even though no additional instructions are executed.
2315 This makes source-level debugging much clearer; you can see both the
2316 context of the call and then the effect of the call. Only stepping by a
2317 single instruction using 'stepi' or 'nexti' does not do this; single
2318 instruction steps always show the inlined body.
2320 There are some ways that GDB does not pretend that inlined function
2321 calls are the same as normal calls:
2323 * Setting breakpoints at the call site of an inlined function may not
2324 work, because the call site does not contain any code. GDB may
2325 incorrectly move the breakpoint to the next line of the enclosing
2326 function, after the call. This limitation will be removed in a
2327 future version of GDB; until then, set a breakpoint on an earlier
2328 line or inside the inlined function instead.
2330 * GDB cannot locate the return value of inlined calls after using the
2331 'finish' command. This is a limitation of compiler-generated
2332 debugging information; after 'finish', you can step to the next
2333 line and print a variable where your program stored the return
2337 File: gdb.info, Node: Tail Call Frames, Prev: Inline Functions, Up: Optimized Code
2339 11.2 Tail Call Frames
2340 =====================
2342 Function 'B' can call function 'C' in its very last statement. In
2343 unoptimized compilation the call of 'C' is immediately followed by
2344 return instruction at the end of 'B' code. Optimizing compiler may
2345 replace the call and return in function 'B' into one jump to function
2346 'C' instead. Such use of a jump instruction is called "tail call".
2348 During execution of function 'C', there will be no indication in the
2349 function call stack frames that it was tail-called from 'B'. If
2350 function 'A' regularly calls function 'B' which tail-calls function 'C',
2351 then GDB will see 'A' as the caller of 'C'. However, in some cases GDB
2352 can determine that 'C' was tail-called from 'B', and it will then create
2353 fictitious call frame for that, with the return address set up as if 'B'
2354 called 'C' normally.
2356 This functionality is currently supported only by DWARF 2 debugging
2357 format and the compiler has to produce 'DW_TAG_GNU_call_site' tags.
2358 With GCC, you need to specify '-O -g' during compilation, to get this
2361 'info frame' command (*note Frame Info::) will indicate the tail call
2362 frame kind by text 'tail call frame' such as in this sample GDB output:
2365 0x40066b <b(int, double)+11>: jmp 0x400640 <c(int, double)>
2367 Stack level 1, frame at 0x7fffffffda30:
2368 rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
2369 tail call frame, caller of frame at 0x7fffffffda30
2370 source language c++.
2371 Arglist at unknown address.
2372 Locals at unknown address, Previous frame's sp is 0x7fffffffda30
2374 The detection of all the possible code path executions can find them
2375 ambiguous. There is no execution history stored (possible *note Reverse
2376 Execution:: is never used for this purpose) and the last known caller
2377 could have reached the known callee by multiple different jump
2378 sequences. In such case GDB still tries to show at least all the
2379 unambiguous top tail callers and all the unambiguous bottom tail calees,
2382 'set debug entry-values'
2383 When set to on, enables printing of analysis messages for both
2384 frame argument values at function entry and tail calls. It will
2385 show all the possible valid tail calls code paths it has
2386 considered. It will also print the intersection of them with the
2387 final unambiguous (possibly partial or even empty) code path
2390 'show debug entry-values'
2391 Show the current state of analysis messages printing for both frame
2392 argument values at function entry and tail calls.
2394 The analysis messages for tail calls can for example show why the
2395 virtual tail call frame for function 'c' has not been recognized (due to
2396 the indirect reference by variable 'x'):
2398 static void __attribute__((noinline, noclone)) c (void);
2399 void (*x) (void) = c;
2400 static void __attribute__((noinline, noclone)) a (void) { x++; }
2401 static void __attribute__((noinline, noclone)) c (void) { a (); }
2402 int main (void) { x (); return 0; }
2404 Breakpoint 1, DW_OP_GNU_entry_value resolving cannot find
2405 DW_TAG_GNU_call_site 0x40039a in main
2407 3 static void __attribute__((noinline, noclone)) a (void) { x++; }
2410 #1 0x000000000040039a in main () at t.c:5
2412 Another possibility is an ambiguous virtual tail call frames
2416 static void __attribute__((noinline, noclone)) f (void) { i++; }
2417 static void __attribute__((noinline, noclone)) e (void) { f (); }
2418 static void __attribute__((noinline, noclone)) d (void) { f (); }
2419 static void __attribute__((noinline, noclone)) c (void) { d (); }
2420 static void __attribute__((noinline, noclone)) b (void)
2421 { if (i) c (); else e (); }
2422 static void __attribute__((noinline, noclone)) a (void) { b (); }
2423 int main (void) { a (); return 0; }
2425 tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d)
2426 tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e)
2427 tailcall: reduced: 0x4004d2(a) |
2430 #1 0x00000000004004d2 in a () at t.c:8
2431 #2 0x0000000000400395 in main () at t.c:9
2433 Frames #0 and #2 are real, #1 is a virtual tail call frame. The code
2434 can have possible execution paths 'main->a->b->c->d->f' or
2435 'main->a->b->e->f', GDB cannot find which one from the inferior state.
2437 'initial:' state shows some random possible calling sequence GDB has
2438 found. It then finds another possible calling sequcen - that one is
2439 prefixed by 'compare:'. The non-ambiguous intersection of these two is
2440 printed as the 'reduced:' calling sequence. That one could have many
2441 futher 'compare:' and 'reduced:' statements as long as there remain any
2442 non-ambiguous sequence entries.
2444 For the frame of function 'b' in both cases there are different
2445 possible '$pc' values ('0x4004cc' or '0x4004ce'), therefore this frame
2446 is also ambigous. The only non-ambiguous frame is the one for function
2447 'a', therefore this one is displayed to the user while the ambiguous
2450 There can be also reasons why printing of frame argument values at
2451 function entry may fail:
2454 static void __attribute__((noinline, noclone)) c (int i) { v++; }
2455 static void __attribute__((noinline, noclone)) a (int i);
2456 static void __attribute__((noinline, noclone)) b (int i) { a (i); }
2457 static void __attribute__((noinline, noclone)) a (int i)
2458 { if (i) b (i - 1); else c (0); }
2459 int main (void) { a (5); return 0; }
2462 #0 c (i=i@entry=0) at t.c:2
2463 #1 0x0000000000400428 in a (DW_OP_GNU_entry_value resolving has found
2464 function "a" at 0x400420 can call itself via tail calls
2465 i=<optimized out>) at t.c:6
2466 #2 0x000000000040036e in main () at t.c:7
2468 GDB cannot find out from the inferior state if and how many times did
2469 function 'a' call itself (via function 'b') as these calls would be tail
2470 calls. Such tail calls would modify thue 'i' variable, therefore GDB
2471 cannot be sure the value it knows would be right - GDB prints
2472 '<optimized out>' instead.
2475 File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Optimized Code, Up: Top
2477 12 C Preprocessor Macros
2478 ************************
2480 Some languages, such as C and C++, provide a way to define and invoke
2481 "preprocessor macros" which expand into strings of tokens. GDB can
2482 evaluate expressions containing macro invocations, show the result of
2483 macro expansion, and show a macro's definition, including where it was
2486 You may need to compile your program specially to provide GDB with
2487 information about preprocessor macros. Most compilers do not include
2488 macros in their debugging information, even when you compile with the
2489 '-g' flag. *Note Compilation::.
2491 A program may define a macro at one point, remove that definition
2492 later, and then provide a different definition after that. Thus, at
2493 different points in the program, a macro may have different definitions,
2494 or have no definition at all. If there is a current stack frame, GDB
2495 uses the macros in scope at that frame's source code line. Otherwise,
2496 GDB uses the macros in scope at the current listing location; see *note
2499 Whenever GDB evaluates an expression, it always expands any macro
2500 invocations present in the expression. GDB also provides the following
2501 commands for working with macros explicitly.
2503 'macro expand EXPRESSION'
2504 'macro exp EXPRESSION'
2505 Show the results of expanding all preprocessor macro invocations in
2506 EXPRESSION. Since GDB simply expands macros, but does not parse
2507 the result, EXPRESSION need not be a valid expression; it can be
2508 any string of tokens.
2510 'macro expand-once EXPRESSION'
2511 'macro exp1 EXPRESSION'
2512 (This command is not yet implemented.) Show the results of
2513 expanding those preprocessor macro invocations that appear
2514 explicitly in EXPRESSION. Macro invocations appearing in that
2515 expansion are left unchanged. This command allows you to see the
2516 effect of a particular macro more clearly, without being confused
2517 by further expansions. Since GDB simply expands macros, but does
2518 not parse the result, EXPRESSION need not be a valid expression; it
2519 can be any string of tokens.
2521 'info macro [-a|-all] [--] MACRO'
2522 Show the current definition or all definitions of the named MACRO,
2523 and describe the source location or compiler command-line where
2524 that definition was established. The optional double dash is to
2525 signify the end of argument processing and the beginning of MACRO
2526 for non C-like macros where the macro may begin with a hyphen.
2528 'info macros LINESPEC'
2529 Show all macro definitions that are in effect at the location
2530 specified by LINESPEC, and describe the source location or compiler
2531 command-line where those definitions were established.
2533 'macro define MACRO REPLACEMENT-LIST'
2534 'macro define MACRO(ARGLIST) REPLACEMENT-LIST'
2535 Introduce a definition for a preprocessor macro named MACRO,
2536 invocations of which are replaced by the tokens given in
2537 REPLACEMENT-LIST. The first form of this command defines an
2538 "object-like" macro, which takes no arguments; the second form
2539 defines a "function-like" macro, which takes the arguments given in
2542 A definition introduced by this command is in scope in every
2543 expression evaluated in GDB, until it is removed with the 'macro
2544 undef' command, described below. The definition overrides all
2545 definitions for MACRO present in the program being debugged, as
2546 well as any previous user-supplied definition.
2549 Remove any user-supplied definition for the macro named MACRO.
2550 This command only affects definitions provided with the 'macro
2551 define' command, described above; it cannot remove definitions
2552 present in the program being debugged.
2555 List all the macros defined using the 'macro define' command.
2557 Here is a transcript showing the above commands in action. First, we
2558 show our source files:
2565 #define ADD(x) (M + x)
2570 printf ("Hello, world!\n");
2572 printf ("We're so creative.\n");
2574 printf ("Goodbye, world!\n");
2580 Now, we compile the program using the GNU C compiler, GCC. We pass
2581 the '-gdwarf-2'(1) _and_ '-g3' flags to ensure the compiler includes
2582 information about preprocessor macros in the debugging information.
2584 $ gcc -gdwarf-2 -g3 sample.c -o sample
2587 Now, we start GDB on our sample program:
2590 GNU gdb 2002-05-06-cvs
2591 Copyright 2002 Free Software Foundation, Inc.
2592 GDB is free software, ...
2595 We can expand macros and examine their definitions, even when the
2596 program is not running. GDB uses the current listing position to decide
2597 which macro definitions are in scope:
2602 5 #define ADD(x) (M + x)
2607 10 printf ("Hello, world!\n");
2609 12 printf ("We're so creative.\n");
2610 (gdb) info macro ADD
2611 Defined at /home/jimb/gdb/macros/play/sample.c:5
2612 #define ADD(x) (M + x)
2614 Defined at /home/jimb/gdb/macros/play/sample.h:1
2615 included at /home/jimb/gdb/macros/play/sample.c:2
2617 (gdb) macro expand ADD(1)
2618 expands to: (42 + 1)
2619 (gdb) macro expand-once ADD(1)
2620 expands to: once (M + 1)
2623 In the example above, note that 'macro expand-once' expands only the
2624 macro invocation explicit in the original text -- the invocation of
2625 'ADD' -- but does not expand the invocation of the macro 'M', which was
2626 introduced by 'ADD'.
2628 Once the program is running, GDB uses the macro definitions in force
2629 at the source line of the current stack frame:
2632 Breakpoint 1 at 0x8048370: file sample.c, line 10.
2634 Starting program: /home/jimb/gdb/macros/play/sample
2636 Breakpoint 1, main () at sample.c:10
2637 10 printf ("Hello, world!\n");
2640 At line 10, the definition of the macro 'N' at line 9 is in force:
2643 Defined at /home/jimb/gdb/macros/play/sample.c:9
2645 (gdb) macro expand N Q M
2651 As we step over directives that remove 'N''s definition, and then
2652 give it a new definition, GDB finds the definition (or lack thereof) in
2653 force at each point:
2657 12 printf ("We're so creative.\n");
2659 The symbol `N' has no definition as a C/C++ preprocessor macro
2660 at /home/jimb/gdb/macros/play/sample.c:12
2663 14 printf ("Goodbye, world!\n");
2665 Defined at /home/jimb/gdb/macros/play/sample.c:13
2667 (gdb) macro expand N Q M
2668 expands to: 1729 < 42
2673 In addition to source files, macros can be defined on the compilation
2674 command line using the '-DNAME=VALUE' syntax. For macros defined in
2675 such a way, GDB displays the location of their definition as line zero
2676 of the source file submitted to the compiler.
2678 (gdb) info macro __STDC__
2679 Defined at /home/jimb/gdb/macros/play/sample.c:0
2683 ---------- Footnotes ----------
2685 (1) This is the minimum. Recent versions of GCC support '-gdwarf-3'
2686 and '-gdwarf-4'; we recommend always choosing the most recent version of
2690 File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top
2695 In some applications, it is not feasible for the debugger to interrupt
2696 the program's execution long enough for the developer to learn anything
2697 helpful about its behavior. If the program's correctness depends on its
2698 real-time behavior, delays introduced by a debugger might cause the
2699 program to change its behavior drastically, or perhaps fail, even when
2700 the code itself is correct. It is useful to be able to observe the
2701 program's behavior without interrupting it.
2703 Using GDB's 'trace' and 'collect' commands, you can specify locations
2704 in the program, called "tracepoints", and arbitrary expressions to
2705 evaluate when those tracepoints are reached. Later, using the 'tfind'
2706 command, you can examine the values those expressions had when the
2707 program hit the tracepoints. The expressions may also denote objects in
2708 memory--structures or arrays, for example--whose values GDB should
2709 record; while visiting a particular tracepoint, you may inspect those
2710 objects as if they were in memory at that moment. However, because GDB
2711 records these values without interacting with you, it can do so quickly
2712 and unobtrusively, hopefully not disturbing the program's behavior.
2714 The tracepoint facility is currently available only for remote
2715 targets. *Note Targets::. In addition, your remote target must know
2716 how to collect trace data. This functionality is implemented in the
2717 remote stub; however, none of the stubs distributed with GDB support
2718 tracepoints as of this writing. The format of the remote packets used
2719 to implement tracepoints are described in *note Tracepoint Packets::.
2721 It is also possible to get trace data from a file, in a manner
2722 reminiscent of corefiles; you specify the filename, and use 'tfind' to
2723 search through the file. *Note Trace Files::, for more details.
2725 This chapter describes the tracepoint commands and features.
2730 * Analyze Collected Data::
2731 * Tracepoint Variables::
2735 File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints
2737 13.1 Commands to Set Tracepoints
2738 ================================
2740 Before running such a "trace experiment", an arbitrary number of
2741 tracepoints can be set. A tracepoint is actually a special type of
2742 breakpoint (*note Set Breaks::), so you can manipulate it using standard
2743 breakpoint commands. For instance, as with breakpoints, tracepoint
2744 numbers are successive integers starting from one, and many of the
2745 commands associated with tracepoints take the tracepoint number as their
2746 argument, to identify which tracepoint to work on.
2748 For each tracepoint, you can specify, in advance, some arbitrary set
2749 of data that you want the target to collect in the trace buffer when it
2750 hits that tracepoint. The collected data can include registers, local
2751 variables, or global data. Later, you can use GDB commands to examine
2752 the values these data had at the time the tracepoint was hit.
2754 Tracepoints do not support every breakpoint feature. Ignore counts
2755 on tracepoints have no effect, and tracepoints cannot run GDB commands
2756 when they are hit. Tracepoints may not be thread-specific either.
2758 Some targets may support "fast tracepoints", which are inserted in a
2759 different way (such as with a jump instead of a trap), that is faster
2760 but possibly restricted in where they may be installed.
2762 Regular and fast tracepoints are dynamic tracing facilities, meaning
2763 that they can be used to insert tracepoints at (almost) any location in
2764 the target. Some targets may also support controlling "static
2765 tracepoints" from GDB. With static tracing, a set of instrumentation
2766 points, also known as "markers", are embedded in the target program, and
2767 can be activated or deactivated by name or address. These are usually
2768 placed at locations which facilitate investigating what the target is
2769 actually doing. GDB's support for static tracing includes being able to
2770 list instrumentation points, and attach them with GDB defined high level
2771 tracepoints that expose the whole range of convenience of GDB's
2772 tracepoints support. Namely, support for collecting registers values
2773 and values of global or local (to the instrumentation point) variables;
2774 tracepoint conditions and trace state variables. The act of installing
2775 a GDB static tracepoint on an instrumentation point, or marker, is
2776 referred to as "probing" a static tracepoint marker.
2778 'gdbserver' supports tracepoints on some target systems. *Note
2779 Tracepoints support in 'gdbserver': Server.
2781 This section describes commands to set tracepoints and associated
2782 conditions and actions.
2786 * Create and Delete Tracepoints::
2787 * Enable and Disable Tracepoints::
2788 * Tracepoint Passcounts::
2789 * Tracepoint Conditions::
2790 * Trace State Variables::
2791 * Tracepoint Actions::
2792 * Listing Tracepoints::
2793 * Listing Static Tracepoint Markers::
2794 * Starting and Stopping Trace Experiments::
2795 * Tracepoint Restrictions::
2798 File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints
2800 13.1.1 Create and Delete Tracepoints
2801 ------------------------------------
2804 The 'trace' command is very similar to the 'break' command. Its
2805 argument LOCATION can be a source line, a function name, or an
2806 address in the target program. *Note Specify Location::. The
2807 'trace' command defines a tracepoint, which is a point in the
2808 target program where the debugger will briefly stop, collect some
2809 data, and then allow the program to continue. Setting a tracepoint
2810 or changing its actions takes effect immediately if the remote stub
2811 supports the 'InstallInTrace' feature (*note install tracepoint in
2812 tracing::). If remote stub doesn't support the 'InstallInTrace'
2813 feature, all these changes don't take effect until the next
2814 'tstart' command, and once a trace experiment is running, further
2815 changes will not have any effect until the next trace experiment
2816 starts. In addition, GDB supports "pending
2817 tracepoints"--tracepoints whose address is not yet resolved. (This
2818 is similar to pending breakpoints.) Pending tracepoints are not
2819 downloaded to the target and not installed until they are resolved.
2820 The resolution of pending tracepoints requires GDB support--when
2821 debugging with the remote target, and GDB disconnects from the
2822 remote stub (*note disconnected tracing::), pending tracepoints can
2823 not be resolved (and downloaded to the remote stub) while GDB is
2826 Here are some examples of using the 'trace' command:
2828 (gdb) trace foo.c:121 // a source file and line number
2830 (gdb) trace +2 // 2 lines forward
2832 (gdb) trace my_function // first source line of function
2834 (gdb) trace *my_function // EXACT start address of function
2836 (gdb) trace *0x2117c4 // an address
2838 You can abbreviate 'trace' as 'tr'.
2840 'trace LOCATION if COND'
2841 Set a tracepoint with condition COND; evaluate the expression COND
2842 each time the tracepoint is reached, and collect data only if the
2843 value is nonzero--that is, if COND evaluates as true. *Note
2844 Tracepoint Conditions: Tracepoint Conditions, for more information
2845 on tracepoint conditions.
2847 'ftrace LOCATION [ if COND ]'
2848 The 'ftrace' command sets a fast tracepoint. For targets that
2849 support them, fast tracepoints will use a more efficient but
2850 possibly less general technique to trigger data collection, such as
2851 a jump instruction instead of a trap, or some sort of hardware
2852 support. It may not be possible to create a fast tracepoint at the
2853 desired location, in which case the command will exit with an
2854 explanatory message.
2856 GDB handles arguments to 'ftrace' exactly as for 'trace'.
2858 On 32-bit x86-architecture systems, fast tracepoints normally need
2859 to be placed at an instruction that is 5 bytes or longer, but can
2860 be placed at 4-byte instructions if the low 64K of memory of the
2861 target program is available to install trampolines. Some Unix-type
2862 systems, such as GNU/Linux, exclude low addresses from the
2863 program's address space; but for instance with the Linux kernel it
2864 is possible to let GDB use this area by doing a 'sysctl' command to
2865 set the 'mmap_min_addr' kernel parameter, as in
2867 sudo sysctl -w vm.mmap_min_addr=32768
2869 which sets the low address to 32K, which leaves plenty of room for
2870 trampolines. The minimum address should be set to a page boundary.
2872 'strace LOCATION [ if COND ]'
2873 The 'strace' command sets a static tracepoint. For targets that
2874 support it, setting a static tracepoint probes a static
2875 instrumentation point, or marker, found at LOCATION. It may not be
2876 possible to set a static tracepoint at the desired location, in
2877 which case the command will exit with an explanatory message.
2879 GDB handles arguments to 'strace' exactly as for 'trace', with the
2880 addition that the user can also specify '-m MARKER' as LOCATION.
2881 This probes the marker identified by the MARKER string identifier.
2882 This identifier depends on the static tracepoint backend library
2883 your program is using. You can find all the marker identifiers in
2884 the 'ID' field of the 'info static-tracepoint-markers' command
2885 output. *Note Listing Static Tracepoint Markers: Listing Static
2886 Tracepoint Markers. For example, in the following small program
2887 using the UST tracing engine:
2891 trace_mark(ust, bar33, "str %s", "FOOBAZ");
2894 the marker id is composed of joining the first two arguments to the
2895 'trace_mark' call with a slash, which translates to:
2897 (gdb) info static-tracepoint-markers
2898 Cnt Enb ID Address What
2899 1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22
2903 so you may probe the marker above with:
2905 (gdb) strace -m ust/bar33
2907 Static tracepoints accept an extra collect action -- 'collect
2908 $_sdata'. This collects arbitrary user data passed in the probe
2909 point call to the tracing library. In the UST example above,
2910 you'll see that the third argument to 'trace_mark' is a printf-like
2911 format string. The user data is then the result of running that
2912 formating string against the following arguments. Note that 'info
2913 static-tracepoint-markers' command output lists that format string
2914 in the 'Data:' field.
2916 You can inspect this data when analyzing the trace buffer, by
2917 printing the $_sdata variable like any other variable available to
2918 GDB. *Note Tracepoint Action Lists: Tracepoint Actions.
2920 The convenience variable '$tpnum' records the tracepoint number of
2921 the most recently set tracepoint.
2923 'delete tracepoint [NUM]'
2924 Permanently delete one or more tracepoints. With no argument, the
2925 default is to delete all tracepoints. Note that the regular
2926 'delete' command can remove tracepoints also.
2930 (gdb) delete trace 1 2 3 // remove three tracepoints
2932 (gdb) delete trace // remove all tracepoints
2934 You can abbreviate this command as 'del tr'.
2937 File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints
2939 13.1.2 Enable and Disable Tracepoints
2940 -------------------------------------
2942 These commands are deprecated; they are equivalent to plain 'disable'
2945 'disable tracepoint [NUM]'
2946 Disable tracepoint NUM, or all tracepoints if no argument NUM is
2947 given. A disabled tracepoint will have no effect during a trace
2948 experiment, but it is not forgotten. You can re-enable a disabled
2949 tracepoint using the 'enable tracepoint' command. If the command
2950 is issued during a trace experiment and the debug target has
2951 support for disabling tracepoints during a trace experiment, then
2952 the change will be effective immediately. Otherwise, it will be
2953 applied to the next trace experiment.
2955 'enable tracepoint [NUM]'
2956 Enable tracepoint NUM, or all tracepoints. If this command is
2957 issued during a trace experiment and the debug target supports
2958 enabling tracepoints during a trace experiment, then the enabled
2959 tracepoints will become effective immediately. Otherwise, they
2960 will become effective the next time a trace experiment is run.
2963 File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Conditions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints
2965 13.1.3 Tracepoint Passcounts
2966 ----------------------------
2968 'passcount [N [NUM]]'
2969 Set the "passcount" of a tracepoint. The passcount is a way to
2970 automatically stop a trace experiment. If a tracepoint's passcount
2971 is N, then the trace experiment will be automatically stopped on
2972 the N'th time that tracepoint is hit. If the tracepoint number NUM
2973 is not specified, the 'passcount' command sets the passcount of the
2974 most recently defined tracepoint. If no passcount is given, the
2975 trace experiment will run until stopped explicitly by the user.
2979 (gdb) passcount 5 2 // Stop on the 5th execution of
2982 (gdb) passcount 12 // Stop on the 12th execution of the
2983 // most recently defined tracepoint.
2989 (gdb) pass 1 // Stop tracing when foo has been
2990 // executed 3 times OR when bar has
2991 // been executed 2 times
2992 // OR when baz has been executed 1 time.
2995 File: gdb.info, Node: Tracepoint Conditions, Next: Trace State Variables, Prev: Tracepoint Passcounts, Up: Set Tracepoints
2997 13.1.4 Tracepoint Conditions
2998 ----------------------------
3000 The simplest sort of tracepoint collects data every time your program
3001 reaches a specified place. You can also specify a "condition" for a
3002 tracepoint. A condition is just a Boolean expression in your
3003 programming language (*note Expressions: Expressions.). A tracepoint
3004 with a condition evaluates the expression each time your program reaches
3005 it, and data collection happens only if the condition is true.
3007 Tracepoint conditions can be specified when a tracepoint is set, by
3008 using 'if' in the arguments to the 'trace' command. *Note Setting
3009 Tracepoints: Create and Delete Tracepoints. They can also be set or
3010 changed at any time with the 'condition' command, just as with
3013 Unlike breakpoint conditions, GDB does not actually evaluate the
3014 conditional expression itself. Instead, GDB encodes the expression into
3015 an agent expression (*note Agent Expressions::) suitable for execution
3016 on the target, independently of GDB. Global variables become raw memory
3017 locations, locals become stack accesses, and so forth.
3019 For instance, suppose you have a function that is usually called
3020 frequently, but should not be called after an error has occurred. You
3021 could use the following tracepoint command to collect data about calls
3022 of that function that happen while the error code is propagating through
3023 the program; an unconditional tracepoint could end up collecting
3024 thousands of useless trace frames that you would have to search through.
3026 (gdb) trace normal_operation if errcode > 0
3029 File: gdb.info, Node: Trace State Variables, Next: Tracepoint Actions, Prev: Tracepoint Conditions, Up: Set Tracepoints
3031 13.1.5 Trace State Variables
3032 ----------------------------
3034 A "trace state variable" is a special type of variable that is created
3035 and managed by target-side code. The syntax is the same as that for
3036 GDB's convenience variables (a string prefixed with "$"), but they are
3037 stored on the target. They must be created explicitly, using a
3038 'tvariable' command. They are always 64-bit signed integers.
3040 Trace state variables are remembered by GDB, and downloaded to the
3041 target along with tracepoint information when the trace experiment
3042 starts. There are no intrinsic limits on the number of trace state
3043 variables, beyond memory limitations of the target.
3045 Although trace state variables are managed by the target, you can use
3046 them in print commands and expressions as if they were convenience
3047 variables; GDB will get the current value from the target while the
3048 trace experiment is running. Trace state variables share the same
3049 namespace as other "$" variables, which means that you cannot have trace
3050 state variables with names like '$23' or '$pc', nor can you have a trace
3051 state variable and a convenience variable with the same name.
3053 'tvariable $NAME [ = EXPRESSION ]'
3054 The 'tvariable' command creates a new trace state variable named
3055 '$NAME', and optionally gives it an initial value of EXPRESSION.
3056 EXPRESSION is evaluated when this command is entered; the result
3057 will be converted to an integer if possible, otherwise GDB will
3058 report an error. A subsequent 'tvariable' command specifying the
3059 same name does not create a variable, but instead assigns the
3060 supplied initial value to the existing variable of that name,
3061 overwriting any previous initial value. The default initial value
3065 List all the trace state variables along with their initial values.
3066 Their current values may also be displayed, if the trace experiment
3067 is currently running.
3069 'delete tvariable [ $NAME ... ]'
3070 Delete the given trace state variables, or all of them if no
3071 arguments are specified.
3074 File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Trace State Variables, Up: Set Tracepoints
3076 13.1.6 Tracepoint Action Lists
3077 ------------------------------
3080 This command will prompt for a list of actions to be taken when the
3081 tracepoint is hit. If the tracepoint number NUM is not specified,
3082 this command sets the actions for the one that was most recently
3083 defined (so that you can define a tracepoint and then say 'actions'
3084 without bothering about its number). You specify the actions
3085 themselves on the following lines, one action at a time, and
3086 terminate the actions list with a line containing just 'end'. So
3087 far, the only defined actions are 'collect', 'teval', and
3090 'actions' is actually equivalent to 'commands' (*note Breakpoint
3091 Command Lists: Break Commands.), except that only the defined
3092 actions are allowed; any other GDB command is rejected.
3094 To remove all actions from a tracepoint, type 'actions NUM' and
3095 follow it immediately with 'end'.
3097 (gdb) collect DATA // collect some data
3099 (gdb) while-stepping 5 // single-step 5 times, collect data
3101 (gdb) end // signals the end of actions.
3103 In the following example, the action list begins with 'collect'
3104 commands indicating the things to be collected when the tracepoint
3105 is hit. Then, in order to single-step and collect additional data
3106 following the tracepoint, a 'while-stepping' command is used,
3107 followed by the list of things to be collected after each step in a
3108 sequence of single steps. The 'while-stepping' command is
3109 terminated by its own separate 'end' command. Lastly, the action
3110 list is terminated by an 'end' command.
3114 Enter actions for tracepoint 1, one per line:
3118 > collect $pc, arr[i]
3122 'collect[/MODS] EXPR1, EXPR2, ...'
3123 Collect values of the given expressions when the tracepoint is hit.
3124 This command accepts a comma-separated list of any valid
3125 expressions. In addition to global, static, or local variables,
3126 the following special arguments are supported:
3129 Collect all registers.
3132 Collect all function arguments.
3135 Collect all local variables.
3138 Collect the return address. This is helpful if you want to
3139 see more of a backtrace.
3142 Collects the number of arguments from the static probe at
3143 which the tracepoint is located. *Note Static Probe Points::.
3146 N is an integer between 0 and 11. Collects the Nth argument
3147 from the static probe at which the tracepoint is located.
3148 *Note Static Probe Points::.
3151 Collect static tracepoint marker specific data. Only
3152 available for static tracepoints. *Note Tracepoint Action
3153 Lists: Tracepoint Actions. On the UST static tracepoints
3154 library backend, an instrumentation point resembles a 'printf'
3155 function call. The tracing library is able to collect user
3156 specified data formatted to a character string using the
3157 format provided by the programmer that instrumented the
3158 program. Other backends have similar mechanisms. Here's an
3159 example of a UST marker call:
3161 const char master_name[] = "$your_name";
3162 trace_mark(channel1, marker1, "hello %s", master_name)
3164 In this case, collecting '$_sdata' collects the string 'hello
3165 $yourname'. When analyzing the trace buffer, you can inspect
3166 '$_sdata' like any other variable available to GDB.
3168 You can give several consecutive 'collect' commands, each one with
3169 a single argument, or one 'collect' command with several arguments
3170 separated by commas; the effect is the same.
3172 The optional MODS changes the usual handling of the arguments. 's'
3173 requests that pointers to chars be handled as strings, in
3174 particular collecting the contents of the memory being pointed at,
3175 up to the first zero. The upper bound is by default the value of
3176 the 'print elements' variable; if 's' is followed by a decimal
3177 number, that is the upper bound instead. So for instance
3178 'collect/s25 mystr' collects as many as 25 characters at 'mystr'.
3180 The command 'info scope' (*note info scope: Symbols.) is
3181 particularly useful for figuring out what data to collect.
3183 'teval EXPR1, EXPR2, ...'
3184 Evaluate the given expressions when the tracepoint is hit. This
3185 command accepts a comma-separated list of expressions. The results
3186 are discarded, so this is mainly useful for assigning values to
3187 trace state variables (*note Trace State Variables::) without
3188 adding those values to the trace buffer, as would be the case if
3189 the 'collect' action were used.
3192 Perform N single-step instruction traces after the tracepoint,
3193 collecting new data after each step. The 'while-stepping' command
3194 is followed by the list of what to collect while stepping (followed
3195 by its own 'end' command):
3198 > collect $regs, myglobal
3202 Note that '$pc' is not automatically collected by 'while-stepping';
3203 you need to explicitly collect that register if you need it. You
3204 may abbreviate 'while-stepping' as 'ws' or 'stepping'.
3206 'set default-collect EXPR1, EXPR2, ...'
3207 This variable is a list of expressions to collect at each
3208 tracepoint hit. It is effectively an additional 'collect' action
3209 prepended to every tracepoint action list. The expressions are
3210 parsed individually for each tracepoint, so for instance a variable
3211 named 'xyz' may be interpreted as a global for one tracepoint, and
3212 a local for another, as appropriate to the tracepoint's location.
3214 'show default-collect'
3215 Show the list of expressions that are collected by default at each
3219 File: gdb.info, Node: Listing Tracepoints, Next: Listing Static Tracepoint Markers, Prev: Tracepoint Actions, Up: Set Tracepoints
3221 13.1.7 Listing Tracepoints
3222 --------------------------
3224 'info tracepoints [NUM...]'
3225 Display information about the tracepoint NUM. If you don't specify
3226 a tracepoint number, displays information about all the tracepoints
3227 defined so far. The format is similar to that used for 'info
3228 breakpoints'; in fact, 'info tracepoints' is the same command,
3229 simply restricting itself to tracepoints.
3231 A tracepoint's listing may include additional information specific
3234 * its passcount as given by the 'passcount N' command
3236 * the state about installed on target of each location
3239 Num Type Disp Enb Address What
3240 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7
3242 collect globfoo, $regs
3247 2 tracepoint keep y <MULTIPLE>
3249 2.1 y 0x0804859c in func4 at change-loc.h:35
3251 2.2 y 0xb7ffc480 in func4 at change-loc.h:35
3253 2.3 y <PENDING> set_tracepoint
3254 3 tracepoint keep y 0x080485b1 in foo at change-loc.c:29
3255 not installed on target
3258 This command can be abbreviated 'info tp'.
3261 File: gdb.info, Node: Listing Static Tracepoint Markers, Next: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints
3263 13.1.8 Listing Static Tracepoint Markers
3264 ----------------------------------------
3266 'info static-tracepoint-markers'
3267 Display information about all static tracepoint markers defined in
3270 For each marker, the following columns are printed:
3273 An incrementing counter, output to help readability. This is
3274 not a stable identifier.
3276 The marker ID, as reported by the target.
3277 _Enabled or Disabled_
3278 Probed markers are tagged with 'y'. 'n' identifies marks that
3281 Where the marker is in your program, as a memory address.
3283 Where the marker is in the source for your program, as a file
3284 and line number. If the debug information included in the
3285 program does not allow GDB to locate the source of the marker,
3286 this column will be left blank.
3288 In addition, the following information may be printed for each
3292 User data passed to the tracing library by the marker call.
3293 In the UST backend, this is the format string passed as
3294 argument to the marker call.
3295 _Static tracepoints probing the marker_
3296 The list of static tracepoints attached to the marker.
3298 (gdb) info static-tracepoint-markers
3299 Cnt ID Enb Address What
3300 1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25
3301 Data: number1 %d number2 %d
3302 Probed by static tracepoints: #2
3303 2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24
3308 File: gdb.info, Node: Starting and Stopping Trace Experiments, Next: Tracepoint Restrictions, Prev: Listing Static Tracepoint Markers, Up: Set Tracepoints
3310 13.1.9 Starting and Stopping Trace Experiments
3311 ----------------------------------------------
3314 This command starts the trace experiment, and begins collecting
3315 data. It has the side effect of discarding all the data collected
3316 in the trace buffer during the previous trace experiment. If any
3317 arguments are supplied, they are taken as a note and stored with
3318 the trace experiment's state. The notes may be arbitrary text, and
3319 are especially useful with disconnected tracing in a multi-user
3320 context; the notes can explain what the trace is doing, supply user
3321 contact information, and so forth.
3324 This command stops the trace experiment. If any arguments are
3325 supplied, they are recorded with the experiment as a note. This is
3326 useful if you are stopping a trace started by someone else, for
3327 instance if the trace is interfering with the system's behavior and
3328 needs to be stopped quickly.
3330 *Note*: a trace experiment and data collection may stop
3331 automatically if any tracepoint's passcount is reached (*note
3332 Tracepoint Passcounts::), or if the trace buffer becomes full.
3335 This command displays the status of the current trace data
3338 Here is an example of the commands we described so far:
3340 (gdb) trace gdb_c_test
3342 Enter actions for tracepoint #1, one per line.
3343 > collect $regs,$locals,$args
3352 You can choose to continue running the trace experiment even if GDB
3353 disconnects from the target, voluntarily or involuntarily. For commands
3354 such as 'detach', the debugger will ask what you want to do with the
3355 trace. But for unexpected terminations (GDB crash, network outage), it
3356 would be unfortunate to lose hard-won trace data, so the variable
3357 'disconnected-tracing' lets you decide whether the trace should continue
3358 running without GDB.
3360 'set disconnected-tracing on'
3361 'set disconnected-tracing off'
3362 Choose whether a tracing run should continue to run if GDB has
3363 disconnected from the target. Note that 'detach' or 'quit' will
3364 ask you directly what to do about a running trace no matter what
3365 this variable's setting, so the variable is mainly useful for
3366 handling unexpected situations, such as loss of the network.
3368 'show disconnected-tracing'
3369 Show the current choice for disconnected tracing.
3371 When you reconnect to the target, the trace experiment may or may not
3372 still be running; it might have filled the trace buffer in the meantime,
3373 or stopped for one of the other reasons. If it is running, it will
3374 continue after reconnection.
3376 Upon reconnection, the target will upload information about the
3377 tracepoints in effect. GDB will then compare that information to the
3378 set of tracepoints currently defined, and attempt to match them up,
3379 allowing for the possibility that the numbers may have changed due to
3380 creation and deletion in the meantime. If one of the target's
3381 tracepoints does not match any in GDB, the debugger will create a new
3382 tracepoint, so that you have a number with which to specify that
3383 tracepoint. This matching-up process is necessarily heuristic, and it
3384 may result in useless tracepoints being created; you may simply delete
3385 them if they are of no use.
3387 If your target agent supports a "circular trace buffer", then you can
3388 run a trace experiment indefinitely without filling the trace buffer;
3389 when space runs out, the agent deletes already-collected trace frames,
3390 oldest first, until there is enough room to continue collecting. This
3391 is especially useful if your tracepoints are being hit too often, and
3392 your trace gets terminated prematurely because the buffer is full. To
3393 ask for a circular trace buffer, simply set 'circular-trace-buffer' to
3394 on. You can set this at any time, including during tracing; if the
3395 agent can do it, it will change buffer handling on the fly, otherwise it
3396 will not take effect until the next run.
3398 'set circular-trace-buffer on'
3399 'set circular-trace-buffer off'
3400 Choose whether a tracing run should use a linear or circular buffer
3401 for trace data. A linear buffer will not lose any trace data, but
3402 may fill up prematurely, while a circular buffer will discard old
3403 trace data, but it will have always room for the latest tracepoint
3406 'show circular-trace-buffer'
3407 Show the current choice for the trace buffer. Note that this may
3408 not match the agent's current buffer handling, nor is it guaranteed
3409 to match the setting that might have been in effect during a past
3410 run, for instance if you are looking at frames from a trace file.
3412 'set trace-buffer-size N'
3413 'set trace-buffer-size unlimited'
3414 Request that the target use a trace buffer of N bytes. Not all
3415 targets will honor the request; they may have a compiled-in size
3416 for the trace buffer, or some other limitation. Set to a value of
3417 'unlimited' or '-1' to let the target use whatever size it likes.
3418 This is also the default.
3420 'show trace-buffer-size'
3421 Show the current requested size for the trace buffer. Note that
3422 this will only match the actual size if the target supports
3423 size-setting, and was able to handle the requested size. For
3424 instance, if the target can only change buffer size between runs,
3425 this variable will not reflect the change until the next run
3426 starts. Use 'tstatus' to get a report of the actual buffer size.
3428 'set trace-user TEXT'
3432 'set trace-notes TEXT'
3433 Set the trace run's notes.
3436 Show the trace run's notes.
3438 'set trace-stop-notes TEXT'
3439 Set the trace run's stop notes. The handling of the note is as for
3440 'tstop' arguments; the set command is convenient way to fix a stop
3441 note that is mistaken or incomplete.
3443 'show trace-stop-notes'
3444 Show the trace run's stop notes.
3447 File: gdb.info, Node: Tracepoint Restrictions, Prev: Starting and Stopping Trace Experiments, Up: Set Tracepoints
3449 13.1.10 Tracepoint Restrictions
3450 -------------------------------
3452 There are a number of restrictions on the use of tracepoints. As
3453 described above, tracepoint data gathering occurs on the target without
3454 interaction from GDB. Thus the full capabilities of the debugger are
3455 not available during data gathering, and then at data examination time,
3456 you will be limited by only having what was collected. The following
3457 items describe some common problems, but it is not exhaustive, and you
3458 may run into additional difficulties not mentioned here.
3460 * Tracepoint expressions are intended to gather objects (lvalues).
3461 Thus the full flexibility of GDB's expression evaluator is not
3462 available. You cannot call functions, cast objects to aggregate
3463 types, access convenience variables or modify values (except by
3464 assignment to trace state variables). Some language features may
3465 implicitly call functions (for instance Objective-C fields with
3466 accessors), and therefore cannot be collected either.
3468 * Collection of local variables, either individually or in bulk with
3469 '$locals' or '$args', during 'while-stepping' may behave
3470 erratically. The stepping action may enter a new scope (for
3471 instance by stepping into a function), or the location of the
3472 variable may change (for instance it is loaded into a register).
3473 The tracepoint data recorded uses the location information for the
3474 variables that is correct for the tracepoint location. When the
3475 tracepoint is created, it is not possible, in general, to determine
3476 where the steps of a 'while-stepping' sequence will advance the
3477 program--particularly if a conditional branch is stepped.
3479 * Collection of an incompletely-initialized or partially-destroyed
3480 object may result in something that GDB cannot display, or displays
3481 in a misleading way.
3483 * When GDB displays a pointer to character it automatically
3484 dereferences the pointer to also display characters of the string
3485 being pointed to. However, collecting the pointer during tracing
3486 does not automatically collect the string. You need to explicitly
3487 dereference the pointer and provide size information if you want to
3488 collect not only the pointer, but the memory pointed to. For
3489 example, '*ptr@50' can be used to collect the 50 element array
3490 pointed to by 'ptr'.
3492 * It is not possible to collect a complete stack backtrace at a
3493 tracepoint. Instead, you may collect the registers and a few
3494 hundred bytes from the stack pointer with something like
3495 '*(unsigned char *)$esp@300' (adjust to use the name of the actual
3496 stack pointer register on your target architecture, and the amount
3497 of stack you wish to capture). Then the 'backtrace' command will
3498 show a partial backtrace when using a trace frame. The number of
3499 stack frames that can be examined depends on the sizes of the
3500 frames in the collected stack. Note that if you ask for a block so
3501 large that it goes past the bottom of the stack, the target agent
3502 may report an error trying to read from an invalid address.
3504 * If you do not collect registers at a tracepoint, GDB can infer that
3505 the value of '$pc' must be the same as the address of the
3506 tracepoint and use that when you are looking at a trace frame for
3507 that tracepoint. However, this cannot work if the tracepoint has
3508 multiple locations (for instance if it was set in a function that
3509 was inlined), or if it has a 'while-stepping' loop. In those cases
3510 GDB will warn you that it can't infer '$pc', and default it to
3514 File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints
3516 13.2 Using the Collected Data
3517 =============================
3519 After the tracepoint experiment ends, you use GDB commands for examining
3520 the trace data. The basic idea is that each tracepoint collects a trace
3521 "snapshot" every time it is hit and another snapshot every time it
3522 single-steps. All these snapshots are consecutively numbered from zero
3523 and go into a buffer, and you can examine them later. The way you
3524 examine them is to "focus" on a specific trace snapshot. When the
3525 remote stub is focused on a trace snapshot, it will respond to all GDB
3526 requests for memory and registers by reading from the buffer which
3527 belongs to that snapshot, rather than from _real_ memory or registers of
3528 the program being debugged. This means that *all* GDB commands
3529 ('print', 'info registers', 'backtrace', etc.) will behave as if we
3530 were currently debugging the program state as it was when the tracepoint
3531 occurred. Any requests for data that are not in the buffer will fail.
3535 * tfind:: How to select a trace snapshot
3536 * tdump:: How to display all data for a snapshot
3537 * save tracepoints:: How to save tracepoints for a future run
3540 File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data
3545 The basic command for selecting a trace snapshot from the buffer is
3546 'tfind N', which finds trace snapshot number N, counting from zero. If
3547 no argument N is given, the next snapshot is selected.
3549 Here are the various forms of using the 'tfind' command.
3552 Find the first snapshot in the buffer. This is a synonym for
3553 'tfind 0' (since 0 is the number of the first snapshot).
3556 Stop debugging trace snapshots, resume _live_ debugging.
3559 Same as 'tfind none'.
3562 No argument means find the next trace snapshot.
3565 Find the previous trace snapshot before the current one. This
3566 permits retracing earlier steps.
3568 'tfind tracepoint NUM'
3569 Find the next snapshot associated with tracepoint NUM. Search
3570 proceeds forward from the last examined trace snapshot. If no
3571 argument NUM is given, it means find the next snapshot collected
3572 for the same tracepoint as the current snapshot.
3575 Find the next snapshot associated with the value ADDR of the
3576 program counter. Search proceeds forward from the last examined
3577 trace snapshot. If no argument ADDR is given, it means find the
3578 next snapshot with the same value of PC as the current snapshot.
3580 'tfind outside ADDR1, ADDR2'
3581 Find the next snapshot whose PC is outside the given range of
3582 addresses (exclusive).
3584 'tfind range ADDR1, ADDR2'
3585 Find the next snapshot whose PC is between ADDR1 and ADDR2
3588 'tfind line [FILE:]N'
3589 Find the next snapshot associated with the source line N. If the
3590 optional argument FILE is given, refer to line N in that source
3591 file. Search proceeds forward from the last examined trace
3592 snapshot. If no argument N is given, it means find the next line
3593 other than the one currently being examined; thus saying 'tfind
3594 line' repeatedly can appear to have the same effect as stepping
3595 from line to line in a _live_ debugging session.
3597 The default arguments for the 'tfind' commands are specifically
3598 designed to make it easy to scan through the trace buffer. For
3599 instance, 'tfind' with no argument selects the next trace snapshot, and
3600 'tfind -' with no argument selects the previous trace snapshot. So, by
3601 giving one 'tfind' command, and then simply hitting <RET> repeatedly you
3602 can examine all the trace snapshots in order. Or, by saying 'tfind -'
3603 and then hitting <RET> repeatedly you can examine the snapshots in
3604 reverse order. The 'tfind line' command with no argument selects the
3605 snapshot for the next source line executed. The 'tfind pc' command with
3606 no argument selects the next snapshot with the same program counter (PC)
3607 as the current frame. The 'tfind tracepoint' command with no argument
3608 selects the next trace snapshot collected by the same tracepoint as the
3611 In addition to letting you scan through the trace buffer manually,
3612 these commands make it easy to construct GDB scripts that scan through
3613 the trace buffer and print out whatever collected data you are
3614 interested in. Thus, if we want to examine the PC, FP, and SP registers
3615 from each trace frame in the buffer, we can say this:
3618 (gdb) while ($trace_frame != -1)
3619 > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
3620 $trace_frame, $pc, $sp, $fp
3624 Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
3625 Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
3626 Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
3627 Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
3628 Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
3629 Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
3630 Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
3631 Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
3632 Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
3633 Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
3634 Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
3636 Or, if we want to examine the variable 'X' at each source line in the
3640 (gdb) while ($trace_frame != -1)
3641 > printf "Frame %d, X == %d\n", $trace_frame, X
3650 File: gdb.info, Node: tdump, Next: save tracepoints, Prev: tfind, Up: Analyze Collected Data
3655 This command takes no arguments. It prints all the data collected at
3656 the current trace snapshot.
3660 Enter actions for tracepoint #2, one per line:
3661 > collect $regs, $locals, $args, gdb_long_test
3666 (gdb) tfind line 444
3667 #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
3669 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
3672 Data collected at tracepoint 2, trace frame 1:
3673 d0 0xc4aa0085 -995491707
3677 d4 0x71aea3d 119204413
3682 a1 0x3000668 50333288
3685 a4 0x3000698 50333336
3687 fp 0x30bf3c 0x30bf3c
3688 sp 0x30bf34 0x30bf34
3690 pc 0x20b2c8 0x20b2c8
3694 p = 0x20e5b4 "gdb-test"
3701 gdb_long_test = 17 '\021'
3705 'tdump' works by scanning the tracepoint's current collection actions
3706 and printing the value of each expression listed. So 'tdump' can fail,
3707 if after a run, you change the tracepoint's actions to mention variables
3708 that were not collected during the run.
3710 Also, for tracepoints with 'while-stepping' loops, 'tdump' uses the
3711 collected value of '$pc' to distinguish between trace frames that were
3712 collected at the tracepoint hit, and frames that were collected while
3713 stepping. This allows it to correctly choose whether to display the
3714 basic list of collections, or the collections from the body of the
3715 while-stepping loop. However, if '$pc' was not collected, then 'tdump'
3716 will always attempt to dump using the basic collection list, and may
3717 fail if a while-stepping frame does not include all the same data that
3718 is collected at the tracepoint hit.
3721 File: gdb.info, Node: save tracepoints, Prev: tdump, Up: Analyze Collected Data
3723 13.2.3 'save tracepoints FILENAME'
3724 ----------------------------------
3726 This command saves all current tracepoint definitions together with
3727 their actions and passcounts, into a file 'FILENAME' suitable for use in
3728 a later debugging session. To read the saved tracepoint definitions,
3729 use the 'source' command (*note Command Files::). The 'save-tracepoints'
3730 command is a deprecated alias for 'save tracepoints'
3733 File: gdb.info, Node: Tracepoint Variables, Next: Trace Files, Prev: Analyze Collected Data, Up: Tracepoints
3735 13.3 Convenience Variables for Tracepoints
3736 ==========================================
3738 '(int) $trace_frame'
3739 The current trace snapshot (a.k.a. "frame") number, or -1 if no
3740 snapshot is selected.
3743 The tracepoint for the current trace snapshot.
3746 The line number for the current trace snapshot.
3748 '(char []) $trace_file'
3749 The source file for the current trace snapshot.
3751 '(char []) $trace_func'
3752 The name of the function containing '$tracepoint'.
3754 Note: '$trace_file' is not suitable for use in 'printf', use 'output'
3757 Here's a simple example of using these convenience variables for
3758 stepping through all the trace snapshots and printing some of their
3759 data. Note that these are not the same as trace state variables, which
3760 are managed by the target.
3764 (gdb) while $trace_frame != -1
3765 > output $trace_file
3766 > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
3771 File: gdb.info, Node: Trace Files, Prev: Tracepoint Variables, Up: Tracepoints
3773 13.4 Using Trace Files
3774 ======================
3776 In some situations, the target running a trace experiment may no longer
3777 be available; perhaps it crashed, or the hardware was needed for a
3778 different activity. To handle these cases, you can arrange to dump the
3779 trace data into a file, and later use that file as a source of trace
3780 data, via the 'target tfile' command.
3782 'tsave [ -r ] FILENAME'
3783 'tsave [-ctf] DIRNAME'
3784 Save the trace data to FILENAME. By default, this command assumes
3785 that FILENAME refers to the host filesystem, so if necessary GDB
3786 will copy raw trace data up from the target and then save it. If
3787 the target supports it, you can also supply the optional argument
3788 '-r' ("remote") to direct the target to save the data directly into
3789 FILENAME in its own filesystem, which may be more efficient if the
3790 trace buffer is very large. (Note, however, that 'target tfile'
3791 can only read from files accessible to the host.) By default, this
3792 command will save trace frame in tfile format. You can supply the
3793 optional argument '-ctf' to save date in CTF format. The "Common
3794 Trace Format" (CTF) is proposed as a trace format that can be
3795 shared by multiple debugging and tracing tools. Please go to
3796 'http://www.efficios.com/ctf' to get more information.
3798 'target tfile FILENAME'
3799 'target ctf DIRNAME'
3800 Use the file named FILENAME or directory named DIRNAME as a source
3801 of trace data. Commands that examine data work as they do with a
3802 live target, but it is not possible to run any new trace
3803 experiments. 'tstatus' will report the state of the trace run at
3804 the moment the data was saved, as well as the current trace frame
3805 you are examining. FILENAME or DIRNAME must be on a filesystem
3806 accessible to the host.
3808 (gdb) target ctf ctf.ctf
3810 Found trace frame 0, tracepoint 2
3811 39 ++a; /* set tracepoint 1 here */
3813 Data collected at tracepoint 2, trace frame 0:
3817 c = {"123", "456", "789", "123", "456", "789"}
3818 d = {{{a = 1, b = 2}, {a = 3, b = 4}}, {{a = 5, b = 6}, {a = 7, b = 8}}}
3823 File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top
3825 14 Debugging Programs That Use Overlays
3826 ***************************************
3828 If your program is too large to fit completely in your target system's
3829 memory, you can sometimes use "overlays" to work around this problem.
3830 GDB provides some support for debugging programs that use overlays.
3834 * How Overlays Work:: A general explanation of overlays.
3835 * Overlay Commands:: Managing overlays in GDB.
3836 * Automatic Overlay Debugging:: GDB can find out which overlays are
3837 mapped by asking the inferior.
3838 * Overlay Sample Program:: A sample program using overlays.
3841 File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays
3843 14.1 How Overlays Work
3844 ======================
3846 Suppose you have a computer whose instruction address space is only 64
3847 kilobytes long, but which has much more memory which can be accessed by
3848 other means: special instructions, segment registers, or memory
3849 management hardware, for example. Suppose further that you want to
3850 adapt a program which is larger than 64 kilobytes to run on this system.
3852 One solution is to identify modules of your program which are
3853 relatively independent, and need not call each other directly; call
3854 these modules "overlays". Separate the overlays from the main program,
3855 and place their machine code in the larger memory. Place your main
3856 program in instruction memory, but leave at least enough space there to
3857 hold the largest overlay as well.
3859 Now, to call a function located in an overlay, you must first copy
3860 that overlay's machine code from the large memory into the space set
3861 aside for it in the instruction memory, and then jump to its entry point
3864 Data Instruction Larger
3865 Address Space Address Space Address Space
3866 +-----------+ +-----------+ +-----------+
3868 +-----------+ +-----------+ +-----------+<-- overlay 1
3869 | program | | main | .----| overlay 1 | load address
3870 | variables | | program | | +-----------+
3871 | and heap | | | | | |
3872 +-----------+ | | | +-----------+<-- overlay 2
3873 | | +-----------+ | | | load address
3874 +-----------+ | | | .-| overlay 2 |
3876 mapped --->+-----------+ | | +-----------+
3878 | overlay | <-' | | |
3879 | area | <---' +-----------+<-- overlay 3
3880 | | <---. | | load address
3881 +-----------+ `--| overlay 3 |
3890 The diagram (*note A code overlay::) shows a system with separate
3891 data and instruction address spaces. To map an overlay, the program
3892 copies its code from the larger address space to the instruction address
3893 space. Since the overlays shown here all use the same mapped address,
3894 only one may be mapped at a time. For a system with a single address
3895 space for data and instructions, the diagram would be similar, except
3896 that the program variables and heap would share an address space with
3897 the main program and the overlay area.
3899 An overlay loaded into instruction memory and ready for use is called
3900 a "mapped" overlay; its "mapped address" is its address in the
3901 instruction memory. An overlay not present (or only partially present)
3902 in instruction memory is called "unmapped"; its "load address" is its
3903 address in the larger memory. The mapped address is also called the
3904 "virtual memory address", or "VMA"; the load address is also called the
3905 "load memory address", or "LMA".
3907 Unfortunately, overlays are not a completely transparent way to adapt
3908 a program to limited instruction memory. They introduce a new set of
3909 global constraints you must keep in mind as you design your program:
3911 * Before calling or returning to a function in an overlay, your
3912 program must make sure that overlay is actually mapped. Otherwise,
3913 the call or return will transfer control to the right address, but
3914 in the wrong overlay, and your program will probably crash.
3916 * If the process of mapping an overlay is expensive on your system,
3917 you will need to choose your overlays carefully to minimize their
3918 effect on your program's performance.
3920 * The executable file you load onto your system must contain each
3921 overlay's instructions, appearing at the overlay's load address,
3922 not its mapped address. However, each overlay's instructions must
3923 be relocated and its symbols defined as if the overlay were at its
3924 mapped address. You can use GNU linker scripts to specify
3925 different load and relocation addresses for pieces of your program;
3926 see *note (ld.info)Overlay Description::.
3928 * The procedure for loading executable files onto your system must be
3929 able to load their contents into the larger address space as well
3930 as the instruction and data spaces.
3932 The overlay system described above is rather simple, and could be
3933 improved in many ways:
3935 * If your system has suitable bank switch registers or memory
3936 management hardware, you could use those facilities to make an
3937 overlay's load area contents simply appear at their mapped address
3938 in instruction space. This would probably be faster than copying
3939 the overlay to its mapped area in the usual way.
3941 * If your overlays are small enough, you could set aside more than
3942 one overlay area, and have more than one overlay mapped at a time.
3944 * You can use overlays to manage data, as well as instructions. In
3945 general, data overlays are even less transparent to your design
3946 than code overlays: whereas code overlays only require care when
3947 you call or return to functions, data overlays require care every
3948 time you access the data. Also, if you change the contents of a
3949 data overlay, you must copy its contents back out to its load
3950 address before you can copy a different data overlay into the same
3954 File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays
3956 14.2 Overlay Commands
3957 =====================
3959 To use GDB's overlay support, each overlay in your program must
3960 correspond to a separate section of the executable file. The section's
3961 virtual memory address and load memory address must be the overlay's
3962 mapped and load addresses. Identifying overlays with sections allows
3963 GDB to determine the appropriate address of a function or variable,
3964 depending on whether the overlay is mapped or not.
3966 GDB's overlay commands all start with the word 'overlay'; you can
3967 abbreviate this as 'ov' or 'ovly'. The commands are:
3970 Disable GDB's overlay support. When overlay support is disabled,
3971 GDB assumes that all functions and variables are always present at
3972 their mapped addresses. By default, GDB's overlay support is
3976 Enable "manual" overlay debugging. In this mode, GDB relies on you
3977 to tell it which overlays are mapped, and which are not, using the
3978 'overlay map-overlay' and 'overlay unmap-overlay' commands
3981 'overlay map-overlay OVERLAY'
3982 'overlay map OVERLAY'
3983 Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of
3984 the object file section containing the overlay. When an overlay is
3985 mapped, GDB assumes it can find the overlay's functions and
3986 variables at their mapped addresses. GDB assumes that any other
3987 overlays whose mapped ranges overlap that of OVERLAY are now
3990 'overlay unmap-overlay OVERLAY'
3991 'overlay unmap OVERLAY'
3992 Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the name
3993 of the object file section containing the overlay. When an overlay
3994 is unmapped, GDB assumes it can find the overlay's functions and
3995 variables at their load addresses.
3998 Enable "automatic" overlay debugging. In this mode, GDB consults a
3999 data structure the overlay manager maintains in the inferior to see
4000 which overlays are mapped. For details, see *note Automatic
4001 Overlay Debugging::.
4003 'overlay load-target'
4005 Re-read the overlay table from the inferior. Normally, GDB
4006 re-reads the table GDB automatically each time the inferior stops,
4007 so this command should only be necessary if you have changed the
4008 overlay mapping yourself using GDB. This command is only useful
4009 when using automatic overlay debugging.
4011 'overlay list-overlays'
4013 Display a list of the overlays currently mapped, along with their
4014 mapped addresses, load addresses, and sizes.
4016 Normally, when GDB prints a code address, it includes the name of the
4017 function the address falls in:
4020 $3 = {int ()} 0x11a0 <main>
4021 When overlay debugging is enabled, GDB recognizes code in unmapped
4022 overlays, and prints the names of unmapped functions with asterisks
4023 around them. For example, if 'foo' is a function in an unmapped
4024 overlay, GDB prints it this way:
4027 No sections are mapped.
4029 $5 = {int (int)} 0x100000 <*foo*>
4030 When 'foo''s overlay is mapped, GDB prints the function's name normally:
4033 Section .ov.foo.text, loaded at 0x100000 - 0x100034,
4034 mapped at 0x1016 - 0x104a
4036 $6 = {int (int)} 0x1016 <foo>
4038 When overlay debugging is enabled, GDB can find the correct address
4039 for functions and variables in an overlay, whether or not the overlay is
4040 mapped. This allows most GDB commands, like 'break' and 'disassemble',
4041 to work normally, even on unmapped code. However, GDB's breakpoint
4042 support has some limitations:
4044 * You can set breakpoints in functions in unmapped overlays, as long
4045 as GDB can write to the overlay at its load address.
4046 * GDB can not set hardware or simulator-based breakpoints in unmapped
4047 overlays. However, if you set a breakpoint at the end of your
4048 overlay manager (and tell GDB which overlays are now mapped, if you
4049 are using manual overlay management), GDB will re-set its
4050 breakpoints properly.
4053 File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays
4055 14.3 Automatic Overlay Debugging
4056 ================================
4058 GDB can automatically track which overlays are mapped and which are not,
4059 given some simple co-operation from the overlay manager in the inferior.
4060 If you enable automatic overlay debugging with the 'overlay auto'
4061 command (*note Overlay Commands::), GDB looks in the inferior's memory
4062 for certain variables describing the current state of the overlays.
4064 Here are the variables your overlay manager must define to support
4065 GDB's automatic overlay debugging:
4068 This variable must be an array of the following structures:
4072 /* The overlay's mapped address. */
4075 /* The size of the overlay, in bytes. */
4078 /* The overlay's load address. */
4081 /* Non-zero if the overlay is currently mapped;
4083 unsigned long mapped;
4087 This variable must be a four-byte signed integer, holding the total
4088 number of elements in '_ovly_table'.
4090 To decide whether a particular overlay is mapped or not, GDB looks
4091 for an entry in '_ovly_table' whose 'vma' and 'lma' members equal the
4092 VMA and LMA of the overlay's section in the executable file. When GDB
4093 finds a matching entry, it consults the entry's 'mapped' member to
4094 determine whether the overlay is currently mapped.
4096 In addition, your overlay manager may define a function called
4097 '_ovly_debug_event'. If this function is defined, GDB will silently set
4098 a breakpoint there. If the overlay manager then calls this function
4099 whenever it has changed the overlay table, this will enable GDB to
4100 accurately keep track of which overlays are in program memory, and
4101 update any breakpoints that may be set in overlays. This will allow
4102 breakpoints to work even if the overlays are kept in ROM or other
4103 non-writable memory while they are not being executed.
4106 File: gdb.info, Node: Overlay Sample Program, Prev: Automatic Overlay Debugging, Up: Overlays
4108 14.4 Overlay Sample Program
4109 ===========================
4111 When linking a program which uses overlays, you must place the overlays
4112 at their load addresses, while relocating them to run at their mapped
4113 addresses. To do this, you must write a linker script (*note
4114 (ld.info)Overlay Description::). Unfortunately, since linker scripts
4115 are specific to a particular host system, target architecture, and
4116 target memory layout, this manual cannot provide portable sample code
4117 demonstrating GDB's overlay support.
4119 However, the GDB source distribution does contain an overlaid
4120 program, with linker scripts for a few systems, as part of its test
4121 suite. The program consists of the following files from
4122 'gdb/testsuite/gdb.base':
4125 The main program file.
4127 A simple overlay manager, used by 'overlays.c'.
4132 Overlay modules, loaded and used by 'overlays.c'.
4135 Linker scripts for linking the test program on the 'd10v-elf' and
4138 You can build the test program using the 'd10v-elf' GCC
4139 cross-compiler like this:
4141 $ d10v-elf-gcc -g -c overlays.c
4142 $ d10v-elf-gcc -g -c ovlymgr.c
4143 $ d10v-elf-gcc -g -c foo.c
4144 $ d10v-elf-gcc -g -c bar.c
4145 $ d10v-elf-gcc -g -c baz.c
4146 $ d10v-elf-gcc -g -c grbx.c
4147 $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
4148 baz.o grbx.o -Wl,-Td10v.ld -o overlays
4150 The build process is identical for any other architecture, except
4151 that you must substitute the appropriate compiler and linker script for
4152 the target system for 'd10v-elf-gcc' and 'd10v.ld'.
4155 File: gdb.info, Node: Languages, Next: Symbols, Prev: Overlays, Up: Top
4157 15 Using GDB with Different Languages
4158 *************************************
4160 Although programming languages generally have common aspects, they are
4161 rarely expressed in the same manner. For instance, in ANSI C,
4162 dereferencing a pointer 'p' is accomplished by '*p', but in Modula-2, it
4163 is accomplished by 'p^'. Values can also be represented (and displayed)
4164 differently. Hex numbers in C appear as '0x1ae', while in Modula-2 they
4167 Language-specific information is built into GDB for some languages,
4168 allowing you to express operations like the above in your program's
4169 native language, and allowing GDB to output values in a manner
4170 consistent with the syntax of your program's native language. The
4171 language you use to build expressions is called the "working language".
4175 * Setting:: Switching between source languages
4176 * Show:: Displaying the language
4177 * Checks:: Type and range checks
4178 * Supported Languages:: Supported languages
4179 * Unsupported Languages:: Unsupported languages
4182 File: gdb.info, Node: Setting, Next: Show, Up: Languages
4184 15.1 Switching Between Source Languages
4185 =======================================
4187 There are two ways to control the working language--either have GDB set
4188 it automatically, or select it manually yourself. You can use the 'set
4189 language' command for either purpose. On startup, GDB defaults to
4190 setting the language automatically. The working language is used to
4191 determine how expressions you type are interpreted, how values are
4194 In addition to the working language, every source file that GDB knows
4195 about has its own working language. For some object file formats, the
4196 compiler might indicate which language a particular source file is in.
4197 However, most of the time GDB infers the language from the name of the
4198 file. The language of a source file controls whether C++ names are
4199 demangled--this way 'backtrace' can show each frame appropriately for
4200 its own language. There is no way to set the language of a source file
4201 from within GDB, but you can set the language associated with a filename
4202 extension. *Note Displaying the Language: Show.
4204 This is most commonly a problem when you use a program, such as
4205 'cfront' or 'f2c', that generates C but is written in another language.
4206 In that case, make the program use '#line' directives in its C output;
4207 that way GDB will know the correct language of the source code of the
4208 original program, and will display that source code, not the generated C
4213 * Filenames:: Filename extensions and languages.
4214 * Manually:: Setting the working language manually
4215 * Automatically:: Having GDB infer the source language
4218 File: gdb.info, Node: Filenames, Next: Manually, Up: Setting
4220 15.1.1 List of Filename Extensions and Languages
4221 ------------------------------------------------
4223 If a source file name ends in one of the following extensions, then GDB
4224 infers that its language is the one indicated.
4247 Objective-C source file
4254 Modula-2 source file
4258 Assembler source file. This actually behaves almost like C, but
4259 GDB does not skip over function prologues when stepping.
4261 In addition, you may set the language associated with a filename
4262 extension. *Note Displaying the Language: Show.
4265 File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting
4267 15.1.2 Setting the Working Language
4268 -----------------------------------
4270 If you allow GDB to set the language automatically, expressions are
4271 interpreted the same way in your debugging session and your program.
4273 If you wish, you may set the language manually. To do this, issue
4274 the command 'set language LANG', where LANG is the name of a language,
4275 such as 'c' or 'modula-2'. For a list of the supported languages, type
4278 Setting the language manually prevents GDB from updating the working
4279 language automatically. This can lead to confusion if you try to debug
4280 a program when the working language is not the same as the source
4281 language, when an expression is acceptable to both languages--but means
4282 different things. For instance, if the current source file were written
4283 in C, and GDB was parsing Modula-2, a command such as:
4287 might not have the effect you intended. In C, this means to add 'b' and
4288 'c' and place the result in 'a'. The result printed would be the value
4289 of 'a'. In Modula-2, this means to compare 'a' to the result of 'b+c',
4290 yielding a 'BOOLEAN' value.
4293 File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting
4295 15.1.3 Having GDB Infer the Source Language
4296 -------------------------------------------
4298 To have GDB set the working language automatically, use 'set language
4299 local' or 'set language auto'. GDB then infers the working language.
4300 That is, when your program stops in a frame (usually by encountering a
4301 breakpoint), GDB sets the working language to the language recorded for
4302 the function in that frame. If the language for a frame is unknown
4303 (that is, if the function or block corresponding to the frame was
4304 defined in a source file that does not have a recognized extension), the
4305 current working language is not changed, and GDB issues a warning.
4307 This may not seem necessary for most programs, which are written
4308 entirely in one source language. However, program modules and libraries
4309 written in one source language can be used by a main program written in
4310 a different source language. Using 'set language auto' in this case
4311 frees you from having to set the working language manually.
4314 File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages
4316 15.2 Displaying the Language
4317 ============================
4319 The following commands help you find out which language is the working
4320 language, and also what language source files were written in.
4323 Display the current working language. This is the language you can
4324 use with commands such as 'print' to build and compute expressions
4325 that may involve variables in your program.
4328 Display the source language for this frame. This language becomes
4329 the working language if you use an identifier from this frame.
4330 *Note Information about a Frame: Frame Info, to identify the other
4331 information listed here.
4334 Display the source language of this source file. *Note Examining
4335 the Symbol Table: Symbols, to identify the other information listed
4338 In unusual circumstances, you may have source files with extensions
4339 not in the standard list. You can then set the extension associated
4340 with a language explicitly:
4342 'set extension-language EXT LANGUAGE'
4343 Tell GDB that source files with extension EXT are to be assumed as
4344 written in the source language LANGUAGE.
4347 List all the filename extensions and the associated languages.
4350 File: gdb.info, Node: Checks, Next: Supported Languages, Prev: Show, Up: Languages
4352 15.3 Type and Range Checking
4353 ============================
4355 Some languages are designed to guard you against making seemingly common
4356 errors through a series of compile- and run-time checks. These include
4357 checking the type of arguments to functions and operators and making
4358 sure mathematical overflows are caught at run time. Checks such as
4359 these help to ensure a program's correctness once it has been compiled
4360 by eliminating type mismatches and providing active checks for range
4361 errors when your program is running.
4363 By default GDB checks for these errors according to the rules of the
4364 current source language. Although GDB does not check the statements in
4365 your program, it can check expressions entered directly into GDB for
4366 evaluation via the 'print' command, for example.
4370 * Type Checking:: An overview of type checking
4371 * Range Checking:: An overview of range checking
4374 File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks
4376 15.3.1 An Overview of Type Checking
4377 -----------------------------------
4379 Some languages, such as C and C++, are strongly typed, meaning that the
4380 arguments to operators and functions have to be of the correct type,
4381 otherwise an error occurs. These checks prevent type mismatch errors
4382 from ever causing any run-time problems. For example,
4384 int klass::my_method(char *b) { return b ? 1 : 2; }
4386 (gdb) print obj.my_method (0)
4389 (gdb) print obj.my_method (0x1234)
4390 Cannot resolve method klass::my_method to any overloaded instance
4392 The second example fails because in C++ the integer constant '0x1234'
4393 is not type-compatible with the pointer parameter type.
4395 For the expressions you use in GDB commands, you can tell GDB to not
4396 enforce strict type checking or to treat any mismatches as errors and
4397 abandon the expression; When type checking is disabled, GDB successfully
4398 evaluates expressions like the second example above.
4400 Even if type checking is off, there may be other reasons related to
4401 type that prevent GDB from evaluating an expression. For instance, GDB
4402 does not know how to add an 'int' and a 'struct foo'. These particular
4403 type errors have nothing to do with the language in use and usually
4404 arise from expressions which make little sense to evaluate anyway.
4406 GDB provides some additional commands for controlling type checking:
4409 'set check type off'
4410 Set strict type checking on or off. If any type mismatches occur
4411 in evaluating an expression while type checking is on, GDB prints a
4412 message and aborts evaluation of the expression.
4415 Show the current setting of type checking and whether GDB is
4416 enforcing strict type checking rules.
4419 File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks
4421 15.3.2 An Overview of Range Checking
4422 ------------------------------------
4424 In some languages (such as Modula-2), it is an error to exceed the
4425 bounds of a type; this is enforced with run-time checks. Such range
4426 checking is meant to ensure program correctness by making sure
4427 computations do not overflow, or indices on an array element access do
4428 not exceed the bounds of the array.
4430 For expressions you use in GDB commands, you can tell GDB to treat
4431 range errors in one of three ways: ignore them, always treat them as
4432 errors and abandon the expression, or issue warnings but evaluate the
4435 A range error can result from numerical overflow, from exceeding an
4436 array index bound, or when you type a constant that is not a member of
4437 any type. Some languages, however, do not treat overflows as an error.
4438 In many implementations of C, mathematical overflow causes the result to
4439 "wrap around" to lower values--for example, if M is the largest integer
4440 value, and S is the smallest, then
4444 This, too, is specific to individual languages, and in some cases
4445 specific to individual compilers or machines. *Note Supported
4446 Languages: Supported Languages, for further details on specific
4449 GDB provides some additional commands for controlling the range
4452 'set check range auto'
4453 Set range checking on or off based on the current working language.
4454 *Note Supported Languages: Supported Languages, for the default
4455 settings for each language.
4457 'set check range on'
4458 'set check range off'
4459 Set range checking on or off, overriding the default setting for
4460 the current working language. A warning is issued if the setting
4461 does not match the language default. If a range error occurs and
4462 range checking is on, then a message is printed and evaluation of
4463 the expression is aborted.
4465 'set check range warn'
4466 Output messages when the GDB range checker detects a range error,
4467 but attempt to evaluate the expression anyway. Evaluating the
4468 expression may still be impossible for other reasons, such as
4469 accessing memory that the process does not own (a typical example
4470 from many Unix systems).
4473 Show the current setting of the range checker, and whether or not
4474 it is being set automatically by GDB.
4477 File: gdb.info, Node: Supported Languages, Next: Unsupported Languages, Prev: Checks, Up: Languages
4479 15.4 Supported Languages
4480 ========================
4482 GDB supports C, C++, D, Go, Objective-C, Fortran, Java, OpenCL C,
4483 Pascal, assembly, Modula-2, and Ada. Some GDB features may be used in
4484 expressions regardless of the language you use: the GDB '@' and '::'
4485 operators, and the '{type}addr' construct (*note Expressions:
4486 Expressions.) can be used with the constructs of any supported language.
4488 The following sections detail to what degree each source language is
4489 supported by GDB. These sections are not meant to be language tutorials
4490 or references, but serve only as a reference guide to what the GDB
4491 expression parser accepts, and what input and output formats should look
4492 like for different languages. There are many good books written on each
4493 of these languages; please look to these for a language reference or
4501 * Objective-C:: Objective-C
4502 * OpenCL C:: OpenCL C
4505 * Modula-2:: Modula-2
4509 File: gdb.info, Node: C, Next: D, Up: Supported Languages
4514 Since C and C++ are so closely related, many features of GDB apply to
4515 both languages. Whenever this is the case, we discuss those languages
4518 The C++ debugging facilities are jointly implemented by the C++
4519 compiler and GDB. Therefore, to debug your C++ code effectively, you
4520 must compile your C++ programs with a supported C++ compiler, such as
4521 GNU 'g++', or the HP ANSI C++ compiler ('aCC').
4525 * C Operators:: C and C++ operators
4526 * C Constants:: C and C++ constants
4527 * C Plus Plus Expressions:: C++ expressions
4528 * C Defaults:: Default settings for C and C++
4529 * C Checks:: C and C++ type and range checks
4530 * Debugging C:: GDB and C
4531 * Debugging C Plus Plus:: GDB features for C++
4532 * Decimal Floating Point:: Numbers in Decimal Floating Point format
4535 File: gdb.info, Node: C Operators, Next: C Constants, Up: C
4537 15.4.1.1 C and C++ Operators
4538 ............................
4540 Operators must be defined on values of specific types. For instance,
4541 '+' is defined on numbers, but not on structures. Operators are often
4542 defined on groups of types.
4544 For the purposes of C and C++, the following definitions hold:
4546 * _Integral types_ include 'int' with any of its storage-class
4547 specifiers; 'char'; 'enum'; and, for C++, 'bool'.
4549 * _Floating-point types_ include 'float', 'double', and 'long double'
4550 (if supported by the target platform).
4552 * _Pointer types_ include all types defined as '(TYPE *)'.
4554 * _Scalar types_ include all of the above.
4556 The following operators are supported. They are listed here in order of
4557 increasing precedence:
4560 The comma or sequencing operator. Expressions in a comma-separated
4561 list are evaluated from left to right, with the result of the
4562 entire expression being the last expression evaluated.
4565 Assignment. The value of an assignment expression is the value
4566 assigned. Defined on scalar types.
4569 Used in an expression of the form 'A OP= B', and translated to
4570 'A = A OP B'. 'OP=' and '=' have the same precedence. OP is any
4571 one of the operators '|', '^', '&', '<<', '>>', '+', '-', '*', '/',
4575 The ternary operator. 'A ? B : C' can be thought of as: if A then
4576 B else C. A should be of an integral type.
4579 Logical OR. Defined on integral types.
4582 Logical AND. Defined on integral types.
4585 Bitwise OR. Defined on integral types.
4588 Bitwise exclusive-OR. Defined on integral types.
4591 Bitwise AND. Defined on integral types.
4594 Equality and inequality. Defined on scalar types. The value of
4595 these expressions is 0 for false and non-zero for true.
4598 Less than, greater than, less than or equal, greater than or equal.
4599 Defined on scalar types. The value of these expressions is 0 for
4600 false and non-zero for true.
4603 left shift, and right shift. Defined on integral types.
4606 The GDB "artificial array" operator (*note Expressions:
4610 Addition and subtraction. Defined on integral types,
4611 floating-point types and pointer types.
4614 Multiplication, division, and modulus. Multiplication and division
4615 are defined on integral and floating-point types. Modulus is
4616 defined on integral types.
4619 Increment and decrement. When appearing before a variable, the
4620 operation is performed before the variable is used in an
4621 expression; when appearing after it, the variable's value is used
4622 before the operation takes place.
4625 Pointer dereferencing. Defined on pointer types. Same precedence
4629 Address operator. Defined on variables. Same precedence as '++'.
4631 For debugging C++, GDB implements a use of '&' beyond what is
4632 allowed in the C++ language itself: you can use '&(&REF)' to
4633 examine the address where a C++ reference variable (declared with
4637 Negative. Defined on integral and floating-point types. Same
4641 Logical negation. Defined on integral types. Same precedence as
4645 Bitwise complement operator. Defined on integral types. Same
4649 Structure member, and pointer-to-structure member. For
4650 convenience, GDB regards the two as equivalent, choosing whether to
4651 dereference a pointer based on the stored type information.
4652 Defined on 'struct' and 'union' data.
4655 Dereferences of pointers to members.
4658 Array indexing. 'A[I]' is defined as '*(A+I)'. Same precedence as
4662 Function parameter list. Same precedence as '->'.
4665 C++ scope resolution operator. Defined on 'struct', 'union', and
4669 Doubled colons also represent the GDB scope operator (*note
4670 Expressions: Expressions.). Same precedence as '::', above.
4672 If an operator is redefined in the user code, GDB usually attempts to
4673 invoke the redefined version instead of using the operator's predefined
4677 File: gdb.info, Node: C Constants, Next: C Plus Plus Expressions, Prev: C Operators, Up: C
4679 15.4.1.2 C and C++ Constants
4680 ............................
4682 GDB allows you to express the constants of C and C++ in the following
4685 * Integer constants are a sequence of digits. Octal constants are
4686 specified by a leading '0' (i.e. zero), and hexadecimal constants
4687 by a leading '0x' or '0X'. Constants may also end with a letter
4688 'l', specifying that the constant should be treated as a 'long'
4691 * Floating point constants are a sequence of digits, followed by a
4692 decimal point, followed by a sequence of digits, and optionally
4693 followed by an exponent. An exponent is of the form:
4694 'e[[+]|-]NNN', where NNN is another sequence of digits. The '+' is
4695 optional for positive exponents. A floating-point constant may
4696 also end with a letter 'f' or 'F', specifying that the constant
4697 should be treated as being of the 'float' (as opposed to the
4698 default 'double') type; or with a letter 'l' or 'L', which
4699 specifies a 'long double' constant.
4701 * Enumerated constants consist of enumerated identifiers, or their
4702 integral equivalents.
4704 * Character constants are a single character surrounded by single
4705 quotes ('''), or a number--the ordinal value of the corresponding
4706 character (usually its ASCII value). Within quotes, the single
4707 character may be represented by a letter or by "escape sequences",
4708 which are of the form '\NNN', where NNN is the octal representation
4709 of the character's ordinal value; or of the form '\X', where 'X' is
4710 a predefined special character--for example, '\n' for newline.
4712 Wide character constants can be written by prefixing a character
4713 constant with 'L', as in C. For example, 'L'x'' is the wide form of
4714 'x'. The target wide character set is used when computing the
4715 value of this constant (*note Character Sets::).
4717 * String constants are a sequence of character constants surrounded
4718 by double quotes ('"'). Any valid character constant (as described
4719 above) may appear. Double quotes within the string must be
4720 preceded by a backslash, so for instance '"a\"b'c"' is a string of
4723 Wide string constants can be written by prefixing a string constant
4724 with 'L', as in C. The target wide character set is used when
4725 computing the value of this constant (*note Character Sets::).
4727 * Pointer constants are an integral value. You can also write
4728 pointers to constants using the C operator '&'.
4730 * Array constants are comma-separated lists surrounded by braces '{'
4731 and '}'; for example, '{1,2,3}' is a three-element array of
4732 integers, '{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and
4733 '{&"hi", &"there", &"fred"}' is a three-element array of pointers.
4736 File: gdb.info, Node: C Plus Plus Expressions, Next: C Defaults, Prev: C Constants, Up: C
4738 15.4.1.3 C++ Expressions
4739 ........................
4741 GDB expression handling can interpret most C++ expressions.
4743 _Warning:_ GDB can only debug C++ code if you use the proper
4744 compiler and the proper debug format. Currently, GDB works best
4745 when debugging C++ code that is compiled with the most recent
4746 version of GCC possible. The DWARF debugging format is preferred;
4747 GCC defaults to this on most popular platforms. Other compilers
4748 and/or debug formats are likely to work badly or not at all when
4749 using GDB to debug C++ code. *Note Compilation::.
4751 1. Member function calls are allowed; you can use expressions like
4753 count = aml->GetOriginal(x, y)
4755 2. While a member function is active (in the selected stack frame),
4756 your expressions have the same namespace available as the member
4757 function; that is, GDB allows implicit references to the class
4758 instance pointer 'this' following the same rules as C++. 'using'
4759 declarations in the current scope are also respected by GDB.
4761 3. You can call overloaded functions; GDB resolves the function call
4762 to the right definition, with some restrictions. GDB does not
4763 perform overload resolution involving user-defined type
4764 conversions, calls to constructors, or instantiations of templates
4765 that do not exist in the program. It also cannot handle ellipsis
4766 argument lists or default arguments.
4768 It does perform integral conversions and promotions, floating-point
4769 promotions, arithmetic conversions, pointer conversions,
4770 conversions of class objects to base classes, and standard
4771 conversions such as those of functions or arrays to pointers; it
4772 requires an exact match on the number of function arguments.
4774 Overload resolution is always performed, unless you have specified
4775 'set overload-resolution off'. *Note GDB Features for C++:
4776 Debugging C Plus Plus.
4778 You must specify 'set overload-resolution off' in order to use an
4779 explicit function signature to call an overloaded function, as in
4780 p 'foo(char,int)'('x', 13)
4782 The GDB command-completion facility can simplify this; see *note
4783 Command Completion: Completion.
4785 4. GDB understands variables declared as C++ references; you can use
4786 them in expressions just as you do in C++ source--they are
4787 automatically dereferenced.
4789 In the parameter list shown when GDB displays a frame, the values
4790 of reference variables are not displayed (unlike other variables);
4791 this avoids clutter, since references are often used for large
4792 structures. The _address_ of a reference variable is always shown,
4793 unless you have specified 'set print address off'.
4795 5. GDB supports the C++ name resolution operator '::'--your
4796 expressions can use it just as expressions in your program do.
4797 Since one scope may be defined in another, you can use '::'
4798 repeatedly if necessary, for example in an expression like
4799 'SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by
4800 reference to source files, in both C and C++ debugging (*note
4801 Program Variables: Variables.).
4803 6. GDB performs argument-dependent lookup, following the C++
4807 File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C Plus Plus Expressions, Up: C
4809 15.4.1.4 C and C++ Defaults
4810 ...........................
4812 If you allow GDB to set range checking automatically, it defaults to
4813 'off' whenever the working language changes to C or C++. This happens
4814 regardless of whether you or GDB selects the working language.
4816 If you allow GDB to set the language automatically, it recognizes
4817 source files whose names end with '.c', '.C', or '.cc', etc, and when
4818 GDB enters code compiled from one of these files, it sets the working
4819 language to C or C++. *Note Having GDB Infer the Source Language:
4820 Automatically, for further details.
4823 File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C
4825 15.4.1.5 C and C++ Type and Range Checks
4826 ........................................
4828 By default, when GDB parses C or C++ expressions, strict type checking
4829 is used. However, if you turn type checking off, GDB will allow certain
4830 non-standard conversions, such as promoting integer constants to
4833 Range checking, if turned on, is done on mathematical operations.
4834 Array indices are not checked, since they are often used to index a
4835 pointer that is not itself an array.
4838 File: gdb.info, Node: Debugging C, Next: Debugging C Plus Plus, Prev: C Checks, Up: C
4843 The 'set print union' and 'show print union' commands apply to the
4844 'union' type. When set to 'on', any 'union' that is inside a 'struct'
4845 or 'class' is also printed. Otherwise, it appears as '{...}'.
4847 The '@' operator aids in the debugging of dynamic arrays, formed with
4848 pointers and a memory allocation function. *Note Expressions:
4852 File: gdb.info, Node: Debugging C Plus Plus, Next: Decimal Floating Point, Prev: Debugging C, Up: C
4854 15.4.1.7 GDB Features for C++
4855 .............................
4857 Some GDB commands are particularly useful with C++, and some are
4858 designed specifically for use with C++. Here is a summary:
4861 When you want a breakpoint in a function whose name is overloaded,
4862 GDB has the capability to display a menu of possible breakpoint
4863 locations to help you specify which function definition you want.
4864 *Note Ambiguous Expressions: Ambiguous Expressions.
4867 Setting breakpoints using regular expressions is helpful for
4868 setting breakpoints on overloaded functions that are not members of
4869 any special classes. *Note Setting Breakpoints: Set Breaks.
4874 Debug C++ exception handling using these commands. *Note Setting
4875 Catchpoints: Set Catchpoints.
4878 Print inheritance relationships as well as other information for
4879 type TYPENAME. *Note Examining the Symbol Table: Symbols.
4881 'info vtbl EXPRESSION.'
4882 The 'info vtbl' command can be used to display the virtual method
4883 tables of the object computed by EXPRESSION. This shows one entry
4884 per virtual table; there may be multiple virtual tables when
4885 multiple inheritance is in use.
4887 'set print demangle'
4888 'show print demangle'
4889 'set print asm-demangle'
4890 'show print asm-demangle'
4891 Control whether C++ symbols display in their source form, both when
4892 displaying code as C++ source and when displaying disassemblies.
4893 *Note Print Settings: Print Settings.
4897 Choose whether to print derived (actual) or declared types of
4898 objects. *Note Print Settings: Print Settings.
4902 Control the format for printing virtual function tables. *Note
4903 Print Settings: Print Settings. (The 'vtbl' commands do not work
4904 on programs compiled with the HP ANSI C++ compiler ('aCC').)
4906 'set overload-resolution on'
4907 Enable overload resolution for C++ expression evaluation. The
4908 default is on. For overloaded functions, GDB evaluates the
4909 arguments and searches for a function whose signature matches the
4910 argument types, using the standard C++ conversion rules (see *note
4911 C++ Expressions: C Plus Plus Expressions, for details). If it
4912 cannot find a match, it emits a message.
4914 'set overload-resolution off'
4915 Disable overload resolution for C++ expression evaluation. For
4916 overloaded functions that are not class member functions, GDB
4917 chooses the first function of the specified name that it finds in
4918 the symbol table, whether or not its arguments are of the correct
4919 type. For overloaded functions that are class member functions,
4920 GDB searches for a function whose signature _exactly_ matches the
4923 'show overload-resolution'
4924 Show the current setting of overload resolution.
4926 'Overloaded symbol names'
4927 You can specify a particular definition of an overloaded symbol,
4928 using the same notation that is used to declare such symbols in
4929 C++: type 'SYMBOL(TYPES)' rather than just SYMBOL. You can also
4930 use the GDB command-line word completion facilities to list the
4931 available choices, or to finish the type list for you. *Note
4932 Command Completion: Completion, for details on how to do this.
4935 File: gdb.info, Node: Decimal Floating Point, Prev: Debugging C Plus Plus, Up: C
4937 15.4.1.8 Decimal Floating Point format
4938 ......................................
4940 GDB can examine, set and perform computations with numbers in decimal
4941 floating point format, which in the C language correspond to the
4942 '_Decimal32', '_Decimal64' and '_Decimal128' types as specified by the
4943 extension to support decimal floating-point arithmetic.
4945 There are two encodings in use, depending on the architecture: BID
4946 (Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed
4947 Decimal) for PowerPC and S/390. GDB will use the appropriate encoding
4948 for the configured target.
4950 Because of a limitation in 'libdecnumber', the library used by GDB to
4951 manipulate decimal floating point numbers, it is not possible to convert
4952 (using a cast, for example) integers wider than 32-bit to decimal float.
4954 In addition, in order to imitate GDB's behaviour with binary floating
4955 point computations, error checking in decimal float operations ignores
4956 underflow, overflow and divide by zero exceptions.
4958 In the PowerPC architecture, GDB provides a set of pseudo-registers
4959 to inspect '_Decimal128' values stored in floating point registers. See
4960 *note PowerPC: PowerPC. for more details.
4963 File: gdb.info, Node: D, Next: Go, Prev: C, Up: Supported Languages
4968 GDB can be used to debug programs written in D and compiled with GDC,
4969 LDC or DMD compilers. Currently GDB supports only one D specific
4970 feature -- dynamic arrays.
4973 File: gdb.info, Node: Go, Next: Objective-C, Prev: D, Up: Supported Languages
4978 GDB can be used to debug programs written in Go and compiled with
4979 'gccgo' or '6g' compilers.
4981 Here is a summary of the Go-specific features and restrictions:
4983 'The current Go package'
4984 The name of the current package does not need to be specified when
4985 specifying global variables and functions.
4987 For example, given the program:
4990 var myglob = "Shall we?"
4995 When stopped inside 'main' either of these work:
5001 The 'string' type is recognized by GDB and is printed as a string.
5003 'Builtin Go functions'
5004 The GDB expression parser recognizes the 'unsafe.Sizeof' function
5005 and handles it internally.
5007 'Restrictions on Go expressions'
5008 All Go operators are supported except '&^'. The Go '_' "blank
5009 identifier" is not supported. Automatic dereferencing of pointers
5013 File: gdb.info, Node: Objective-C, Next: OpenCL C, Prev: Go, Up: Supported Languages
5018 This section provides information about some commands and command
5019 options that are useful for debugging Objective-C code. See also *note
5020 info classes: Symbols, and *note info selectors: Symbols, for a few more
5021 commands specific to Objective-C support.
5025 * Method Names in Commands::
5026 * The Print Command with Objective-C::
5029 File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Up: Objective-C
5031 15.4.4.1 Method Names in Commands
5032 .................................
5034 The following commands have been extended to accept Objective-C method
5035 names as line specifications:
5043 A fully qualified Objective-C method name is specified as
5047 where the minus sign is used to indicate an instance method and a
5048 plus sign (not shown) is used to indicate a class method. The class
5049 name CLASS and method name METHODNAME are enclosed in brackets, similar
5050 to the way messages are specified in Objective-C source code. For
5051 example, to set a breakpoint at the 'create' instance method of class
5052 'Fruit' in the program currently being debugged, enter:
5054 break -[Fruit create]
5056 To list ten program lines around the 'initialize' class method,
5059 list +[NSText initialize]
5061 In the current version of GDB, the plus or minus sign is required.
5062 In future versions of GDB, the plus or minus sign will be optional, but
5063 you can use it to narrow the search. It is also possible to specify
5068 You must specify the complete method name, including any colons. If
5069 your program's source files contain more than one 'create' method,
5070 you'll be presented with a numbered list of classes that implement that
5071 method. Indicate your choice by number, or type '0' to exit if none
5074 As another example, to clear a breakpoint established at the
5075 'makeKeyAndOrderFront:' method of the 'NSWindow' class, enter:
5077 clear -[NSWindow makeKeyAndOrderFront:]
5080 File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C
5082 15.4.4.2 The Print Command With Objective-C
5083 ...........................................
5085 The print command has also been extended to accept methods. For
5088 print -[OBJECT hash]
5090 will tell GDB to send the 'hash' message to OBJECT and print the result.
5091 Also, an additional command has been added, 'print-object' or 'po' for
5092 short, which is meant to print the description of an object. However,
5093 this command may only work with certain Objective-C libraries that have
5094 a particular hook function, '_NSPrintForDebugger', defined.
5097 File: gdb.info, Node: OpenCL C, Next: Fortran, Prev: Objective-C, Up: Supported Languages
5102 This section provides information about GDBs OpenCL C support.
5106 * OpenCL C Datatypes::
5107 * OpenCL C Expressions::
5108 * OpenCL C Operators::
5111 File: gdb.info, Node: OpenCL C Datatypes, Next: OpenCL C Expressions, Up: OpenCL C
5113 15.4.5.1 OpenCL C Datatypes
5114 ...........................
5116 GDB supports the builtin scalar and vector datatypes specified by OpenCL
5117 1.1. In addition the half- and double-precision floating point data
5118 types of the 'cl_khr_fp16' and 'cl_khr_fp64' OpenCL extensions are also
5122 File: gdb.info, Node: OpenCL C Expressions, Next: OpenCL C Operators, Prev: OpenCL C Datatypes, Up: OpenCL C
5124 15.4.5.2 OpenCL C Expressions
5125 .............................
5127 GDB supports accesses to vector components including the access as
5128 lvalue where possible. Since OpenCL C is based on C99 most C
5129 expressions supported by GDB can be used as well.
5132 File: gdb.info, Node: OpenCL C Operators, Prev: OpenCL C Expressions, Up: OpenCL C
5134 15.4.5.3 OpenCL C Operators
5135 ...........................
5137 GDB supports the operators specified by OpenCL 1.1 for scalar and vector
5141 File: gdb.info, Node: Fortran, Next: Pascal, Prev: OpenCL C, Up: Supported Languages
5146 GDB can be used to debug programs written in Fortran, but it currently
5147 supports only the features of Fortran 77 language.
5149 Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers among
5150 them) append an underscore to the names of variables and functions.
5151 When you debug programs compiled by those compilers, you will need to
5152 refer to variables and functions with a trailing underscore.
5156 * Fortran Operators:: Fortran operators and expressions
5157 * Fortran Defaults:: Default settings for Fortran
5158 * Special Fortran Commands:: Special GDB commands for Fortran
5161 File: gdb.info, Node: Fortran Operators, Next: Fortran Defaults, Up: Fortran
5163 15.4.6.1 Fortran Operators and Expressions
5164 ..........................................
5166 Operators must be defined on values of specific types. For instance,
5167 '+' is defined on numbers, but not on characters or other non-
5168 arithmetic types. Operators are often defined on groups of types.
5171 The exponentiation operator. It raises the first operand to the
5172 power of the second one.
5175 The range operator. Normally used in the form of array(low:high)
5176 to represent a section of array.
5179 The access component operator. Normally used to access elements in
5180 derived types. Also suitable for unions. As unions aren't part of
5181 regular Fortran, this can only happen when accessing a register
5182 that uses a gdbarch-defined union type.
5185 File: gdb.info, Node: Fortran Defaults, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran
5187 15.4.6.2 Fortran Defaults
5188 .........................
5190 Fortran symbols are usually case-insensitive, so GDB by default uses
5191 case-insensitive matches for Fortran symbols. You can change that with
5192 the 'set case-insensitive' command, see *note Symbols::, for the
5196 File: gdb.info, Node: Special Fortran Commands, Prev: Fortran Defaults, Up: Fortran
5198 15.4.6.3 Special Fortran Commands
5199 .................................
5201 GDB has some commands to support Fortran-specific features, such as
5202 displaying common blocks.
5204 'info common [COMMON-NAME]'
5205 This command prints the values contained in the Fortran 'COMMON'
5206 block whose name is COMMON-NAME. With no argument, the names of
5207 all 'COMMON' blocks visible at the current program location are
5211 File: gdb.info, Node: Pascal, Next: Modula-2, Prev: Fortran, Up: Supported Languages
5216 Debugging Pascal programs which use sets, subranges, file variables, or
5217 nested functions does not currently work. GDB does not support entering
5218 expressions, printing values, or similar features using Pascal syntax.
5220 The Pascal-specific command 'set print pascal_static-members'
5221 controls whether static members of Pascal objects are displayed. *Note
5222 pascal_static-members: Print Settings.
5225 File: gdb.info, Node: Modula-2, Next: Ada, Prev: Pascal, Up: Supported Languages
5230 The extensions made to GDB to support Modula-2 only support output from
5231 the GNU Modula-2 compiler (which is currently being developed). Other
5232 Modula-2 compilers are not currently supported, and attempting to debug
5233 executables produced by them is most likely to give an error as GDB
5234 reads in the executable's symbol table.
5238 * M2 Operators:: Built-in operators
5239 * Built-In Func/Proc:: Built-in functions and procedures
5240 * M2 Constants:: Modula-2 constants
5241 * M2 Types:: Modula-2 types
5242 * M2 Defaults:: Default settings for Modula-2
5243 * Deviations:: Deviations from standard Modula-2
5244 * M2 Checks:: Modula-2 type and range checks
5245 * M2 Scope:: The scope operators '::' and '.'
5246 * GDB/M2:: GDB and Modula-2
5249 File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2
5254 Operators must be defined on values of specific types. For instance,
5255 '+' is defined on numbers, but not on structures. Operators are often
5256 defined on groups of types. For the purposes of Modula-2, the following
5259 * _Integral types_ consist of 'INTEGER', 'CARDINAL', and their
5262 * _Character types_ consist of 'CHAR' and its subranges.
5264 * _Floating-point types_ consist of 'REAL'.
5266 * _Pointer types_ consist of anything declared as 'POINTER TO TYPE'.
5268 * _Scalar types_ consist of all of the above.
5270 * _Set types_ consist of 'SET' and 'BITSET' types.
5272 * _Boolean types_ consist of 'BOOLEAN'.
5274 The following operators are supported, and appear in order of increasing
5278 Function argument or array index separator.
5281 Assignment. The value of VAR ':=' VALUE is VALUE.
5284 Less than, greater than on integral, floating-point, or enumerated
5288 Less than or equal to, greater than or equal to on integral,
5289 floating-point and enumerated types, or set inclusion on set types.
5290 Same precedence as '<'.
5293 Equality and two ways of expressing inequality, valid on scalar
5294 types. Same precedence as '<'. In GDB scripts, only '<>' is
5295 available for inequality, since '#' conflicts with the script
5299 Set membership. Defined on set types and the types of their
5300 members. Same precedence as '<'.
5303 Boolean disjunction. Defined on boolean types.
5306 Boolean conjunction. Defined on boolean types.
5309 The GDB "artificial array" operator (*note Expressions:
5313 Addition and subtraction on integral and floating-point types, or
5314 union and difference on set types.
5317 Multiplication on integral and floating-point types, or set
5318 intersection on set types.
5321 Division on floating-point types, or symmetric set difference on
5322 set types. Same precedence as '*'.
5325 Integer division and remainder. Defined on integral types. Same
5329 Negative. Defined on 'INTEGER' and 'REAL' data.
5332 Pointer dereferencing. Defined on pointer types.
5335 Boolean negation. Defined on boolean types. Same precedence as
5339 'RECORD' field selector. Defined on 'RECORD' data. Same
5343 Array indexing. Defined on 'ARRAY' data. Same precedence as '^'.
5346 Procedure argument list. Defined on 'PROCEDURE' objects. Same
5350 GDB and Modula-2 scope operators.
5352 _Warning:_ Set expressions and their operations are not yet
5353 supported, so GDB treats the use of the operator 'IN', or the use
5354 of operators '+', '-', '*', '/', '=', , '<>', '#', '<=', and '>='
5355 on sets as an error.
5358 File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2
5360 15.4.8.2 Built-in Functions and Procedures
5361 ..........................................
5363 Modula-2 also makes available several built-in procedures and functions.
5364 In describing these, the following metavariables are used:
5367 represents an 'ARRAY' variable.
5370 represents a 'CHAR' constant or variable.
5373 represents a variable or constant of integral type.
5376 represents an identifier that belongs to a set. Generally used in
5377 the same function with the metavariable S. The type of S should be
5378 'SET OF MTYPE' (where MTYPE is the type of M).
5381 represents a variable or constant of integral or floating-point
5385 represents a variable or constant of floating-point type.
5391 represents a variable.
5394 represents a variable or constant of one of many types. See the
5395 explanation of the function for details.
5397 All Modula-2 built-in procedures also return a result, described
5401 Returns the absolute value of N.
5404 If C is a lower case letter, it returns its upper case equivalent,
5405 otherwise it returns its argument.
5408 Returns the character whose ordinal value is I.
5411 Decrements the value in the variable V by one. Returns the new
5415 Decrements the value in the variable V by I. Returns the new
5419 Removes the element M from the set S. Returns the new set.
5422 Returns the floating point equivalent of the integer I.
5425 Returns the index of the last member of A.
5428 Increments the value in the variable V by one. Returns the new
5432 Increments the value in the variable V by I. Returns the new
5436 Adds the element M to the set S if it is not already there.
5437 Returns the new set.
5440 Returns the maximum value of the type T.
5443 Returns the minimum value of the type T.
5446 Returns boolean TRUE if I is an odd number.
5449 Returns the ordinal value of its argument. For example, the
5450 ordinal value of a character is its ASCII value (on machines
5451 supporting the ASCII character set). X must be of an ordered type,
5452 which include integral, character and enumerated types.
5455 Returns the size of its argument. X can be a variable or a type.
5458 Returns the integral part of R.
5461 Returns the size of its argument. X can be a variable or a type.
5464 Returns the member of the type T whose ordinal value is I.
5466 _Warning:_ Sets and their operations are not yet supported, so GDB
5467 treats the use of procedures 'INCL' and 'EXCL' as an error.
5470 File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2
5475 GDB allows you to express the constants of Modula-2 in the following
5478 * Integer constants are simply a sequence of digits. When used in an
5479 expression, a constant is interpreted to be type-compatible with
5480 the rest of the expression. Hexadecimal integers are specified by
5481 a trailing 'H', and octal integers by a trailing 'B'.
5483 * Floating point constants appear as a sequence of digits, followed
5484 by a decimal point and another sequence of digits. An optional
5485 exponent can then be specified, in the form 'E[+|-]NNN', where
5486 '[+|-]NNN' is the desired exponent. All of the digits of the
5487 floating point constant must be valid decimal (base 10) digits.
5489 * Character constants consist of a single character enclosed by a
5490 pair of like quotes, either single (''') or double ('"'). They may
5491 also be expressed by their ordinal value (their ASCII value,
5492 usually) followed by a 'C'.
5494 * String constants consist of a sequence of characters enclosed by a
5495 pair of like quotes, either single (''') or double ('"'). Escape
5496 sequences in the style of C are also allowed. *Note C and C++
5497 Constants: C Constants, for a brief explanation of escape
5500 * Enumerated constants consist of an enumerated identifier.
5502 * Boolean constants consist of the identifiers 'TRUE' and 'FALSE'.
5504 * Pointer constants consist of integral values only.
5506 * Set constants are not yet supported.
5509 File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2
5511 15.4.8.4 Modula-2 Types
5512 .......................
5514 Currently GDB can print the following data types in Modula-2 syntax:
5515 array types, record types, set types, pointer types, procedure types,
5516 enumerated types, subrange types and base types. You can also print the
5517 contents of variables declared using these type. This section gives a
5518 number of simple source code examples together with sample GDB sessions.
5520 The first example contains the following section of code:
5526 and you can request GDB to interrogate the type and value of 'r' and
5538 Likewise if your source code declares 's' as:
5543 then you may query the type of 's' by:
5546 type = SET ['A'..'Z']
5548 Note that at present you cannot interactively manipulate set expressions
5551 The following example shows how you might declare an array in
5552 Modula-2 and how you can interact with GDB to print its type and
5556 s: ARRAY [-10..10] OF CHAR ;
5559 ARRAY [-10..10] OF CHAR
5561 Note that the array handling is not yet complete and although the
5562 type is printed correctly, expression handling still assumes that all
5563 arrays have a lower bound of zero and not '-10' as in the example above.
5565 Here are some more type related Modula-2 examples:
5568 colour = (blue, red, yellow, green) ;
5569 t = [blue..yellow] ;
5575 The GDB interaction shows how you can query the data type and value of a
5581 type = [blue..yellow]
5583 In this example a Modula-2 array is declared and its contents displayed.
5584 Observe that the contents are written in the same way as their 'C'
5588 s: ARRAY [1..5] OF CARDINAL ;
5593 $1 = {1, 0, 0, 0, 0}
5595 type = ARRAY [1..5] OF CARDINAL
5597 The Modula-2 language interface to GDB also understands pointer types
5598 as shown in this example:
5601 s: POINTER TO ARRAY [1..5] OF CARDINAL ;
5606 and you can request that GDB describes the type of 's'.
5609 type = POINTER TO ARRAY [1..5] OF CARDINAL
5611 GDB handles compound types as we can see in this example. Here we
5612 combine array types, record types, pointer types and subrange types:
5621 myarray = ARRAY myrange OF CARDINAL ;
5624 s: POINTER TO ARRAY myrange OF foo ;
5626 and you can ask GDB to describe the type of 's' as shown below.
5629 type = POINTER TO ARRAY [-2..2] OF foo = RECORD
5632 f3 : ARRAY [-2..2] OF CARDINAL;
5636 File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2
5638 15.4.8.5 Modula-2 Defaults
5639 ..........................
5641 If type and range checking are set automatically by GDB, they both
5642 default to 'on' whenever the working language changes to Modula-2. This
5643 happens regardless of whether you or GDB selected the working language.
5645 If you allow GDB to set the language automatically, then entering
5646 code compiled from a file whose name ends with '.mod' sets the working
5647 language to Modula-2. *Note Having GDB Infer the Source Language:
5648 Automatically, for further details.
5651 File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2
5653 15.4.8.6 Deviations from Standard Modula-2
5654 ..........................................
5656 A few changes have been made to make Modula-2 programs easier to debug.
5657 This is done primarily via loosening its type strictness:
5659 * Unlike in standard Modula-2, pointer constants can be formed by
5660 integers. This allows you to modify pointer variables during
5661 debugging. (In standard Modula-2, the actual address contained in
5662 a pointer variable is hidden from you; it can only be modified
5663 through direct assignment to another pointer variable or expression
5664 that returned a pointer.)
5666 * C escape sequences can be used in strings and characters to
5667 represent non-printable characters. GDB prints out strings with
5668 these escape sequences embedded. Single non-printable characters
5669 are printed using the 'CHR(NNN)' format.
5671 * The assignment operator (':=') returns the value of its right-hand
5674 * All built-in procedures both modify _and_ return their argument.
5677 File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2
5679 15.4.8.7 Modula-2 Type and Range Checks
5680 .......................................
5682 _Warning:_ in this release, GDB does not yet perform type or range
5685 GDB considers two Modula-2 variables type equivalent if:
5687 * They are of types that have been declared equivalent via a 'TYPE T1
5690 * They have been declared on the same line. (Note: This is true of
5691 the GNU Modula-2 compiler, but it may not be true of other
5694 As long as type checking is enabled, any attempt to combine variables
5695 whose types are not equivalent is an error.
5697 Range checking is done on all mathematical operations, assignment,
5698 array index bounds, and all built-in functions and procedures.
5701 File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2
5703 15.4.8.8 The Scope Operators '::' and '.'
5704 .........................................
5706 There are a few subtle differences between the Modula-2 scope operator
5707 ('.') and the GDB scope operator ('::'). The two have similar syntax:
5713 where SCOPE is the name of a module or a procedure, MODULE the name of a
5714 module, and ID is any declared identifier within your program, except
5717 Using the '::' operator makes GDB search the scope specified by SCOPE
5718 for the identifier ID. If it is not found in the specified scope, then
5719 GDB searches all scopes enclosing the one specified by SCOPE.
5721 Using the '.' operator makes GDB search the current scope for the
5722 identifier specified by ID that was imported from the definition module
5723 specified by MODULE. With this operator, it is an error if the
5724 identifier ID was not imported from definition module MODULE, or if ID
5725 is not an identifier in MODULE.
5728 File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2
5730 15.4.8.9 GDB and Modula-2
5731 .........................
5733 Some GDB commands have little use when debugging Modula-2 programs.
5734 Five subcommands of 'set print' and 'show print' apply specifically to C
5735 and C++: 'vtbl', 'demangle', 'asm-demangle', 'object', and 'union'. The
5736 first four apply to C++, and the last to the C 'union' type, which has
5737 no direct analogue in Modula-2.
5739 The '@' operator (*note Expressions: Expressions.), while available
5740 with any language, is not useful with Modula-2. Its intent is to aid
5741 the debugging of "dynamic arrays", which cannot be created in Modula-2
5742 as they can in C or C++. However, because an address can be specified
5743 by an integral constant, the construct '{TYPE}ADREXP' is still useful.
5745 In GDB scripts, the Modula-2 inequality operator '#' is interpreted
5746 as the beginning of a comment. Use '<>' instead.
5749 File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages
5754 The extensions made to GDB for Ada only support output from the GNU Ada
5755 (GNAT) compiler. Other Ada compilers are not currently supported, and
5756 attempting to debug executables produced by them is most likely to be
5761 * Ada Mode Intro:: General remarks on the Ada syntax
5762 and semantics supported by Ada mode
5764 * Omissions from Ada:: Restrictions on the Ada expression syntax.
5765 * Additions to Ada:: Extensions of the Ada expression syntax.
5766 * Stopping Before Main Program:: Debugging the program during elaboration.
5767 * Ada Exceptions:: Ada Exceptions
5768 * Ada Tasks:: Listing and setting breakpoints in tasks.
5769 * Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
5770 * Ravenscar Profile:: Tasking Support when using the Ravenscar
5772 * Ada Glitches:: Known peculiarities of Ada mode.
5775 File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada
5777 15.4.9.1 Introduction
5778 .....................
5780 The Ada mode of GDB supports a fairly large subset of Ada expression
5781 syntax, with some extensions. The philosophy behind the design of this
5784 * That GDB should provide basic literals and access to operations for
5785 arithmetic, dereferencing, field selection, indexing, and
5786 subprogram calls, leaving more sophisticated computations to
5787 subprograms written into the program (which therefore may be called
5790 * That type safety and strict adherence to Ada language restrictions
5791 are not particularly important to the GDB user.
5793 * That brevity is important to the GDB user.
5795 Thus, for brevity, the debugger acts as if all names declared in
5796 user-written packages are directly visible, even if they are not visible
5797 according to Ada rules, thus making it unnecessary to fully qualify most
5798 names with their packages, regardless of context. Where this causes
5799 ambiguity, GDB asks the user's intent.
5801 The debugger will start in Ada mode if it detects an Ada main
5802 program. As for other languages, it will enter Ada mode when stopped in
5803 a program that was translated from an Ada source file.
5805 While in Ada mode, you may use '--' for comments. This is useful
5806 mostly for documenting command files. The standard GDB comment ('#')
5807 still works at the beginning of a line in Ada mode, but not in the
5808 middle (to allow based literals).
5810 The debugger supports limited overloading. Given a subprogram call
5811 in which the function symbol has multiple definitions, it will use the
5812 number of actual parameters and some information about their types to
5813 attempt to narrow the set of definitions. It also makes very limited
5814 use of context, preferring procedures to functions in the context of the
5815 'call' command, and functions to procedures elsewhere.
5818 File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada
5820 15.4.9.2 Omissions from Ada
5821 ...........................
5823 Here are the notable omissions from the subset:
5825 * Only a subset of the attributes are supported:
5827 - 'First, 'Last, and 'Length on array objects (not on types and
5836 - 'Range on array objects (not subtypes), but only as the right
5837 operand of the membership ('in') operator.
5839 - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT
5844 * The names in 'Characters.Latin_1' are not available and
5845 concatenation is not implemented. Thus, escape characters in
5846 strings are not currently available.
5848 * Equality tests ('=' and '/=') on arrays test for bitwise equality
5849 of representations. They will generally work correctly for strings
5850 and arrays whose elements have integer or enumeration types. They
5851 may not work correctly for arrays whose element types have
5852 user-defined equality, for arrays of real values (in particular,
5853 IEEE-conformant floating point, because of negative zeroes and
5854 NaNs), and for arrays whose elements contain unused bits with
5855 indeterminate values.
5857 * The other component-by-component array operations ('and', 'or',
5858 'xor', 'not', and relational tests other than equality) are not
5861 * There is limited support for array and record aggregates. They are
5862 permitted only on the right sides of assignments, as in these
5865 (gdb) set An_Array := (1, 2, 3, 4, 5, 6)
5866 (gdb) set An_Array := (1, others => 0)
5867 (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
5868 (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
5869 (gdb) set A_Record := (1, "Peter", True);
5870 (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True)
5872 Changing a discriminant's value by assigning an aggregate has an
5873 undefined effect if that discriminant is used within the record.
5874 However, you can first modify discriminants by directly assigning
5875 to them (which normally would not be allowed in Ada), and then
5876 performing an aggregate assignment. For example, given a variable
5877 'A_Rec' declared to have a type such as:
5879 type Rec (Len : Small_Integer := 0) is record
5881 Vals : IntArray (1 .. Len);
5884 you can assign a value with a different size of 'Vals' with two
5887 (gdb) set A_Rec.Len := 4
5888 (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
5890 As this example also illustrates, GDB is very loose about the usual
5891 rules concerning aggregates. You may leave out some of the
5892 components of an array or record aggregate (such as the 'Len'
5893 component in the assignment to 'A_Rec' above); they will retain
5894 their original values upon assignment. You may freely use dynamic
5895 values as indices in component associations. You may even use
5896 overlapping or redundant component associations, although which
5897 component values are assigned in such cases is not defined.
5899 * Calls to dispatching subprograms are not implemented.
5901 * The overloading algorithm is much more limited (i.e., less
5902 selective) than that of real Ada. It makes only limited use of the
5903 context in which a subexpression appears to resolve its meaning,
5904 and it is much looser in its rules for allowing type matches. As a
5905 result, some function calls will be ambiguous, and the user will be
5906 asked to choose the proper resolution.
5908 * The 'new' operator is not implemented.
5910 * Entry calls are not implemented.
5912 * Aside from printing, arithmetic operations on the native VAX
5913 floating-point formats are not supported.
5915 * It is not possible to slice a packed array.
5917 * The names 'True' and 'False', when not part of a qualified name,
5918 are interpreted as if implicitly prefixed by 'Standard', regardless
5919 of context. Should your program redefine these names in a package
5920 or procedure (at best a dubious practice), you will have to use
5921 fully qualified names to access their new definitions.
5924 File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada
5926 15.4.9.3 Additions to Ada
5927 .........................
5929 As it does for other languages, GDB makes certain generic extensions to
5930 Ada (*note Expressions::):
5932 * If the expression E is a variable residing in memory (typically a
5933 local variable or array element) and N is a positive integer, then
5934 'E@N' displays the values of E and the N-1 adjacent variables
5935 following it in memory as an array. In Ada, this operator is
5936 generally not necessary, since its prime use is in displaying parts
5937 of an array, and slicing will usually do this in Ada. However,
5938 there are occasional uses when debugging programs in which certain
5939 debugging information has been optimized away.
5941 * 'B::VAR' means "the variable named VAR that appears in function or
5942 file B." When B is a file name, you must typically surround it in
5945 * The expression '{TYPE} ADDR' means "the variable of type TYPE that
5946 appears at address ADDR."
5948 * A name starting with '$' is a convenience variable (*note
5949 Convenience Vars::) or a machine register (*note Registers::).
5951 In addition, GDB provides a few other shortcuts and outright
5952 additions specific to Ada:
5954 * The assignment statement is allowed as an expression, returning its
5955 right-hand operand as its value. Thus, you may enter
5957 (gdb) set x := y + 3
5958 (gdb) print A(tmp := y + 1)
5960 * The semicolon is allowed as an "operator," returning as its value
5961 the value of its right-hand operand. This allows, for example,
5962 complex conditional breaks:
5965 (gdb) condition 1 (report(i); k += 1; A(k) > 100)
5967 * Rather than use catenation and symbolic character names to
5968 introduce special characters into strings, one may instead use a
5969 special bracket notation, which is also used to print strings. A
5970 sequence of characters of the form '["XX"]' within a string or
5971 character literal denotes the (single) character whose numeric
5972 encoding is XX in hexadecimal. The sequence of characters '["""]'
5973 also denotes a single quotation mark in strings. For example,
5974 "One line.["0a"]Next line.["0a"]"
5975 contains an ASCII newline character ('Ada.Characters.Latin_1.LF')
5978 * The subtype used as a prefix for the attributes 'Pos, 'Min, and
5979 'Max is optional (and is ignored in any case). For example, it is
5982 (gdb) print 'max(x, y)
5984 * When printing arrays, GDB uses positional notation when the array
5985 has a lower bound of 1, and uses a modified named notation
5986 otherwise. For example, a one-dimensional array of three integers
5987 with a lower bound of 3 might print as
5991 That is, in contrast to valid Ada, only the first component has a
5994 * You may abbreviate attributes in expressions with any unique,
5995 multi-character subsequence of their names (an exact match gets
5996 preference). For example, you may use a'len, a'gth, or a'lh in
5999 * Since Ada is case-insensitive, the debugger normally maps
6000 identifiers you type to lower case. The GNAT compiler uses
6001 upper-case characters for some of its internal identifiers, which
6002 are normally of no interest to users. For the rare occasions when
6003 you actually have to look at them, enclose them in angle brackets
6004 to avoid the lower-case mapping. For example,
6005 (gdb) print <JMPBUF_SAVE>[0]
6007 * Printing an object of class-wide type or dereferencing an
6008 access-to-class-wide value will display all the components of the
6009 object's specific type (as indicated by its run-time tag).
6010 Likewise, component selection on such a value will operate on the
6011 specific type of the object.
6014 File: gdb.info, Node: Stopping Before Main Program, Next: Ada Exceptions, Prev: Additions to Ada, Up: Ada
6016 15.4.9.4 Stopping at the Very Beginning
6017 .......................................
6019 It is sometimes necessary to debug the program during elaboration, and
6020 before reaching the main procedure. As defined in the Ada Reference
6021 Manual, the elaboration code is invoked from a procedure called
6022 'adainit'. To run your program up to the beginning of elaboration,
6023 simply use the following two commands: 'tbreak adainit' and 'run'.
6026 File: gdb.info, Node: Ada Exceptions, Next: Ada Tasks, Prev: Stopping Before Main Program, Up: Ada
6028 15.4.9.5 Ada Exceptions
6029 .......................
6031 A command is provided to list all Ada exceptions:
6034 'info exceptions REGEXP'
6035 The 'info exceptions' command allows you to list all Ada exceptions
6036 defined within the program being debugged, as well as their
6037 addresses. With a regular expression, REGEXP, as argument, only
6038 those exceptions whose names match REGEXP are listed.
6040 Below is a small example, showing how the command can be used, first
6041 without argument, and next with a regular expression passed as an
6044 (gdb) info exceptions
6045 All defined Ada exceptions:
6046 constraint_error: 0x613da0
6047 program_error: 0x613d20
6048 storage_error: 0x613ce0
6049 tasking_error: 0x613ca0
6050 const.aint_global_e: 0x613b00
6051 (gdb) info exceptions const.aint
6052 All Ada exceptions matching regular expression "const.aint":
6053 constraint_error: 0x613da0
6054 const.aint_global_e: 0x613b00
6056 It is also possible to ask GDB to stop your program's execution when
6057 an exception is raised. For more details, see *note Set Catchpoints::.
6060 File: gdb.info, Node: Ada Tasks, Next: Ada Tasks and Core Files, Prev: Ada Exceptions, Up: Ada
6062 15.4.9.6 Extensions for Ada Tasks
6063 .................................
6065 Support for Ada tasks is analogous to that for threads (*note
6066 Threads::). GDB provides the following task-related commands:
6069 This command shows a list of current Ada tasks, as in the following
6073 ID TID P-ID Pri State Name
6074 1 8088000 0 15 Child Activation Wait main_task
6075 2 80a4000 1 15 Accept Statement b
6076 3 809a800 1 15 Child Activation Wait a
6077 * 4 80ae800 3 15 Runnable c
6079 In this listing, the asterisk before the last task indicates it to
6080 be the task currently being inspected.
6083 Represents GDB's internal task number.
6089 The parent's task ID (GDB's internal task number).
6092 The base priority of the task.
6095 Current state of the task.
6098 The task has been created but has not been activated. It
6099 cannot be executing.
6102 The task is not blocked for any reason known to Ada. (It
6103 may be waiting for a mutex, though.) It is conceptually
6104 "executing" in normal mode.
6107 The task is terminated, in the sense of ARM 9.3 (5). Any
6108 dependents that were waiting on terminate alternatives
6109 have been awakened and have terminated themselves.
6111 'Child Activation Wait'
6112 The task is waiting for created tasks to complete
6116 The task is waiting on an accept or selective wait
6119 'Waiting on entry call'
6120 The task is waiting on an entry call.
6123 The task is waiting to start the abortable part of an
6124 asynchronous select statement.
6127 The task is waiting on a select statement with only a
6128 delay alternative open.
6130 'Child Termination Wait'
6131 The task is sleeping having completed a master within
6132 itself, and is waiting for the tasks dependent on that
6133 master to become terminated or waiting on a terminate
6136 'Wait Child in Term Alt'
6137 The task is sleeping waiting for tasks on terminate
6138 alternatives to finish terminating.
6140 'Accepting RV with TASKNO'
6141 The task is accepting a rendez-vous with the task TASKNO.
6144 Name of the task in the program.
6147 This command shows detailled informations on the specified task, as
6148 in the following example:
6150 ID TID P-ID Pri State Name
6151 1 8077880 0 15 Child Activation Wait main_task
6152 * 2 807c468 1 15 Runnable task_1
6157 Parent: 1 (main_task)
6162 This command prints the ID of the current task.
6165 ID TID P-ID Pri State Name
6166 1 8077870 0 15 Child Activation Wait main_task
6167 * 2 807c458 1 15 Runnable t
6172 This command is like the 'thread THREADNO' command (*note
6173 Threads::). It switches the context of debugging from the current
6174 task to the given task.
6177 ID TID P-ID Pri State Name
6178 1 8077870 0 15 Child Activation Wait main_task
6179 * 2 807c458 1 15 Runnable t
6181 [Switching to task 1]
6182 #0 0x8067726 in pthread_cond_wait ()
6184 #0 0x8067726 in pthread_cond_wait ()
6185 #1 0x8056714 in system.os_interface.pthread_cond_wait ()
6186 #2 0x805cb63 in system.task_primitives.operations.sleep ()
6187 #3 0x806153e in system.tasking.stages.activate_tasks ()
6188 #4 0x804aacc in un () at un.adb:5
6190 'break LINESPEC task TASKNO'
6191 'break LINESPEC task TASKNO if ...'
6192 These commands are like the 'break ... thread ...' command (*note
6193 Thread Stops::). LINESPEC specifies source lines, as described in
6194 *note Specify Location::.
6196 Use the qualifier 'task TASKNO' with a breakpoint command to
6197 specify that you only want GDB to stop the program when a
6198 particular Ada task reaches this breakpoint. TASKNO is one of the
6199 numeric task identifiers assigned by GDB, shown in the first column
6200 of the 'info tasks' display.
6202 If you do not specify 'task TASKNO' when you set a breakpoint, the
6203 breakpoint applies to _all_ tasks of your program.
6205 You can use the 'task' qualifier on conditional breakpoints as
6206 well; in this case, place 'task TASKNO' before the breakpoint
6207 condition (before the 'if').
6212 ID TID P-ID Pri State Name
6213 1 140022020 0 15 Child Activation Wait main_task
6214 2 140045060 1 15 Accept/Select Wait t2
6215 3 140044840 1 15 Runnable t1
6216 * 4 140056040 1 15 Runnable t3
6218 Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
6224 Breakpoint 5, test_task_debug () at test_task_debug.adb:15
6227 ID TID P-ID Pri State Name
6228 1 140022020 0 15 Child Activation Wait main_task
6229 * 2 140045060 1 15 Runnable t2
6230 3 140044840 1 15 Runnable t1
6231 4 140056040 1 15 Delay Sleep t3
6234 File: gdb.info, Node: Ada Tasks and Core Files, Next: Ravenscar Profile, Prev: Ada Tasks, Up: Ada
6236 15.4.9.7 Tasking Support when Debugging Core Files
6237 ..................................................
6239 When inspecting a core file, as opposed to debugging a live program,
6240 tasking support may be limited or even unavailable, depending on the
6241 platform being used. For instance, on x86-linux, the list of tasks is
6242 available, but task switching is not supported. On Tru64, however, task
6243 switching will work as usual.
6245 On certain platforms, including Tru64, the debugger needs to perform
6246 some memory writes in order to provide Ada tasking support. When
6247 inspecting a core file, this means that the core file must be opened
6248 with read-write privileges, using the command '"set write on"' (*note
6249 Patching::). Under these circumstances, you should make a backup copy
6250 of the core file before inspecting it with GDB.
6253 File: gdb.info, Node: Ravenscar Profile, Next: Ada Glitches, Prev: Ada Tasks and Core Files, Up: Ada
6255 15.4.9.8 Tasking Support when using the Ravenscar Profile
6256 .........................................................
6258 The "Ravenscar Profile" is a subset of the Ada tasking features,
6259 specifically designed for systems with safety-critical real-time
6262 'set ravenscar task-switching on'
6263 Allows task switching when debugging a program that uses the
6264 Ravenscar Profile. This is the default.
6266 'set ravenscar task-switching off'
6267 Turn off task switching when debugging a program that uses the
6268 Ravenscar Profile. This is mostly intended to disable the code
6269 that adds support for the Ravenscar Profile, in case a bug in
6270 either GDB or in the Ravenscar runtime is preventing GDB from
6271 working properly. To be effective, this command should be run
6272 before the program is started.
6274 'show ravenscar task-switching'
6275 Show whether it is possible to switch from task to task in a
6276 program using the Ravenscar Profile.
6279 File: gdb.info, Node: Ada Glitches, Prev: Ravenscar Profile, Up: Ada
6281 15.4.9.9 Known Peculiarities of Ada Mode
6282 ........................................
6284 Besides the omissions listed previously (*note Omissions from Ada::), we
6285 know of several problems with and limitations of Ada mode in GDB, some
6286 of which will be fixed with planned future releases of the debugger and
6287 the GNU Ada compiler.
6289 * Static constants that the compiler chooses not to materialize as
6290 objects in storage are invisible to the debugger.
6292 * Named parameter associations in function argument lists are ignored
6293 (the argument lists are treated as positional).
6295 * Many useful library packages are currently invisible to the
6298 * Fixed-point arithmetic, conversions, input, and output is carried
6299 out using floating-point arithmetic, and may give results that only
6300 approximate those on the host machine.
6302 * The GNAT compiler never generates the prefix 'Standard' for any of
6303 the standard symbols defined by the Ada language. GDB knows about
6304 this: it will strip the prefix from names when you use it, and will
6305 never look for a name you have so qualified among local symbols,
6306 nor match against symbols in other packages or subprograms. If you
6307 have defined entities anywhere in your program other than
6308 parameters and local variables whose simple names match names in
6309 'Standard', GNAT's lack of qualification here can cause confusion.
6310 When this happens, you can usually resolve the confusion by
6311 qualifying the problematic names with package 'Standard'
6314 Older versions of the compiler sometimes generate erroneous debugging
6315 information, resulting in the debugger incorrectly printing the value of
6316 affected entities. In some cases, the debugger is able to work around
6317 an issue automatically. In other cases, the debugger is able to work
6318 around the issue, but the work-around has to be specifically enabled.
6320 'set ada trust-PAD-over-XVS on'
6321 Configure GDB to strictly follow the GNAT encoding when computing
6322 the value of Ada entities, particularly when 'PAD' and 'PAD___XVS'
6323 types are involved (see 'ada/exp_dbug.ads' in the GCC sources for a
6324 complete description of the encoding used by the GNAT compiler).
6325 This is the default.
6327 'set ada trust-PAD-over-XVS off'
6328 This is related to the encoding using by the GNAT compiler. If GDB
6329 sometimes prints the wrong value for certain entities, changing
6330 'ada trust-PAD-over-XVS' to 'off' activates a work-around which may
6331 fix the issue. It is always safe to set 'ada trust-PAD-over-XVS'
6332 to 'off', but this incurs a slight performance penalty, so it is
6333 recommended to leave this setting to 'on' unless necessary.
6336 File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages
6338 15.5 Unsupported Languages
6339 ==========================
6341 In addition to the other fully-supported programming languages, GDB also
6342 provides a pseudo-language, called 'minimal'. It does not represent a
6343 real programming language, but provides a set of capabilities close to
6344 what the C or assembly languages provide. This should allow most simple
6345 operations to be performed while debugging an application that uses a
6346 language currently not supported by GDB.
6348 If the language is set to 'auto', GDB will automatically select this
6349 language if the current frame corresponds to an unsupported language.
6352 File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top
6354 16 Examining the Symbol Table
6355 *****************************
6357 The commands described in this chapter allow you to inquire about the
6358 symbols (names of variables, functions and types) defined in your
6359 program. This information is inherent in the text of your program and
6360 does not change as your program executes. GDB finds it in your
6361 program's symbol table, in the file indicated when you started GDB
6362 (*note Choosing Files: File Options.), or by one of the file-management
6363 commands (*note Commands to Specify Files: Files.).
6365 Occasionally, you may need to refer to symbols that contain unusual
6366 characters, which GDB ordinarily treats as word delimiters. The most
6367 frequent case is in referring to static variables in other source files
6368 (*note Program Variables: Variables.). File names are recorded in
6369 object files as debugging symbols, but GDB would ordinarily parse a
6370 typical file name, like 'foo.c', as the three words 'foo' '.' 'c'. To
6371 allow GDB to recognize 'foo.c' as a single symbol, enclose it in single
6372 quotes; for example,
6376 looks up the value of 'x' in the scope of the file 'foo.c'.
6378 'set case-sensitive on'
6379 'set case-sensitive off'
6380 'set case-sensitive auto'
6381 Normally, when GDB looks up symbols, it matches their names with
6382 case sensitivity determined by the current source language.
6383 Occasionally, you may wish to control that. The command 'set
6384 case-sensitive' lets you do that by specifying 'on' for
6385 case-sensitive matches or 'off' for case-insensitive ones. If you
6386 specify 'auto', case sensitivity is reset to the default suitable
6387 for the source language. The default is case-sensitive matches for
6388 all languages except for Fortran, for which the default is
6389 case-insensitive matches.
6391 'show case-sensitive'
6392 This command shows the current setting of case sensitivity for
6395 'set print type methods'
6396 'set print type methods on'
6397 'set print type methods off'
6398 Normally, when GDB prints a class, it displays any methods declared
6399 in that class. You can control this behavior either by passing the
6400 appropriate flag to 'ptype', or using 'set print type methods'.
6401 Specifying 'on' will cause GDB to display the methods; this is the
6402 default. Specifying 'off' will cause GDB to omit the methods.
6404 'show print type methods'
6405 This command shows the current setting of method display when
6408 'set print type typedefs'
6409 'set print type typedefs on'
6410 'set print type typedefs off'
6412 Normally, when GDB prints a class, it displays any typedefs defined
6413 in that class. You can control this behavior either by passing the
6414 appropriate flag to 'ptype', or using 'set print type typedefs'.
6415 Specifying 'on' will cause GDB to display the typedef definitions;
6416 this is the default. Specifying 'off' will cause GDB to omit the
6417 typedef definitions. Note that this controls whether the typedef
6418 definition itself is printed, not whether typedef names are
6419 substituted when printing other types.
6421 'show print type typedefs'
6422 This command shows the current setting of typedef display when
6425 'info address SYMBOL'
6426 Describe where the data for SYMBOL is stored. For a register
6427 variable, this says which register it is kept in. For a
6428 non-register local variable, this prints the stack-frame offset at
6429 which the variable is always stored.
6431 Note the contrast with 'print &SYMBOL', which does not work at all
6432 for a register variable, and for a stack local variable prints the
6433 exact address of the current instantiation of the variable.
6436 Print the name of a symbol which is stored at the address ADDR. If
6437 no symbol is stored exactly at ADDR, GDB prints the nearest symbol
6438 and an offset from it:
6440 (gdb) info symbol 0x54320
6441 _initialize_vx + 396 in section .text
6443 This is the opposite of the 'info address' command. You can use it
6444 to find out the name of a variable or a function given its address.
6446 For dynamically linked executables, the name of executable or
6447 shared library containing the symbol is also printed:
6449 (gdb) info symbol 0x400225
6450 _start + 5 in section .text of /tmp/a.out
6451 (gdb) info symbol 0x2aaaac2811cf
6452 __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
6454 'whatis[/FLAGS] [ARG]'
6455 Print the data type of ARG, which can be either an expression or a
6456 name of a data type. With no argument, print the data type of '$',
6457 the last value in the value history.
6459 If ARG is an expression (*note Expressions: Expressions.), it is
6460 not actually evaluated, and any side-effecting operations (such as
6461 assignments or function calls) inside it do not take place.
6463 If ARG is a variable or an expression, 'whatis' prints its literal
6464 type as it is used in the source code. If the type was defined
6465 using a 'typedef', 'whatis' will _not_ print the data type
6466 underlying the 'typedef'. If the type of the variable or the
6467 expression is a compound data type, such as 'struct' or 'class',
6468 'whatis' never prints their fields or methods. It just prints the
6469 'struct'/'class' name (a.k.a. its "tag"). If you want to see the
6470 members of such a compound data type, use 'ptype'.
6472 If ARG is a type name that was defined using 'typedef', 'whatis'
6473 "unrolls" only one level of that 'typedef'. Unrolling means that
6474 'whatis' will show the underlying type used in the 'typedef'
6475 declaration of ARG. However, if that underlying type is also a
6476 'typedef', 'whatis' will not unroll it.
6478 For C code, the type names may also have the form 'class
6479 CLASS-NAME', 'struct STRUCT-TAG', 'union UNION-TAG' or 'enum
6482 FLAGS can be used to modify how the type is displayed. Available
6486 Display in "raw" form. Normally, GDB substitutes template
6487 parameters and typedefs defined in a class when printing the
6488 class' members. The '/r' flag disables this.
6491 Do not print methods defined in the class.
6494 Print methods defined in the class. This is the default, but
6495 the flag exists in case you change the default with 'set print
6499 Do not print typedefs defined in the class. Note that this
6500 controls whether the typedef definition itself is printed, not
6501 whether typedef names are substituted when printing other
6505 Print typedefs defined in the class. This is the default, but
6506 the flag exists in case you change the default with 'set print
6509 'ptype[/FLAGS] [ARG]'
6510 'ptype' accepts the same arguments as 'whatis', but prints a
6511 detailed description of the type, instead of just the name of the
6512 type. *Note Expressions: Expressions.
6514 Contrary to 'whatis', 'ptype' always unrolls any 'typedef's in its
6515 argument declaration, whether the argument is a variable,
6516 expression, or a data type. This means that 'ptype' of a variable
6517 or an expression will not print literally its type as present in
6518 the source code--use 'whatis' for that. 'typedef's at the pointer
6519 or reference targets are also unrolled. Only 'typedef's of fields,
6520 methods and inner 'class typedef's of 'struct's, 'class'es and
6521 'union's are not unrolled even with 'ptype'.
6523 For example, for this variable declaration:
6525 typedef double real_t;
6526 struct complex { real_t real; double imag; };
6527 typedef struct complex complex_t;
6529 real_t *real_pointer_var;
6531 the two commands give this output:
6536 type = struct complex {
6540 (gdb) whatis complex_t
6541 type = struct complex
6542 (gdb) whatis struct complex
6543 type = struct complex
6544 (gdb) ptype struct complex
6545 type = struct complex {
6549 (gdb) whatis real_pointer_var
6551 (gdb) ptype real_pointer_var
6554 As with 'whatis', using 'ptype' without an argument refers to the
6555 type of '$', the last value in the value history.
6557 Sometimes, programs use opaque data types or incomplete
6558 specifications of complex data structure. If the debug information
6559 included in the program does not allow GDB to display a full
6560 declaration of the data type, it will say '<incomplete type>'. For
6561 example, given these declarations:
6566 but no definition for 'struct foo' itself, GDB will say:
6569 $1 = <incomplete type>
6571 "Incomplete type" is C terminology for data types that are not
6572 completely specified.
6576 Print a brief description of all types whose names match the
6577 regular expression REGEXP (or all types in your program, if you
6578 supply no argument). Each complete typename is matched as though
6579 it were a complete line; thus, 'i type value' gives information on
6580 all types in your program whose names include the string 'value',
6581 but 'i type ^value$' gives information only on types whose complete
6584 This command differs from 'ptype' in two ways: first, like
6585 'whatis', it does not print a detailed description; second, it
6586 lists all source files where a type is defined.
6588 'info type-printers'
6589 Versions of GDB that ship with Python scripting enabled may have
6590 "type printers" available. When using 'ptype' or 'whatis', these
6591 printers are consulted when the name of a type is needed. *Note
6592 Type Printing API::, for more information on writing type printers.
6594 'info type-printers' displays all the available type printers.
6596 'enable type-printer NAME...'
6597 'disable type-printer NAME...'
6598 These commands can be used to enable or disable type printers.
6600 'info scope LOCATION'
6601 List all the variables local to a particular scope. This command
6602 accepts a LOCATION argument--a function name, a source line, or an
6603 address preceded by a '*', and prints all the variables local to
6604 the scope defined by that location. (*Note Specify Location::, for
6605 details about supported forms of LOCATION.) For example:
6607 (gdb) info scope command_line_handler
6608 Scope for command_line_handler:
6609 Symbol rl is an argument at stack/frame offset 8, length 4.
6610 Symbol linebuffer is in static storage at address 0x150a18, length 4.
6611 Symbol linelength is in static storage at address 0x150a1c, length 4.
6612 Symbol p is a local variable in register $esi, length 4.
6613 Symbol p1 is a local variable in register $ebx, length 4.
6614 Symbol nline is a local variable in register $edx, length 4.
6615 Symbol repeat is a local variable at frame offset -8, length 4.
6617 This command is especially useful for determining what data to
6618 collect during a "trace experiment", see *note collect: Tracepoint
6622 Show information about the current source file--that is, the source
6623 file for the function containing the current point of execution:
6624 * the name of the source file, and the directory containing it,
6625 * the directory it was compiled in,
6626 * its length, in lines,
6627 * which programming language it is written in,
6628 * whether the executable includes debugging information for that
6629 file, and if so, what format the information is in (e.g.,
6630 STABS, Dwarf 2, etc.), and
6631 * whether the debugging information includes information about
6632 preprocessor macros.
6635 Print the names of all source files in your program for which there
6636 is debugging information, organized into two lists: files whose
6637 symbols have already been read, and files whose symbols will be
6641 Print the names and data types of all defined functions.
6643 'info functions REGEXP'
6644 Print the names and data types of all defined functions whose names
6645 contain a match for regular expression REGEXP. Thus, 'info fun
6646 step' finds all functions whose names include 'step'; 'info fun
6647 ^step' finds those whose names start with 'step'. If a function
6648 name contains characters that conflict with the regular expression
6649 language (e.g. 'operator*()'), they may be quoted with a backslash.
6652 Print the names and data types of all variables that are defined
6653 outside of functions (i.e. excluding local variables).
6655 'info variables REGEXP'
6656 Print the names and data types of all variables (except for local
6657 variables) whose names contain a match for regular expression
6661 'info classes REGEXP'
6662 Display all Objective-C classes in your program, or (with the
6663 REGEXP argument) all those matching a particular regular
6667 'info selectors REGEXP'
6668 Display all Objective-C selectors in your program, or (with the
6669 REGEXP argument) all those matching a particular regular
6672 'set opaque-type-resolution on'
6673 Tell GDB to resolve opaque types. An opaque type is a type
6674 declared as a pointer to a 'struct', 'class', or 'union'--for
6675 example, 'struct MyType *'--that is used in one source file
6676 although the full declaration of 'struct MyType' is in another
6677 source file. The default is on.
6679 A change in the setting of this subcommand will not take effect
6680 until the next time symbols for a file are loaded.
6682 'set opaque-type-resolution off'
6683 Tell GDB not to resolve opaque types. In this case, the type is
6687 'show opaque-type-resolution'
6688 Show whether opaque types are resolved or not.
6690 'maint print symbols FILENAME'
6691 'maint print psymbols FILENAME'
6692 'maint print msymbols FILENAME'
6693 Write a dump of debugging symbol data into the file FILENAME.
6694 These commands are used to debug the GDB symbol-reading code. Only
6695 symbols with debugging data are included. If you use 'maint print
6696 symbols', GDB includes all the symbols for which it has already
6697 collected full details: that is, FILENAME reflects symbols for only
6698 those files whose symbols GDB has read. You can use the command
6699 'info sources' to find out which files these are. If you use
6700 'maint print psymbols' instead, the dump shows information about
6701 symbols that GDB only knows partially--that is, symbols defined in
6702 files that GDB has skimmed, but not yet read completely. Finally,
6703 'maint print msymbols' dumps just the minimal symbol information
6704 required for each object file from which GDB has read some symbols.
6705 *Note Commands to Specify Files: Files, for a discussion of how GDB
6706 reads symbols (in the description of 'symbol-file').
6708 'maint info symtabs [ REGEXP ]'
6709 'maint info psymtabs [ REGEXP ]'
6711 List the 'struct symtab' or 'struct partial_symtab' structures
6712 whose names match REGEXP. If REGEXP is not given, list them all.
6713 The output includes expressions which you can copy into a GDB
6714 debugging this one to examine a particular structure in more
6715 detail. For example:
6717 (gdb) maint info psymtabs dwarf2read
6718 { objfile /home/gnu/build/gdb/gdb
6719 ((struct objfile *) 0x82e69d0)
6720 { psymtab /home/gnu/src/gdb/dwarf2read.c
6721 ((struct partial_symtab *) 0x8474b10)
6724 text addresses 0x814d3c8 -- 0x8158074
6725 globals (* (struct partial_symbol **) 0x8507a08 @ 9)
6726 statics (* (struct partial_symbol **) 0x40e95b78 @ 2882)
6730 (gdb) maint info symtabs
6732 We see that there is one partial symbol table whose filename
6733 contains the string 'dwarf2read', belonging to the 'gdb'
6734 executable; and we see that GDB has not read in any symtabs yet at
6735 all. If we set a breakpoint on a function, that will cause GDB to
6736 read the symtab for the compilation unit containing that function:
6738 (gdb) break dwarf2_psymtab_to_symtab
6739 Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
6741 (gdb) maint info symtabs
6742 { objfile /home/gnu/build/gdb/gdb
6743 ((struct objfile *) 0x82e69d0)
6744 { symtab /home/gnu/src/gdb/dwarf2read.c
6745 ((struct symtab *) 0x86c1f38)
6748 blockvector ((struct blockvector *) 0x86c1bd0) (primary)
6749 linetable ((struct linetable *) 0x8370fa0)
6756 File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top
6758 17 Altering Execution
6759 *********************
6761 Once you think you have found an error in your program, you might want
6762 to find out for certain whether correcting the apparent error would lead
6763 to correct results in the rest of the run. You can find the answer by
6764 experiment, using the GDB features for altering execution of the
6767 For example, you can store new values into variables or memory
6768 locations, give your program a signal, restart it at a different
6769 address, or even return prematurely from a function.
6773 * Assignment:: Assignment to variables
6774 * Jumping:: Continuing at a different address
6775 * Signaling:: Giving your program a signal
6776 * Returning:: Returning from a function
6777 * Calling:: Calling your program's functions
6778 * Patching:: Patching your program
6781 File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering
6783 17.1 Assignment to Variables
6784 ============================
6786 To alter the value of a variable, evaluate an assignment expression.
6787 *Note Expressions: Expressions. For example,
6791 stores the value 4 into the variable 'x', and then prints the value of
6792 the assignment expression (which is 4). *Note Using GDB with Different
6793 Languages: Languages, for more information on operators in supported
6796 If you are not interested in seeing the value of the assignment, use
6797 the 'set' command instead of the 'print' command. 'set' is really the
6798 same as 'print' except that the expression's value is not printed and is
6799 not put in the value history (*note Value History: Value History.). The
6800 expression is evaluated only for its effects.
6802 If the beginning of the argument string of the 'set' command appears
6803 identical to a 'set' subcommand, use the 'set variable' command instead
6804 of just 'set'. This command is identical to 'set' except for its lack
6805 of subcommands. For example, if your program has a variable 'width',
6806 you get an error if you try to set a new value with just 'set width=13',
6807 because GDB has the command 'set width':
6814 Invalid syntax in expression.
6816 The invalid expression, of course, is '=47'. In order to actually set
6817 the program's variable 'width', use
6819 (gdb) set var width=47
6821 Because the 'set' command has many subcommands that can conflict with
6822 the names of program variables, it is a good idea to use the 'set
6823 variable' command instead of just 'set'. For example, if your program
6824 has a variable 'g', you run into problems if you try to set a new value
6825 with just 'set g=4', because GDB has the command 'set gnutarget',
6826 abbreviated 'set g':
6836 The program being debugged has been started already.
6837 Start it from the beginning? (y or n) y
6838 Starting program: /home/smith/cc_progs/a.out
6839 "/home/smith/cc_progs/a.out": can't open to read symbols:
6842 The current BFD target is "=4".
6844 The program variable 'g' did not change, and you silently set the
6845 'gnutarget' to an invalid value. In order to set the variable 'g', use
6849 GDB allows more implicit conversions in assignments than C; you can
6850 freely store an integer value into a pointer variable or vice versa, and
6851 you can convert any structure to any other structure that is the same
6854 To store values into arbitrary places in memory, use the '{...}'
6855 construct to generate a value of specified type at a specified address
6856 (*note Expressions: Expressions.). For example, '{int}0x83040' refers
6857 to memory location '0x83040' as an integer (which implies a certain size
6858 and representation in memory), and
6860 set {int}0x83040 = 4
6862 stores the value 4 into that memory location.
6865 File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering
6867 17.2 Continuing at a Different Address
6868 ======================================
6870 Ordinarily, when you continue your program, you do so at the place where
6871 it stopped, with the 'continue' command. You can instead continue at an
6872 address of your own choosing, with the following commands:
6878 Resume execution at line LINESPEC or at address given by LOCATION.
6879 Execution stops again immediately if there is a breakpoint there.
6880 *Note Specify Location::, for a description of the different forms
6881 of LINESPEC and LOCATION. It is common practice to use the
6882 'tbreak' command in conjunction with 'jump'. *Note Setting
6883 Breakpoints: Set Breaks.
6885 The 'jump' command does not change the current stack frame, or the
6886 stack pointer, or the contents of any memory location or any
6887 register other than the program counter. If line LINESPEC is in a
6888 different function from the one currently executing, the results
6889 may be bizarre if the two functions expect different patterns of
6890 arguments or of local variables. For this reason, the 'jump'
6891 command requests confirmation if the specified line is not in the
6892 function currently executing. However, even bizarre results are
6893 predictable if you are well acquainted with the machine-language
6894 code of your program.
6896 On many systems, you can get much the same effect as the 'jump'
6897 command by storing a new value into the register '$pc'. The difference
6898 is that this does not start your program running; it only changes the
6899 address of where it _will_ run when you continue. For example,
6903 makes the next 'continue' command or stepping command execute at address
6904 '0x485', rather than at the address where your program stopped. *Note
6905 Continuing and Stepping: Continuing and Stepping.
6907 The most common occasion to use the 'jump' command is to back
6908 up--perhaps with more breakpoints set--over a portion of a program that
6909 has already executed, in order to examine its execution in more detail.
6912 File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering
6914 17.3 Giving your Program a Signal
6915 =================================
6918 Resume execution where your program stopped, but immediately give
6919 it the signal SIGNAL. SIGNAL can be the name or the number of a
6920 signal. For example, on many systems 'signal 2' and 'signal
6921 SIGINT' are both ways of sending an interrupt signal.
6923 Alternatively, if SIGNAL is zero, continue execution without giving
6924 a signal. This is useful when your program stopped on account of a
6925 signal and would ordinarily see the signal when resumed with the
6926 'continue' command; 'signal 0' causes it to resume without a
6929 'signal' does not repeat when you press <RET> a second time after
6930 executing the command.
6932 Invoking the 'signal' command is not the same as invoking the 'kill'
6933 utility from the shell. Sending a signal with 'kill' causes GDB to
6934 decide what to do with the signal depending on the signal handling
6935 tables (*note Signals::). The 'signal' command passes the signal
6936 directly to your program.
6939 File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering
6941 17.4 Returning from a Function
6942 ==============================
6946 You can cancel execution of a function call with the 'return'
6947 command. If you give an EXPRESSION argument, its value is used as
6948 the function's return value.
6950 When you use 'return', GDB discards the selected stack frame (and all
6951 frames within it). You can think of this as making the discarded frame
6952 return prematurely. If you wish to specify a value to be returned, give
6953 that value as the argument to 'return'.
6955 This pops the selected stack frame (*note Selecting a Frame:
6956 Selection.), and any other frames inside of it, leaving its caller as
6957 the innermost remaining frame. That frame becomes selected. The
6958 specified value is stored in the registers used for returning values of
6961 The 'return' command does not resume execution; it leaves the program
6962 stopped in the state that would exist if the function had just returned.
6963 In contrast, the 'finish' command (*note Continuing and Stepping:
6964 Continuing and Stepping.) resumes execution until the selected stack
6965 frame returns naturally.
6967 GDB needs to know how the EXPRESSION argument should be set for the
6968 inferior. The concrete registers assignment depends on the OS ABI and
6969 the type being returned by the selected stack frame. For example it is
6970 common for OS ABI to return floating point values in FPU registers while
6971 integer values in CPU registers. Still some ABIs return even floating
6972 point values in CPU registers. Larger integer widths (such as 'long
6973 long int') also have specific placement rules. GDB already knows the OS
6974 ABI from its current target so it needs to find out also the type being
6975 returned to make the assignment into the right register(s).
6977 Normally, the selected stack frame has debug info. GDB will always
6978 use the debug info instead of the implicit type of EXPRESSION when the
6979 debug info is available. For example, if you type 'return -1', and the
6980 function in the current stack frame is declared to return a 'long long
6981 int', GDB transparently converts the implicit 'int' value of -1 into a
6984 Breakpoint 1, func () at gdb.base/return-nodebug.c:29
6987 Make func return now? (y or n) y
6988 #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43
6989 43 printf ("result=%lld\n", func ());
6992 However, if the selected stack frame does not have a debug info,
6993 e.g., if the function was compiled without debug info, GDB has to find
6994 out the type to return from user. Specifying a different type by
6995 mistake may set the value in different inferior registers than the
6996 caller code expects. For example, typing 'return -1' with its implicit
6997 type 'int' would set only a part of a 'long long int' result for a debug
6998 info less function (on 32-bit architectures). Therefore the user is
6999 required to specify the return type by an appropriate cast explicitly:
7001 Breakpoint 2, 0x0040050b in func ()
7003 Return value type not available for selected stack frame.
7004 Please use an explicit cast of the value to return.
7005 (gdb) return (long long int) -1
7006 Make selected stack frame return now? (y or n) y
7007 #0 0x00400526 in main ()
7011 File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering
7013 17.5 Calling Program Functions
7014 ==============================
7017 Evaluate the expression EXPR and display the resulting value. EXPR
7018 may include calls to functions in the program being debugged.
7021 Evaluate the expression EXPR without displaying 'void' returned
7024 You can use this variant of the 'print' command if you want to
7025 execute a function from your program that does not return anything
7026 (a.k.a. "a void function"), but without cluttering the output with
7027 'void' returned values that GDB will otherwise print. If the
7028 result is not void, it is printed and saved in the value history.
7030 It is possible for the function you call via the 'print' or 'call'
7031 command to generate a signal (e.g., if there's a bug in the function, or
7032 if you passed it incorrect arguments). What happens in that case is
7033 controlled by the 'set unwindonsignal' command.
7035 Similarly, with a C++ program it is possible for the function you
7036 call via the 'print' or 'call' command to generate an exception that is
7037 not handled due to the constraints of the dummy frame. In this case,
7038 any exception that is raised in the frame, but has an out-of-frame
7039 exception handler will not be found. GDB builds a dummy-frame for the
7040 inferior function call, and the unwinder cannot seek for exception
7041 handlers outside of this dummy-frame. What happens in that case is
7042 controlled by the 'set unwind-on-terminating-exception' command.
7044 'set unwindonsignal'
7045 Set unwinding of the stack if a signal is received while in a
7046 function that GDB called in the program being debugged. If set to
7047 on, GDB unwinds the stack it created for the call and restores the
7048 context to what it was before the call. If set to off (the
7049 default), GDB stops in the frame where the signal was received.
7051 'show unwindonsignal'
7052 Show the current setting of stack unwinding in the functions called
7055 'set unwind-on-terminating-exception'
7056 Set unwinding of the stack if a C++ exception is raised, but left
7057 unhandled while in a function that GDB called in the program being
7058 debugged. If set to on (the default), GDB unwinds the stack it
7059 created for the call and restores the context to what it was before
7060 the call. If set to off, GDB the exception is delivered to the
7061 default C++ exception handler and the inferior terminated.
7063 'show unwind-on-terminating-exception'
7064 Show the current setting of stack unwinding in the functions called
7067 Sometimes, a function you wish to call is actually a "weak alias" for
7068 another function. In such case, GDB might not pick up the type
7069 information, including the types of the function arguments, which causes
7070 GDB to call the inferior function incorrectly. As a result, the called
7071 function will function erroneously and may even crash. A solution to
7072 that is to use the name of the aliased function instead.
7075 File: gdb.info, Node: Patching, Prev: Calling, Up: Altering
7077 17.6 Patching Programs
7078 ======================
7080 By default, GDB opens the file containing your program's executable code
7081 (or the corefile) read-only. This prevents accidental alterations to
7082 machine code; but it also prevents you from intentionally patching your
7085 If you'd like to be able to patch the binary, you can specify that
7086 explicitly with the 'set write' command. For example, you might want to
7087 turn on internal debugging flags, or even to make emergency repairs.
7091 If you specify 'set write on', GDB opens executable and core files
7092 for both reading and writing; if you specify 'set write off' (the
7093 default), GDB opens them read-only.
7095 If you have already loaded a file, you must load it again (using
7096 the 'exec-file' or 'core-file' command) after changing 'set write',
7097 for your new setting to take effect.
7100 Display whether executable files and core files are opened for
7101 writing as well as reading.
7104 File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top
7109 GDB needs to know the file name of the program to be debugged, both in
7110 order to read its symbol table and in order to start your program. To
7111 debug a core dump of a previous run, you must also tell GDB the name of
7116 * Files:: Commands to specify files
7117 * Separate Debug Files:: Debugging information in separate files
7118 * MiniDebugInfo:: Debugging information in a special section
7119 * Index Files:: Index files speed up GDB
7120 * Symbol Errors:: Errors reading symbol files
7121 * Data Files:: GDB data files
7124 File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files
7126 18.1 Commands to Specify Files
7127 ==============================
7129 You may want to specify executable and core dump file names. The usual
7130 way to do this is at start-up time, using the arguments to GDB's
7131 start-up commands (*note Getting In and Out of GDB: Invocation.).
7133 Occasionally it is necessary to change to a different file during a
7134 GDB session. Or you may run GDB and forget to specify a file you want
7135 to use. Or you are debugging a remote target via 'gdbserver' (*note
7136 file: Server.). In these situations the GDB commands to specify new
7140 Use FILENAME as the program to be debugged. It is read for its
7141 symbols and for the contents of pure memory. It is also the
7142 program executed when you use the 'run' command. If you do not
7143 specify a directory and the file is not found in the GDB working
7144 directory, GDB uses the environment variable 'PATH' as a list of
7145 directories to search, just as the shell does when looking for a
7146 program to run. You can change the value of this variable, for
7147 both GDB and your program, using the 'path' command.
7149 You can load unlinked object '.o' files into GDB using the 'file'
7150 command. You will not be able to "run" an object file, but you can
7151 disassemble functions and inspect variables. Also, if the
7152 underlying BFD functionality supports it, you could use 'gdb
7153 -write' to patch object files using this technique. Note that GDB
7154 can neither interpret nor modify relocations in this case, so
7155 branches and some initialized variables will appear to go to the
7156 wrong place. But this feature is still handy from time to time.
7159 'file' with no argument makes GDB discard any information it has on
7160 both executable file and the symbol table.
7162 'exec-file [ FILENAME ]'
7163 Specify that the program to be run (but not the symbol table) is
7164 found in FILENAME. GDB searches the environment variable 'PATH' if
7165 necessary to locate your program. Omitting FILENAME means to
7166 discard information on the executable file.
7168 'symbol-file [ FILENAME ]'
7169 Read symbol table information from file FILENAME. 'PATH' is
7170 searched when necessary. Use the 'file' command to get both symbol
7171 table and program to run from the same file.
7173 'symbol-file' with no argument clears out GDB information on your
7174 program's symbol table.
7176 The 'symbol-file' command causes GDB to forget the contents of some
7177 breakpoints and auto-display expressions. This is because they may
7178 contain pointers to the internal data recording symbols and data
7179 types, which are part of the old symbol table data being discarded
7182 'symbol-file' does not repeat if you press <RET> again after
7185 When GDB is configured for a particular environment, it understands
7186 debugging information in whatever format is the standard generated
7187 for that environment; you may use either a GNU compiler, or other
7188 compilers that adhere to the local conventions. Best results are
7189 usually obtained from GNU compilers; for example, using 'GCC' you
7190 can generate debugging information for optimized code.
7192 For most kinds of object files, with the exception of old SVR3
7193 systems using COFF, the 'symbol-file' command does not normally
7194 read the symbol table in full right away. Instead, it scans the
7195 symbol table quickly to find which source files and which symbols
7196 are present. The details are read later, one source file at a
7197 time, as they are needed.
7199 The purpose of this two-stage reading strategy is to make GDB start
7200 up faster. For the most part, it is invisible except for
7201 occasional pauses while the symbol table details for a particular
7202 source file are being read. (The 'set verbose' command can turn
7203 these pauses into messages if desired. *Note Optional Warnings and
7204 Messages: Messages/Warnings.)
7206 We have not implemented the two-stage strategy for COFF yet. When
7207 the symbol table is stored in COFF format, 'symbol-file' reads the
7208 symbol table data in full right away. Note that "stabs-in-COFF"
7209 still does the two-stage strategy, since the debug info is actually
7212 'symbol-file [ -readnow ] FILENAME'
7213 'file [ -readnow ] FILENAME'
7214 You can override the GDB two-stage strategy for reading symbol
7215 tables by using the '-readnow' option with any of the commands that
7216 load symbol table information, if you want to be sure GDB has the
7217 entire symbol table available.
7219 'core-file [FILENAME]'
7221 Specify the whereabouts of a core dump file to be used as the
7222 "contents of memory". Traditionally, core files contain only some
7223 parts of the address space of the process that generated them; GDB
7224 can access the executable file itself for other parts.
7226 'core-file' with no argument specifies that no core file is to be
7229 Note that the core file is ignored when your program is actually
7230 running under GDB. So, if you have been running your program and
7231 you wish to debug a core file instead, you must kill the subprocess
7232 in which the program is running. To do this, use the 'kill'
7233 command (*note Killing the Child Process: Kill Process.).
7235 'add-symbol-file FILENAME ADDRESS'
7236 'add-symbol-file FILENAME ADDRESS [ -readnow ]'
7237 'add-symbol-file FILENAME ADDRESS -s SECTION ADDRESS ...'
7238 The 'add-symbol-file' command reads additional symbol table
7239 information from the file FILENAME. You would use this command
7240 when FILENAME has been dynamically loaded (by some other means)
7241 into the program that is running. ADDRESS should be the memory
7242 address at which the file has been loaded; GDB cannot figure this
7243 out for itself. You can additionally specify an arbitrary number
7244 of '-s SECTION ADDRESS' pairs, to give an explicit section name and
7245 base address for that section. You can specify any ADDRESS as an
7248 The symbol table of the file FILENAME is added to the symbol table
7249 originally read with the 'symbol-file' command. You can use the
7250 'add-symbol-file' command any number of times; the new symbol data
7251 thus read is kept in addition to the old.
7253 Changes can be reverted using the command 'remove-symbol-file'.
7255 Although FILENAME is typically a shared library file, an executable
7256 file, or some other object file which has been fully relocated for
7257 loading into a process, you can also load symbolic information from
7258 relocatable '.o' files, as long as:
7260 * the file's symbolic information refers only to linker symbols
7261 defined in that file, not to symbols defined by other object
7263 * every section the file's symbolic information refers to has
7264 actually been loaded into the inferior, as it appears in the
7266 * you can determine the address at which every section was
7267 loaded, and provide these to the 'add-symbol-file' command.
7269 Some embedded operating systems, like Sun Chorus and VxWorks, can
7270 load relocatable files into an already running program; such
7271 systems typically make the requirements above easy to meet.
7272 However, it's important to recognize that many native systems use
7273 complex link procedures ('.linkonce' section factoring and C++
7274 constructor table assembly, for example) that make the requirements
7275 difficult to meet. In general, one cannot assume that using
7276 'add-symbol-file' to read a relocatable object file's symbolic
7277 information will have the same effect as linking the relocatable
7278 object file into the program in the normal way.
7280 'add-symbol-file' does not repeat if you press <RET> after using
7283 'remove-symbol-file FILENAME'
7284 'remove-symbol-file -a ADDRESS'
7285 Remove a symbol file added via the 'add-symbol-file' command. The
7286 file to remove can be identified by its FILENAME or by an ADDRESS
7287 that lies within the boundaries of this symbol file in memory.
7290 (gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
7291 add symbol table from file "/home/user/gdb/mylib.so" at
7292 .text_addr = 0x7ffff7ff9480
7294 Reading symbols from /home/user/gdb/mylib.so...done.
7295 (gdb) remove-symbol-file -a 0x7ffff7ff9480
7296 Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
7299 'remove-symbol-file' does not repeat if you press <RET> after using
7302 'add-symbol-file-from-memory ADDRESS'
7303 Load symbols from the given ADDRESS in a dynamically loaded object
7304 file whose image is mapped directly into the inferior's memory.
7305 For example, the Linux kernel maps a 'syscall DSO' into each
7306 process's address space; this DSO provides kernel-specific code for
7307 some system calls. The argument can be any expression whose
7308 evaluation yields the address of the file's shared object file
7309 header. For this command to work, you must have used 'symbol-file'
7310 or 'exec-file' commands in advance.
7312 'add-shared-symbol-files LIBRARY-FILE'
7314 The 'add-shared-symbol-files' command can currently be used only in
7315 the Cygwin build of GDB on MS-Windows OS, where it is an alias for
7316 the 'dll-symbols' command (*note Cygwin Native::). GDB
7317 automatically looks for shared libraries, however if GDB does not
7318 find yours, you can invoke 'add-shared-symbol-files'. It takes one
7319 argument: the shared library's file name. 'assf' is a shorthand
7320 alias for 'add-shared-symbol-files'.
7322 'section SECTION ADDR'
7323 The 'section' command changes the base address of the named SECTION
7324 of the exec file to ADDR. This can be used if the exec file does
7325 not contain section addresses, (such as in the 'a.out' format), or
7326 when the addresses specified in the file itself are wrong. Each
7327 section must be changed separately. The 'info files' command,
7328 described below, lists all the sections and their addresses.
7332 'info files' and 'info target' are synonymous; both print the
7333 current target (*note Specifying a Debugging Target: Targets.),
7334 including the names of the executable and core dump files currently
7335 in use by GDB, and the files from which symbols were loaded. The
7336 command 'help target' lists all possible targets rather than
7339 'maint info sections'
7340 Another command that can give you extra information about program
7341 sections is 'maint info sections'. In addition to the section
7342 information displayed by 'info files', this command displays the
7343 flags and file offset of each section in the executable and core
7344 dump files. In addition, 'maint info sections' provides the
7345 following command options (which may be arbitrarily combined):
7348 Display sections for all loaded object files, including shared
7351 Display info only for named SECTIONS.
7353 Display info only for sections for which SECTION-FLAGS are
7354 true. The section flags that GDB currently knows about are:
7356 Section will have space allocated in the process when
7357 loaded. Set for all sections except those containing
7360 Section will be loaded from the file into the child
7361 process memory. Set for pre-initialized code and data,
7362 clear for '.bss' sections.
7364 Section needs to be relocated before loading.
7366 Section cannot be modified by the child process.
7368 Section contains executable code only.
7370 Section contains data only (no executable code).
7372 Section will reside in ROM.
7374 Section contains data for constructor/destructor lists.
7376 Section is not empty.
7378 An instruction to the linker to not output the section.
7379 'COFF_SHARED_LIBRARY'
7380 A notification to the linker that the section contains
7381 COFF shared library information.
7383 Section contains common symbols.
7384 'set trust-readonly-sections on'
7385 Tell GDB that readonly sections in your object file really are
7386 read-only (i.e. that their contents will not change). In that
7387 case, GDB can fetch values from these sections out of the object
7388 file, rather than from the target program. For some targets
7389 (notably embedded ones), this can be a significant enhancement to
7390 debugging performance.
7394 'set trust-readonly-sections off'
7395 Tell GDB not to trust readonly sections. This means that the
7396 contents of the section might change while the program is running,
7397 and must therefore be fetched from the target when needed.
7399 'show trust-readonly-sections'
7400 Show the current setting of trusting readonly sections.
7402 All file-specifying commands allow both absolute and relative file
7403 names as arguments. GDB always converts the file name to an absolute
7404 file name and remembers it that way.
7406 GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and IBM
7407 RS/6000 AIX shared libraries.
7409 On MS-Windows GDB must be linked with the Expat library to support
7410 shared libraries. *Note Expat::.
7412 GDB automatically loads symbol definitions from shared libraries when
7413 you use the 'run' command, or when you examine a core file. (Before you
7414 issue the 'run' command, GDB does not understand references to a
7415 function in a shared library, however--unless you are debugging a core
7418 On HP-UX, if the program loads a library explicitly, GDB
7419 automatically loads the symbols at the time of the 'shl_load' call.
7421 There are times, however, when you may wish to not automatically load
7422 symbol definitions from shared libraries, such as when they are
7423 particularly large or there are many of them.
7425 To control the automatic loading of shared library symbols, use the
7428 'set auto-solib-add MODE'
7429 If MODE is 'on', symbols from all shared object libraries will be
7430 loaded automatically when the inferior begins execution, you attach
7431 to an independently started inferior, or when the dynamic linker
7432 informs GDB that a new library has been loaded. If MODE is 'off',
7433 symbols must be loaded manually, using the 'sharedlibrary' command.
7434 The default value is 'on'.
7436 If your program uses lots of shared libraries with debug info that
7437 takes large amounts of memory, you can decrease the GDB memory
7438 footprint by preventing it from automatically loading the symbols
7439 from shared libraries. To that end, type 'set auto-solib-add off'
7440 before running the inferior, then load each library whose debug
7441 symbols you do need with 'sharedlibrary REGEXP', where REGEXP is a
7442 regular expression that matches the libraries whose symbols you
7445 'show auto-solib-add'
7446 Display the current autoloading mode.
7448 To explicitly load shared library symbols, use the 'sharedlibrary'
7452 'info sharedlibrary REGEX'
7453 Print the names of the shared libraries which are currently loaded
7454 that match REGEX. If REGEX is omitted then print all shared
7455 libraries that are loaded.
7457 'sharedlibrary REGEX'
7459 Load shared object library symbols for files matching a Unix
7460 regular expression. As with files loaded automatically, it only
7461 loads shared libraries required by your program for a core file or
7462 after typing 'run'. If REGEX is omitted all shared libraries
7463 required by your program are loaded.
7466 Unload all shared object library symbols. This discards all
7467 symbols that have been loaded from all shared libraries. Symbols
7468 from shared libraries that were loaded by explicit user requests
7471 Sometimes you may wish that GDB stops and gives you control when any
7472 of shared library events happen. The best way to do this is to use
7473 'catch load' and 'catch unload' (*note Set Catchpoints::).
7475 GDB also supports the the 'set stop-on-solib-events' command for
7476 this. This command exists for historical reasons. It is less useful
7477 than setting a catchpoint, because it does not allow for conditions or
7478 commands as a catchpoint does.
7480 'set stop-on-solib-events'
7481 This command controls whether GDB should give you control when the
7482 dynamic linker notifies it about some shared library event. The
7483 most common event of interest is loading or unloading of a new
7486 'show stop-on-solib-events'
7487 Show whether GDB stops and gives you control when shared library
7490 Shared libraries are also supported in many cross or remote debugging
7491 configurations. GDB needs to have access to the target's libraries;
7492 this can be accomplished either by providing copies of the libraries on
7493 the host system, or by asking GDB to automatically retrieve the
7494 libraries from the target. If copies of the target libraries are
7495 provided, they need to be the same as the target libraries, although the
7496 copies on the target can be stripped as long as the copies on the host
7499 For remote debugging, you need to tell GDB where the target libraries
7500 are, so that it can load the correct copies--otherwise, it may try to
7501 load the host's libraries. GDB has two variables to specify the search
7502 directories for target libraries.
7505 Use PATH as the system root for the program being debugged. Any
7506 absolute shared library paths will be prefixed with PATH; many
7507 runtime loaders store the absolute paths to the shared library in
7508 the target program's memory. If you use 'set sysroot' to find
7509 shared libraries, they need to be laid out in the same way that
7510 they are on the target, with e.g. a '/lib' and '/usr/lib' hierarchy
7513 If PATH starts with the sequence 'remote:', GDB will retrieve the
7514 target libraries from the remote system. This is only supported
7515 when using a remote target that supports the 'remote get' command
7516 (*note Sending files to a remote system: File Transfer.). The part
7517 of PATH following the initial 'remote:' (if present) is used as
7518 system root prefix on the remote file system. (1)
7520 For targets with an MS-DOS based filesystem, such as MS-Windows and
7521 SymbianOS, GDB tries prefixing a few variants of the target
7522 absolute file name with PATH. But first, on Unix hosts, GDB
7523 converts all backslash directory separators into forward slashes,
7524 because the backslash is not a directory separator on Unix:
7526 c:\foo\bar.dll => c:/foo/bar.dll
7528 Then, GDB attempts prefixing the target file name with PATH, and
7529 looks for the resulting file name in the host file system:
7531 c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll
7533 If that does not find the shared library, GDB tries removing the
7534 ':' character from the drive spec, both for convenience, and, for
7535 the case of the host file system not supporting file names with
7538 c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll
7540 This makes it possible to have a system root that mirrors a target
7541 with more than one drive. E.g., you may want to setup your local
7542 copies of the target system shared libraries like so (note 'c' vs
7545 /path/to/sysroot/c/sys/bin/foo.dll
7546 /path/to/sysroot/c/sys/bin/bar.dll
7547 /path/to/sysroot/z/sys/bin/bar.dll
7549 and point the system root at '/path/to/sysroot', so that GDB can
7550 find the correct copies of both 'c:\sys\bin\foo.dll', and
7551 'z:\sys\bin\bar.dll'.
7553 If that still does not find the shared library, GDB tries removing
7554 the whole drive spec from the target file name:
7556 c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll
7558 This last lookup makes it possible to not care about the drive
7559 name, if you don't want or need to.
7561 The 'set solib-absolute-prefix' command is an alias for 'set
7564 You can set the default system root by using the configure-time
7565 '--with-sysroot' option. If the system root is inside GDB's
7566 configured binary prefix (set with '--prefix' or '--exec-prefix'),
7567 then the default system root will be updated automatically if the
7568 installed GDB is moved to a new location.
7571 Display the current shared library prefix.
7573 'set solib-search-path PATH'
7574 If this variable is set, PATH is a colon-separated list of
7575 directories to search for shared libraries. 'solib-search-path' is
7576 used after 'sysroot' fails to locate the library, or if the path to
7577 the library is relative instead of absolute. If you want to use
7578 'solib-search-path' instead of 'sysroot', be sure to set 'sysroot'
7579 to a nonexistent directory to prevent GDB from finding your host's
7580 libraries. 'sysroot' is preferred; setting it to a nonexistent
7581 directory may interfere with automatic loading of shared library
7584 'show solib-search-path'
7585 Display the current shared library search path.
7587 'set target-file-system-kind KIND'
7588 Set assumed file system kind for target reported file names.
7590 Shared library file names as reported by the target system may not
7591 make sense as is on the system GDB is running on. For example,
7592 when remote debugging a target that has MS-DOS based file system
7593 semantics, from a Unix host, the target may be reporting to GDB a
7594 list of loaded shared libraries with file names such as
7595 'c:\Windows\kernel32.dll'. On Unix hosts, there's no concept of
7596 drive letters, so the 'c:\' prefix is not normally understood as
7597 indicating an absolute file name, and neither is the backslash
7598 normally considered a directory separator character. In that case,
7599 the native file system would interpret this whole absolute file
7600 name as a relative file name with no directory components. This
7601 would make it impossible to point GDB at a copy of the remote
7602 target's shared libraries on the host using 'set sysroot', and
7603 impractical with 'set solib-search-path'. Setting
7604 'target-file-system-kind' to 'dos-based' tells GDB to interpret
7605 such file names similarly to how the target would, and to map them
7606 to file names valid on GDB's native file system semantics. The
7607 value of KIND can be '"auto"', in addition to one of the supported
7608 file system kinds. In that case, GDB tries to determine the
7609 appropriate file system variant based on the current target's
7610 operating system (*note Configuring the Current ABI: ABI.). The
7611 supported file system settings are:
7614 Instruct GDB to assume the target file system is of Unix kind.
7615 Only file names starting the forward slash ('/') character are
7616 considered absolute, and the directory separator character is
7617 also the forward slash.
7620 Instruct GDB to assume the target file system is DOS based.
7621 File names starting with either a forward slash, or a drive
7622 letter followed by a colon (e.g., 'c:'), are considered
7623 absolute, and both the slash ('/') and the backslash ('\\')
7624 characters are considered directory separators.
7627 Instruct GDB to use the file system kind associated with the
7628 target operating system (*note Configuring the Current ABI:
7629 ABI.). This is the default.
7631 When processing file names provided by the user, GDB frequently needs
7632 to compare them to the file names recorded in the program's debug info.
7633 Normally, GDB compares just the "base names" of the files as strings,
7634 which is reasonably fast even for very large programs. (The base name
7635 of a file is the last portion of its name, after stripping all the
7636 leading directories.) This shortcut in comparison is based upon the
7637 assumption that files cannot have more than one base name. This is
7638 usually true, but references to files that use symlinks or similar
7639 filesystem facilities violate that assumption. If your program records
7640 files using such facilities, or if you provide file names to GDB using
7641 symlinks etc., you can set 'basenames-may-differ' to 'true' to instruct
7642 GDB to completely canonicalize each pair of file names it needs to
7643 compare. This will make file-name comparisons accurate, but at a price
7644 of a significant slowdown.
7646 'set basenames-may-differ'
7647 Set whether a source file may have multiple base names.
7649 'show basenames-may-differ'
7650 Show whether a source file may have multiple base names.
7652 ---------- Footnotes ----------
7654 (1) If you want to specify a local system root using a directory that
7655 happens to be named 'remote:', you need to use some equivalent variant
7656 of the name like './remote:'.