| This is gdb.info, produced by makeinfo version 5.2 from gdb.texinfo. |
| |
| Copyright (C) 1988-2015 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| * gdbserver: (gdb) Server. The GNU debugging server. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU debugger GDB. |
| |
| This is the Tenth Edition, of 'Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB (GDB) Version 7.10. |
| |
| Copyright (C) 1988-2015 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| |
| File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data |
| |
| 10.1 Expressions |
| ================ |
| |
| 'print' and many other GDB commands accept an expression and compute its |
| value. Any kind of constant, variable or operator defined by the |
| programming language you are using is valid in an expression in GDB. |
| This includes conditional expressions, function calls, casts, and string |
| constants. It also includes preprocessor macros, if you compiled your |
| program to include this information; see *note Compilation::. |
| |
| GDB supports array constants in expressions input by the user. The |
| syntax is {ELEMENT, ELEMENT...}. For example, you can use the command |
| 'print {1, 2, 3}' to create an array of three integers. If you pass an |
| array to a function or assign it to a program variable, GDB copies the |
| array to memory that is 'malloc'ed in the target program. |
| |
| Because C is so widespread, most of the expressions shown in examples |
| in this manual are in C. *Note Using GDB with Different Languages: |
| Languages, for information on how to use expressions in other languages. |
| |
| In this section, we discuss operators that you can use in GDB |
| expressions regardless of your programming language. |
| |
| Casts are supported in all languages, not just in C, because it is so |
| useful to cast a number into a pointer in order to examine a structure |
| at that address in memory. |
| |
| GDB supports these operators, in addition to those common to |
| programming languages: |
| |
| '@' |
| '@' is a binary operator for treating parts of memory as arrays. |
| *Note Artificial Arrays: Arrays, for more information. |
| |
| '::' |
| '::' allows you to specify a variable in terms of the file or |
| function where it is defined. *Note Program Variables: Variables. |
| |
| '{TYPE} ADDR' |
| Refers to an object of type TYPE stored at address ADDR in memory. |
| The address ADDR may be any expression whose value is an integer or |
| pointer (but parentheses are required around binary operators, just |
| as in a cast). This construct is allowed regardless of what kind |
| of data is normally supposed to reside at ADDR. |
| |
| |
| File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data |
| |
| 10.2 Ambiguous Expressions |
| ========================== |
| |
| Expressions can sometimes contain some ambiguous elements. For |
| instance, some programming languages (notably Ada, C++ and Objective-C) |
| permit a single function name to be defined several times, for |
| application in different contexts. This is called "overloading". |
| Another example involving Ada is generics. A "generic package" is |
| similar to C++ templates and is typically instantiated several times, |
| resulting in the same function name being defined in different contexts. |
| |
| In some cases and depending on the language, it is possible to adjust |
| the expression to remove the ambiguity. For instance in C++, you can |
| specify the signature of the function you want to break on, as in 'break |
| FUNCTION(TYPES)'. In Ada, using the fully qualified name of your |
| function often makes the expression unambiguous as well. |
| |
| When an ambiguity that needs to be resolved is detected, the debugger |
| has the capability to display a menu of numbered choices for each |
| possibility, and then waits for the selection with the prompt '>'. The |
| first option is always '[0] cancel', and typing '0 <RET>' aborts the |
| current command. If the command in which the expression was used allows |
| more than one choice to be selected, the next option in the menu is '[1] |
| all', and typing '1 <RET>' selects all possible choices. |
| |
| For example, the following session excerpt shows an attempt to set a |
| breakpoint at the overloaded symbol 'String::after'. We choose three |
| particular definitions of that function name: |
| |
| (gdb) b String::after |
| [0] cancel |
| [1] all |
| [2] file:String.cc; line number:867 |
| [3] file:String.cc; line number:860 |
| [4] file:String.cc; line number:875 |
| [5] file:String.cc; line number:853 |
| [6] file:String.cc; line number:846 |
| [7] file:String.cc; line number:735 |
| > 2 4 6 |
| Breakpoint 1 at 0xb26c: file String.cc, line 867. |
| Breakpoint 2 at 0xb344: file String.cc, line 875. |
| Breakpoint 3 at 0xafcc: file String.cc, line 846. |
| Multiple breakpoints were set. |
| Use the "delete" command to delete unwanted |
| breakpoints. |
| (gdb) |
| |
| 'set multiple-symbols MODE' |
| |
| This option allows you to adjust the debugger behavior when an |
| expression is ambiguous. |
| |
| By default, MODE is set to 'all'. If the command with which the |
| expression is used allows more than one choice, then GDB |
| automatically selects all possible choices. For instance, |
| inserting a breakpoint on a function using an ambiguous name |
| results in a breakpoint inserted on each possible match. However, |
| if a unique choice must be made, then GDB uses the menu to help you |
| disambiguate the expression. For instance, printing the address of |
| an overloaded function will result in the use of the menu. |
| |
| When MODE is set to 'ask', the debugger always uses the menu when |
| an ambiguity is detected. |
| |
| Finally, when MODE is set to 'cancel', the debugger reports an |
| error due to the ambiguity and the command is aborted. |
| |
| 'show multiple-symbols' |
| Show the current value of the 'multiple-symbols' setting. |
| |
| |
| File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data |
| |
| 10.3 Program Variables |
| ====================== |
| |
| The most common kind of expression to use is the name of a variable in |
| your program. |
| |
| Variables in expressions are understood in the selected stack frame |
| (*note Selecting a Frame: Selection.); they must be either: |
| |
| * global (or file-static) |
| |
| or |
| |
| * visible according to the scope rules of the programming language |
| from the point of execution in that frame |
| |
| This means that in the function |
| |
| foo (a) |
| int a; |
| { |
| bar (a); |
| { |
| int b = test (); |
| bar (b); |
| } |
| } |
| |
| you can examine and use the variable 'a' whenever your program is |
| executing within the function 'foo', but you can only use or examine the |
| variable 'b' while your program is executing inside the block where 'b' |
| is declared. |
| |
| There is an exception: you can refer to a variable or function whose |
| scope is a single source file even if the current execution point is not |
| in this file. But it is possible to have more than one such variable or |
| function with the same name (in different source files). If that |
| happens, referring to that name has unpredictable effects. If you wish, |
| you can specify a static variable in a particular function or file by |
| using the colon-colon ('::') notation: |
| |
| FILE::VARIABLE |
| FUNCTION::VARIABLE |
| |
| Here FILE or FUNCTION is the name of the context for the static |
| VARIABLE. In the case of file names, you can use quotes to make sure |
| GDB parses the file name as a single word--for example, to print a |
| global value of 'x' defined in 'f2.c': |
| |
| (gdb) p 'f2.c'::x |
| |
| The '::' notation is normally used for referring to static variables, |
| since you typically disambiguate uses of local variables in functions by |
| selecting the appropriate frame and using the simple name of the |
| variable. However, you may also use this notation to refer to local |
| variables in frames enclosing the selected frame: |
| |
| void |
| foo (int a) |
| { |
| if (a < 10) |
| bar (a); |
| else |
| process (a); /* Stop here */ |
| } |
| |
| int |
| bar (int a) |
| { |
| foo (a + 5); |
| } |
| |
| For example, if there is a breakpoint at the commented line, here is |
| what you might see when the program stops after executing the call |
| 'bar(0)': |
| |
| (gdb) p a |
| $1 = 10 |
| (gdb) p bar::a |
| $2 = 5 |
| (gdb) up 2 |
| #2 0x080483d0 in foo (a=5) at foobar.c:12 |
| (gdb) p a |
| $3 = 5 |
| (gdb) p bar::a |
| $4 = 0 |
| |
| These uses of '::' are very rarely in conflict with the very similar |
| use of the same notation in C++. When they are in conflict, the C++ |
| meaning takes precedence; however, this can be overridden by quoting the |
| file or function name with single quotes. |
| |
| For example, suppose the program is stopped in a method of a class |
| that has a field named 'includefile', and there is also an include file |
| named 'includefile' that defines a variable, 'some_global'. |
| |
| (gdb) p includefile |
| $1 = 23 |
| (gdb) p includefile::some_global |
| A syntax error in expression, near `'. |
| (gdb) p 'includefile'::some_global |
| $2 = 27 |
| |
| _Warning:_ Occasionally, a local variable may appear to have the |
| wrong value at certain points in a function--just after entry to a |
| new scope, and just before exit. |
| You may see this problem when you are stepping by machine |
| instructions. This is because, on most machines, it takes more than one |
| instruction to set up a stack frame (including local variable |
| definitions); if you are stepping by machine instructions, variables may |
| appear to have the wrong values until the stack frame is completely |
| built. On exit, it usually also takes more than one machine instruction |
| to destroy a stack frame; after you begin stepping through that group of |
| instructions, local variable definitions may be gone. |
| |
| This may also happen when the compiler does significant |
| optimizations. To be sure of always seeing accurate values, turn off |
| all optimization when compiling. |
| |
| Another possible effect of compiler optimizations is to optimize |
| unused variables out of existence, or assign variables to registers (as |
| opposed to memory addresses). Depending on the support for such cases |
| offered by the debug info format used by the compiler, GDB might not be |
| able to display values for such local variables. If that happens, GDB |
| will print a message like this: |
| |
| No symbol "foo" in current context. |
| |
| To solve such problems, either recompile without optimizations, or |
| use a different debug info format, if the compiler supports several such |
| formats. *Note Compilation::, for more information on choosing compiler |
| options. *Note C and C++: C, for more information about debug info |
| formats that are best suited to C++ programs. |
| |
| If you ask to print an object whose contents are unknown to GDB, |
| e.g., because its data type is not completely specified by the debug |
| information, GDB will say '<incomplete type>'. *Note incomplete type: |
| Symbols, for more about this. |
| |
| If you append '@entry' string to a function parameter name you get |
| its value at the time the function got called. If the value is not |
| available an error message is printed. Entry values are available only |
| with some compilers. Entry values are normally also printed at the |
| function parameter list according to *note set print entry-values::. |
| |
| Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29 |
| 29 i++; |
| (gdb) next |
| 30 e (i); |
| (gdb) print i |
| $1 = 31 |
| (gdb) print i@entry |
| $2 = 30 |
| |
| Strings are identified as arrays of 'char' values without specified |
| signedness. Arrays of either 'signed char' or 'unsigned char' get |
| printed as arrays of 1 byte sized integers. '-fsigned-char' or |
| '-funsigned-char' GCC options have no effect as GDB defines literal |
| string type '"char"' as 'char' without a sign. For program code |
| |
| char var0[] = "A"; |
| signed char var1[] = "A"; |
| |
| You get during debugging |
| (gdb) print var0 |
| $1 = "A" |
| (gdb) print var1 |
| $2 = {65 'A', 0 '\0'} |
| |
| |
| File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data |
| |
| 10.4 Artificial Arrays |
| ====================== |
| |
| It is often useful to print out several successive objects of the same |
| type in memory; a section of an array, or an array of dynamically |
| determined size for which only a pointer exists in the program. |
| |
| You can do this by referring to a contiguous span of memory as an |
| "artificial array", using the binary operator '@'. The left operand of |
| '@' should be the first element of the desired array and be an |
| individual object. The right operand should be the desired length of |
| the array. The result is an array value whose elements are all of the |
| type of the left argument. The first element is actually the left |
| argument; the second element comes from bytes of memory immediately |
| following those that hold the first element, and so on. Here is an |
| example. If a program says |
| |
| int *array = (int *) malloc (len * sizeof (int)); |
| |
| you can print the contents of 'array' with |
| |
| p *array@len |
| |
| The left operand of '@' must reside in memory. Array values made |
| with '@' in this way behave just like other arrays in terms of |
| subscripting, and are coerced to pointers when used in expressions. |
| Artificial arrays most often appear in expressions via the value history |
| (*note Value History: Value History.), after printing one out. |
| |
| Another way to create an artificial array is to use a cast. This |
| re-interprets a value as if it were an array. The value need not be in |
| memory: |
| (gdb) p/x (short[2])0x12345678 |
| $1 = {0x1234, 0x5678} |
| |
| As a convenience, if you leave the array length out (as in |
| '(TYPE[])VALUE') GDB calculates the size to fill the value (as |
| 'sizeof(VALUE)/sizeof(TYPE)': |
| (gdb) p/x (short[])0x12345678 |
| $2 = {0x1234, 0x5678} |
| |
| Sometimes the artificial array mechanism is not quite enough; in |
| moderately complex data structures, the elements of interest may not |
| actually be adjacent--for example, if you are interested in the values |
| of pointers in an array. One useful work-around in this situation is to |
| use a convenience variable (*note Convenience Variables: Convenience |
| Vars.) as a counter in an expression that prints the first interesting |
| value, and then repeat that expression via <RET>. For instance, suppose |
| you have an array 'dtab' of pointers to structures, and you are |
| interested in the values of a field 'fv' in each structure. Here is an |
| example of what you might type: |
| |
| set $i = 0 |
| p dtab[$i++]->fv |
| <RET> |
| <RET> |
| ... |
| |
| |
| File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data |
| |
| 10.5 Output Formats |
| =================== |
| |
| By default, GDB prints a value according to its data type. Sometimes |
| this is not what you want. For example, you might want to print a |
| number in hex, or a pointer in decimal. Or you might want to view data |
| in memory at a certain address as a character string or as an |
| instruction. To do these things, specify an "output format" when you |
| print a value. |
| |
| The simplest use of output formats is to say how to print a value |
| already computed. This is done by starting the arguments of the 'print' |
| command with a slash and a format letter. The format letters supported |
| are: |
| |
| 'x' |
| Regard the bits of the value as an integer, and print the integer |
| in hexadecimal. |
| |
| 'd' |
| Print as integer in signed decimal. |
| |
| 'u' |
| Print as integer in unsigned decimal. |
| |
| 'o' |
| Print as integer in octal. |
| |
| 't' |
| Print as integer in binary. The letter 't' stands for "two". (1) |
| |
| 'a' |
| Print as an address, both absolute in hexadecimal and as an offset |
| from the nearest preceding symbol. You can use this format used to |
| discover where (in what function) an unknown address is located: |
| |
| (gdb) p/a 0x54320 |
| $3 = 0x54320 <_initialize_vx+396> |
| |
| The command 'info symbol 0x54320' yields similar results. *Note |
| info symbol: Symbols. |
| |
| 'c' |
| Regard as an integer and print it as a character constant. This |
| prints both the numerical value and its character representation. |
| The character representation is replaced with the octal escape |
| '\nnn' for characters outside the 7-bit ASCII range. |
| |
| Without this format, GDB displays 'char', 'unsigned char', and 'signed char' |
| data as character constants. Single-byte members of vectors are |
| displayed as integer data. |
| |
| 'f' |
| Regard the bits of the value as a floating point number and print |
| using typical floating point syntax. |
| |
| 's' |
| Regard as a string, if possible. With this format, pointers to |
| single-byte data are displayed as null-terminated strings and |
| arrays of single-byte data are displayed as fixed-length strings. |
| Other values are displayed in their natural types. |
| |
| Without this format, GDB displays pointers to and arrays of 'char', |
| 'unsigned char', and 'signed char' as strings. Single-byte members |
| of a vector are displayed as an integer array. |
| |
| 'z' |
| Like 'x' formatting, the value is treated as an integer and printed |
| as hexadecimal, but leading zeros are printed to pad the value to |
| the size of the integer type. |
| |
| 'r' |
| Print using the 'raw' formatting. By default, GDB will use a |
| Python-based pretty-printer, if one is available (*note Pretty |
| Printing::). This typically results in a higher-level display of |
| the value's contents. The 'r' format bypasses any Python |
| pretty-printer which might exist. |
| |
| For example, to print the program counter in hex (*note Registers::), |
| type |
| |
| p/x $pc |
| |
| Note that no space is required before the slash; this is because command |
| names in GDB cannot contain a slash. |
| |
| To reprint the last value in the value history with a different |
| format, you can use the 'print' command with just a format and no |
| expression. For example, 'p/x' reprints the last value in hex. |
| |
| ---------- Footnotes ---------- |
| |
| (1) 'b' cannot be used because these format letters are also used |
| with the 'x' command, where 'b' stands for "byte"; see *note Examining |
| Memory: Memory. |
| |
| |
| File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data |
| |
| 10.6 Examining Memory |
| ===================== |
| |
| You can use the command 'x' (for "examine") to examine memory in any of |
| several formats, independently of your program's data types. |
| |
| 'x/NFU ADDR' |
| 'x ADDR' |
| 'x' |
| Use the 'x' command to examine memory. |
| |
| N, F, and U are all optional parameters that specify how much memory |
| to display and how to format it; ADDR is an expression giving the |
| address where you want to start displaying memory. If you use defaults |
| for NFU, you need not type the slash '/'. Several commands set |
| convenient defaults for ADDR. |
| |
| N, the repeat count |
| The repeat count is a decimal integer; the default is 1. It |
| specifies how much memory (counting by units U) to display. |
| |
| F, the display format |
| The display format is one of the formats used by 'print' ('x', 'd', |
| 'u', 'o', 't', 'a', 'c', 'f', 's'), and in addition 'i' (for |
| machine instructions). The default is 'x' (hexadecimal) initially. |
| The default changes each time you use either 'x' or 'print'. |
| |
| U, the unit size |
| The unit size is any of |
| |
| 'b' |
| Bytes. |
| 'h' |
| Halfwords (two bytes). |
| 'w' |
| Words (four bytes). This is the initial default. |
| 'g' |
| Giant words (eight bytes). |
| |
| Each time you specify a unit size with 'x', that size becomes the |
| default unit the next time you use 'x'. For the 'i' format, the |
| unit size is ignored and is normally not written. For the 's' |
| format, the unit size defaults to 'b', unless it is explicitly |
| given. Use 'x /hs' to display 16-bit char strings and 'x /ws' to |
| display 32-bit strings. The next use of 'x /s' will again display |
| 8-bit strings. Note that the results depend on the programming |
| language of the current compilation unit. If the language is C, |
| the 's' modifier will use the UTF-16 encoding while 'w' will use |
| UTF-32. The encoding is set by the programming language and cannot |
| be altered. |
| |
| ADDR, starting display address |
| ADDR is the address where you want GDB to begin displaying memory. |
| The expression need not have a pointer value (though it may); it is |
| always interpreted as an integer address of a byte of memory. |
| *Note Expressions: Expressions, for more information on |
| expressions. The default for ADDR is usually just after the last |
| address examined--but several other commands also set the default |
| address: 'info breakpoints' (to the address of the last breakpoint |
| listed), 'info line' (to the starting address of a line), and |
| 'print' (if you use it to display a value from memory). |
| |
| For example, 'x/3uh 0x54320' is a request to display three halfwords |
| ('h') of memory, formatted as unsigned decimal integers ('u'), starting |
| at address '0x54320'. 'x/4xw $sp' prints the four words ('w') of memory |
| above the stack pointer (here, '$sp'; *note Registers: Registers.) in |
| hexadecimal ('x'). |
| |
| Since the letters indicating unit sizes are all distinct from the |
| letters specifying output formats, you do not have to remember whether |
| unit size or format comes first; either order works. The output |
| specifications '4xw' and '4wx' mean exactly the same thing. (However, |
| the count N must come first; 'wx4' does not work.) |
| |
| Even though the unit size U is ignored for the formats 's' and 'i', |
| you might still want to use a count N; for example, '3i' specifies that |
| you want to see three machine instructions, including any operands. For |
| convenience, especially when used with the 'display' command, the 'i' |
| format also prints branch delay slot instructions, if any, beyond the |
| count specified, which immediately follow the last instruction that is |
| within the count. The command 'disassemble' gives an alternative way of |
| inspecting machine instructions; see *note Source and Machine Code: |
| Machine Code. |
| |
| All the defaults for the arguments to 'x' are designed to make it |
| easy to continue scanning memory with minimal specifications each time |
| you use 'x'. For example, after you have inspected three machine |
| instructions with 'x/3i ADDR', you can inspect the next seven with just |
| 'x/7'. If you use <RET> to repeat the 'x' command, the repeat count N |
| is used again; the other arguments default as for successive uses of |
| 'x'. |
| |
| When examining machine instructions, the instruction at current |
| program counter is shown with a '=>' marker. For example: |
| |
| (gdb) x/5i $pc-6 |
| 0x804837f <main+11>: mov %esp,%ebp |
| 0x8048381 <main+13>: push %ecx |
| 0x8048382 <main+14>: sub $0x4,%esp |
| => 0x8048385 <main+17>: movl $0x8048460,(%esp) |
| 0x804838c <main+24>: call 0x80482d4 <puts@plt> |
| |
| The addresses and contents printed by the 'x' command are not saved |
| in the value history because there is often too much of them and they |
| would get in the way. Instead, GDB makes these values available for |
| subsequent use in expressions as values of the convenience variables |
| '$_' and '$__'. After an 'x' command, the last address examined is |
| available for use in expressions in the convenience variable '$_'. The |
| contents of that address, as examined, are available in the convenience |
| variable '$__'. |
| |
| If the 'x' command has a repeat count, the address and contents saved |
| are from the last memory unit printed; this is not the same as the last |
| address printed if several units were printed on the last line of |
| output. |
| |
| Most targets have an addressable memory unit size of 8 bits. This |
| means that to each memory address are associated 8 bits of data. Some |
| targets, however, have other addressable memory unit sizes. Within GDB |
| and this document, the term "addressable memory unit" (or "memory unit" |
| for short) is used when explicitly referring to a chunk of data of that |
| size. The word "byte" is used to refer to a chunk of data of 8 bits, |
| regardless of the addressable memory unit size of the target. For most |
| systems, addressable memory unit is a synonym of byte. |
| |
| When you are debugging a program running on a remote target machine |
| (*note Remote Debugging::), you may wish to verify the program's image |
| in the remote machine's memory against the executable file you |
| downloaded to the target. Or, on any target, you may want to check |
| whether the program has corrupted its own read-only sections. The |
| 'compare-sections' command is provided for such situations. |
| |
| 'compare-sections [SECTION-NAME|-r]' |
| Compare the data of a loadable section SECTION-NAME in the |
| executable file of the program being debugged with the same section |
| in the target machine's memory, and report any mismatches. With no |
| arguments, compares all loadable sections. With an argument of |
| '-r', compares all loadable read-only sections. |
| |
| Note: for remote targets, this command can be accelerated if the |
| target supports computing the CRC checksum of a block of memory |
| (*note qCRC packet::). |
| |
| |
| File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data |
| |
| 10.7 Automatic Display |
| ====================== |
| |
| If you find that you want to print the value of an expression frequently |
| (to see how it changes), you might want to add it to the "automatic |
| display list" so that GDB prints its value each time your program stops. |
| Each expression added to the list is given a number to identify it; to |
| remove an expression from the list, you specify that number. The |
| automatic display looks like this: |
| |
| 2: foo = 38 |
| 3: bar[5] = (struct hack *) 0x3804 |
| |
| This display shows item numbers, expressions and their current values. |
| As with displays you request manually using 'x' or 'print', you can |
| specify the output format you prefer; in fact, 'display' decides whether |
| to use 'print' or 'x' depending your format specification--it uses 'x' |
| if you specify either the 'i' or 's' format, or a unit size; otherwise |
| it uses 'print'. |
| |
| 'display EXPR' |
| Add the expression EXPR to the list of expressions to display each |
| time your program stops. *Note Expressions: Expressions. |
| |
| 'display' does not repeat if you press <RET> again after using it. |
| |
| 'display/FMT EXPR' |
| For FMT specifying only a display format and not a size or count, |
| add the expression EXPR to the auto-display list but arrange to |
| display it each time in the specified format FMT. *Note Output |
| Formats: Output Formats. |
| |
| 'display/FMT ADDR' |
| For FMT 'i' or 's', or including a unit-size or a number of units, |
| add the expression ADDR as a memory address to be examined each |
| time your program stops. Examining means in effect doing 'x/FMT |
| ADDR'. *Note Examining Memory: Memory. |
| |
| For example, 'display/i $pc' can be helpful, to see the machine |
| instruction about to be executed each time execution stops ('$pc' is a |
| common name for the program counter; *note Registers: Registers.). |
| |
| 'undisplay DNUMS...' |
| 'delete display DNUMS...' |
| Remove items from the list of expressions to display. Specify the |
| numbers of the displays that you want affected with the command |
| argument DNUMS. It can be a single display number, one of the |
| numbers shown in the first field of the 'info display' display; or |
| it could be a range of display numbers, as in '2-4'. |
| |
| 'undisplay' does not repeat if you press <RET> after using it. |
| (Otherwise you would just get the error 'No display number ...'.) |
| |
| 'disable display DNUMS...' |
| Disable the display of item numbers DNUMS. A disabled display item |
| is not printed automatically, but is not forgotten. It may be |
| enabled again later. Specify the numbers of the displays that you |
| want affected with the command argument DNUMS. It can be a single |
| display number, one of the numbers shown in the first field of the |
| 'info display' display; or it could be a range of display numbers, |
| as in '2-4'. |
| |
| 'enable display DNUMS...' |
| Enable display of item numbers DNUMS. It becomes effective once |
| again in auto display of its expression, until you specify |
| otherwise. Specify the numbers of the displays that you want |
| affected with the command argument DNUMS. It can be a single |
| display number, one of the numbers shown in the first field of the |
| 'info display' display; or it could be a range of display numbers, |
| as in '2-4'. |
| |
| 'display' |
| Display the current values of the expressions on the list, just as |
| is done when your program stops. |
| |
| 'info display' |
| Print the list of expressions previously set up to display |
| automatically, each one with its item number, but without showing |
| the values. This includes disabled expressions, which are marked |
| as such. It also includes expressions which would not be displayed |
| right now because they refer to automatic variables not currently |
| available. |
| |
| If a display expression refers to local variables, then it does not |
| make sense outside the lexical context for which it was set up. Such an |
| expression is disabled when execution enters a context where one of its |
| variables is not defined. For example, if you give the command 'display |
| last_char' while inside a function with an argument 'last_char', GDB |
| displays this argument while your program continues to stop inside that |
| function. When it stops elsewhere--where there is no variable |
| 'last_char'--the display is disabled automatically. The next time your |
| program stops where 'last_char' is meaningful, you can enable the |
| display expression once again. |
| |
| |
| File: gdb.info, Node: Print Settings, Next: Pretty Printing, Prev: Auto Display, Up: Data |
| |
| 10.8 Print Settings |
| =================== |
| |
| GDB provides the following ways to control how arrays, structures, and |
| symbols are printed. |
| |
| These settings are useful for debugging programs in any language: |
| |
| 'set print address' |
| 'set print address on' |
| GDB prints memory addresses showing the location of stack traces, |
| structure values, pointer values, breakpoints, and so forth, even |
| when it also displays the contents of those addresses. The default |
| is 'on'. For example, this is what a stack frame display looks |
| like with 'set print address on': |
| |
| (gdb) f |
| #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") |
| at input.c:530 |
| 530 if (lquote != def_lquote) |
| |
| 'set print address off' |
| Do not print addresses when displaying their contents. For |
| example, this is the same stack frame displayed with 'set print |
| address off': |
| |
| (gdb) set print addr off |
| (gdb) f |
| #0 set_quotes (lq="<<", rq=">>") at input.c:530 |
| 530 if (lquote != def_lquote) |
| |
| You can use 'set print address off' to eliminate all machine |
| dependent displays from the GDB interface. For example, with |
| 'print address off', you should get the same text for backtraces on |
| all machines--whether or not they involve pointer arguments. |
| |
| 'show print address' |
| Show whether or not addresses are to be printed. |
| |
| When GDB prints a symbolic address, it normally prints the closest |
| earlier symbol plus an offset. If that symbol does not uniquely |
| identify the address (for example, it is a name whose scope is a single |
| source file), you may need to clarify. One way to do this is with 'info |
| line', for example 'info line *0x4537'. Alternately, you can set GDB to |
| print the source file and line number when it prints a symbolic address: |
| |
| 'set print symbol-filename on' |
| Tell GDB to print the source file name and line number of a symbol |
| in the symbolic form of an address. |
| |
| 'set print symbol-filename off' |
| Do not print source file name and line number of a symbol. This is |
| the default. |
| |
| 'show print symbol-filename' |
| Show whether or not GDB will print the source file name and line |
| number of a symbol in the symbolic form of an address. |
| |
| Another situation where it is helpful to show symbol filenames and |
| line numbers is when disassembling code; GDB shows you the line number |
| and source file that corresponds to each instruction. |
| |
| Also, you may wish to see the symbolic form only if the address being |
| printed is reasonably close to the closest earlier symbol: |
| |
| 'set print max-symbolic-offset MAX-OFFSET' |
| 'set print max-symbolic-offset unlimited' |
| Tell GDB to only display the symbolic form of an address if the |
| offset between the closest earlier symbol and the address is less |
| than MAX-OFFSET. The default is 'unlimited', which tells GDB to |
| always print the symbolic form of an address if any symbol precedes |
| it. Zero is equivalent to 'unlimited'. |
| |
| 'show print max-symbolic-offset' |
| Ask how large the maximum offset is that GDB prints in a symbolic |
| address. |
| |
| If you have a pointer and you are not sure where it points, try 'set |
| print symbol-filename on'. Then you can determine the name and source |
| file location of the variable where it points, using 'p/a POINTER'. |
| This interprets the address in symbolic form. For example, here GDB |
| shows that a variable 'ptt' points at another variable 't', defined in |
| 'hi2.c': |
| |
| (gdb) set print symbol-filename on |
| (gdb) p/a ptt |
| $4 = 0xe008 <t in hi2.c> |
| |
| _Warning:_ For pointers that point to a local variable, 'p/a' does |
| not show the symbol name and filename of the referent, even with |
| the appropriate 'set print' options turned on. |
| |
| You can also enable '/a'-like formatting all the time using 'set |
| print symbol on': |
| |
| 'set print symbol on' |
| Tell GDB to print the symbol corresponding to an address, if one |
| exists. |
| |
| 'set print symbol off' |
| Tell GDB not to print the symbol corresponding to an address. In |
| this mode, GDB will still print the symbol corresponding to |
| pointers to functions. This is the default. |
| |
| 'show print symbol' |
| Show whether GDB will display the symbol corresponding to an |
| address. |
| |
| Other settings control how different kinds of objects are printed: |
| |
| 'set print array' |
| 'set print array on' |
| Pretty print arrays. This format is more convenient to read, but |
| uses more space. The default is off. |
| |
| 'set print array off' |
| Return to compressed format for arrays. |
| |
| 'show print array' |
| Show whether compressed or pretty format is selected for displaying |
| arrays. |
| |
| 'set print array-indexes' |
| 'set print array-indexes on' |
| Print the index of each element when displaying arrays. May be |
| more convenient to locate a given element in the array or quickly |
| find the index of a given element in that printed array. The |
| default is off. |
| |
| 'set print array-indexes off' |
| Stop printing element indexes when displaying arrays. |
| |
| 'show print array-indexes' |
| Show whether the index of each element is printed when displaying |
| arrays. |
| |
| 'set print elements NUMBER-OF-ELEMENTS' |
| 'set print elements unlimited' |
| Set a limit on how many elements of an array GDB will print. If |
| GDB is printing a large array, it stops printing after it has |
| printed the number of elements set by the 'set print elements' |
| command. This limit also applies to the display of strings. When |
| GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS |
| to 'unlimited' or zero means that the number of elements to print |
| is unlimited. |
| |
| 'show print elements' |
| Display the number of elements of a large array that GDB will |
| print. If the number is 0, then the printing is unlimited. |
| |
| 'set print frame-arguments VALUE' |
| This command allows to control how the values of arguments are |
| printed when the debugger prints a frame (*note Frames::). The |
| possible values are: |
| |
| 'all' |
| The values of all arguments are printed. |
| |
| 'scalars' |
| Print the value of an argument only if it is a scalar. The |
| value of more complex arguments such as arrays, structures, |
| unions, etc, is replaced by '...'. This is the default. Here |
| is an example where only scalar arguments are shown: |
| |
| #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) |
| at frame-args.c:23 |
| |
| 'none' |
| None of the argument values are printed. Instead, the value |
| of each argument is replaced by '...'. In this case, the |
| example above now becomes: |
| |
| #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) |
| at frame-args.c:23 |
| |
| By default, only scalar arguments are printed. This command can be |
| used to configure the debugger to print the value of all arguments, |
| regardless of their type. However, it is often advantageous to not |
| print the value of more complex parameters. For instance, it |
| reduces the amount of information printed in each frame, making the |
| backtrace more readable. Also, it improves performance when |
| displaying Ada frames, because the computation of large arguments |
| can sometimes be CPU-intensive, especially in large applications. |
| Setting 'print frame-arguments' to 'scalars' (the default) or |
| 'none' avoids this computation, thus speeding up the display of |
| each Ada frame. |
| |
| 'show print frame-arguments' |
| Show how the value of arguments should be displayed when printing a |
| frame. |
| |
| 'set print raw frame-arguments on' |
| Print frame arguments in raw, non pretty-printed, form. |
| |
| 'set print raw frame-arguments off' |
| Print frame arguments in pretty-printed form, if there is a |
| pretty-printer for the value (*note Pretty Printing::), otherwise |
| print the value in raw form. This is the default. |
| |
| 'show print raw frame-arguments' |
| Show whether to print frame arguments in raw form. |
| |
| 'set print entry-values VALUE' |
| Set printing of frame argument values at function entry. In some |
| cases GDB can determine the value of function argument which was |
| passed by the function caller, even if the value was modified |
| inside the called function and therefore is different. With |
| optimized code, the current value could be unavailable, but the |
| entry value may still be known. |
| |
| The default value is 'default' (see below for its description). |
| Older GDB behaved as with the setting 'no'. Compilers not |
| supporting this feature will behave in the 'default' setting the |
| same way as with the 'no' setting. |
| |
| This functionality is currently supported only by DWARF 2 debugging |
| format and the compiler has to produce 'DW_TAG_GNU_call_site' tags. |
| With GCC, you need to specify '-O -g' during compilation, to get |
| this information. |
| |
| The VALUE parameter can be one of the following: |
| |
| 'no' |
| Print only actual parameter values, never print values from |
| function entry point. |
| #0 equal (val=5) |
| #0 different (val=6) |
| #0 lost (val=<optimized out>) |
| #0 born (val=10) |
| #0 invalid (val=<optimized out>) |
| |
| 'only' |
| Print only parameter values from function entry point. The |
| actual parameter values are never printed. |
| #0 equal (val@entry=5) |
| #0 different (val@entry=5) |
| #0 lost (val@entry=5) |
| #0 born (val@entry=<optimized out>) |
| #0 invalid (val@entry=<optimized out>) |
| |
| 'preferred' |
| Print only parameter values from function entry point. If |
| value from function entry point is not known while the actual |
| value is known, print the actual value for such parameter. |
| #0 equal (val@entry=5) |
| #0 different (val@entry=5) |
| #0 lost (val@entry=5) |
| #0 born (val=10) |
| #0 invalid (val@entry=<optimized out>) |
| |
| 'if-needed' |
| Print actual parameter values. If actual parameter value is |
| not known while value from function entry point is known, |
| print the entry point value for such parameter. |
| #0 equal (val=5) |
| #0 different (val=6) |
| #0 lost (val@entry=5) |
| #0 born (val=10) |
| #0 invalid (val=<optimized out>) |
| |
| 'both' |
| Always print both the actual parameter value and its value |
| from function entry point, even if values of one or both are |
| not available due to compiler optimizations. |
| #0 equal (val=5, val@entry=5) |
| #0 different (val=6, val@entry=5) |
| #0 lost (val=<optimized out>, val@entry=5) |
| #0 born (val=10, val@entry=<optimized out>) |
| #0 invalid (val=<optimized out>, val@entry=<optimized out>) |
| |
| 'compact' |
| Print the actual parameter value if it is known and also its |
| value from function entry point if it is known. If neither is |
| known, print for the actual value '<optimized out>'. If not |
| in MI mode (*note GDB/MI::) and if both values are known and |
| identical, print the shortened 'param=param@entry=VALUE' |
| notation. |
| #0 equal (val=val@entry=5) |
| #0 different (val=6, val@entry=5) |
| #0 lost (val@entry=5) |
| #0 born (val=10) |
| #0 invalid (val=<optimized out>) |
| |
| 'default' |
| Always print the actual parameter value. Print also its value |
| from function entry point, but only if it is known. If not in |
| MI mode (*note GDB/MI::) and if both values are known and |
| identical, print the shortened 'param=param@entry=VALUE' |
| notation. |
| #0 equal (val=val@entry=5) |
| #0 different (val=6, val@entry=5) |
| #0 lost (val=<optimized out>, val@entry=5) |
| #0 born (val=10) |
| #0 invalid (val=<optimized out>) |
| |
| For analysis messages on possible failures of frame argument values |
| at function entry resolution see *note set debug entry-values::. |
| |
| 'show print entry-values' |
| Show the method being used for printing of frame argument values at |
| function entry. |
| |
| 'set print repeats NUMBER-OF-REPEATS' |
| 'set print repeats unlimited' |
| Set the threshold for suppressing display of repeated array |
| elements. When the number of consecutive identical elements of an |
| array exceeds the threshold, GDB prints the string '"<repeats N |
| times>"', where N is the number of identical repetitions, instead |
| of displaying the identical elements themselves. Setting the |
| threshold to 'unlimited' or zero will cause all elements to be |
| individually printed. The default threshold is 10. |
| |
| 'show print repeats' |
| Display the current threshold for printing repeated identical |
| elements. |
| |
| 'set print null-stop' |
| Cause GDB to stop printing the characters of an array when the |
| first NULL is encountered. This is useful when large arrays |
| actually contain only short strings. The default is off. |
| |
| 'show print null-stop' |
| Show whether GDB stops printing an array on the first NULL |
| character. |
| |
| 'set print pretty on' |
| Cause GDB to print structures in an indented format with one member |
| per line, like this: |
| |
| $1 = { |
| next = 0x0, |
| flags = { |
| sweet = 1, |
| sour = 1 |
| }, |
| meat = 0x54 "Pork" |
| } |
| |
| 'set print pretty off' |
| Cause GDB to print structures in a compact format, like this: |
| |
| $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ |
| meat = 0x54 "Pork"} |
| |
| This is the default format. |
| |
| 'show print pretty' |
| Show which format GDB is using to print structures. |
| |
| 'set print sevenbit-strings on' |
| Print using only seven-bit characters; if this option is set, GDB |
| displays any eight-bit characters (in strings or character values) |
| using the notation '\'NNN. This setting is best if you are working |
| in English (ASCII) and you use the high-order bit of characters as |
| a marker or "meta" bit. |
| |
| 'set print sevenbit-strings off' |
| Print full eight-bit characters. This allows the use of more |
| international character sets, and is the default. |
| |
| 'show print sevenbit-strings' |
| Show whether or not GDB is printing only seven-bit characters. |
| |
| 'set print union on' |
| Tell GDB to print unions which are contained in structures and |
| other unions. This is the default setting. |
| |
| 'set print union off' |
| Tell GDB not to print unions which are contained in structures and |
| other unions. GDB will print '"{...}"' instead. |
| |
| 'show print union' |
| Ask GDB whether or not it will print unions which are contained in |
| structures and other unions. |
| |
| For example, given the declarations |
| |
| typedef enum {Tree, Bug} Species; |
| typedef enum {Big_tree, Acorn, Seedling} Tree_forms; |
| typedef enum {Caterpillar, Cocoon, Butterfly} |
| Bug_forms; |
| |
| struct thing { |
| Species it; |
| union { |
| Tree_forms tree; |
| Bug_forms bug; |
| } form; |
| }; |
| |
| struct thing foo = {Tree, {Acorn}}; |
| |
| with 'set print union on' in effect 'p foo' would print |
| |
| $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} |
| |
| and with 'set print union off' in effect it would print |
| |
| $1 = {it = Tree, form = {...}} |
| |
| 'set print union' affects programs written in C-like languages and |
| in Pascal. |
| |
| These settings are of interest when debugging C++ programs: |
| |
| 'set print demangle' |
| 'set print demangle on' |
| Print C++ names in their source form rather than in the encoded |
| ("mangled") form passed to the assembler and linker for type-safe |
| linkage. The default is on. |
| |
| 'show print demangle' |
| Show whether C++ names are printed in mangled or demangled form. |
| |
| 'set print asm-demangle' |
| 'set print asm-demangle on' |
| Print C++ names in their source form rather than their mangled |
| form, even in assembler code printouts such as instruction |
| disassemblies. The default is off. |
| |
| 'show print asm-demangle' |
| Show whether C++ names in assembly listings are printed in mangled |
| or demangled form. |
| |
| 'set demangle-style STYLE' |
| Choose among several encoding schemes used by different compilers |
| to represent C++ names. The choices for STYLE are currently: |
| |
| 'auto' |
| Allow GDB to choose a decoding style by inspecting your |
| program. This is the default. |
| |
| 'gnu' |
| Decode based on the GNU C++ compiler ('g++') encoding |
| algorithm. |
| |
| 'hp' |
| Decode based on the HP ANSI C++ ('aCC') encoding algorithm. |
| |
| 'lucid' |
| Decode based on the Lucid C++ compiler ('lcc') encoding |
| algorithm. |
| |
| 'arm' |
| Decode using the algorithm in the 'C++ Annotated Reference |
| Manual'. *Warning:* this setting alone is not sufficient to |
| allow debugging 'cfront'-generated executables. GDB would |
| require further enhancement to permit that. |
| |
| If you omit STYLE, you will see a list of possible formats. |
| |
| 'show demangle-style' |
| Display the encoding style currently in use for decoding C++ |
| symbols. |
| |
| 'set print object' |
| 'set print object on' |
| When displaying a pointer to an object, identify the _actual_ |
| (derived) type of the object rather than the _declared_ type, using |
| the virtual function table. Note that the virtual function table |
| is required--this feature can only work for objects that have |
| run-time type identification; a single virtual method in the |
| object's declared type is sufficient. Note that this setting is |
| also taken into account when working with variable objects via MI |
| (*note GDB/MI::). |
| |
| 'set print object off' |
| Display only the declared type of objects, without reference to the |
| virtual function table. This is the default setting. |
| |
| 'show print object' |
| Show whether actual, or declared, object types are displayed. |
| |
| 'set print static-members' |
| 'set print static-members on' |
| Print static members when displaying a C++ object. The default is |
| on. |
| |
| 'set print static-members off' |
| Do not print static members when displaying a C++ object. |
| |
| 'show print static-members' |
| Show whether C++ static members are printed or not. |
| |
| 'set print pascal_static-members' |
| 'set print pascal_static-members on' |
| Print static members when displaying a Pascal object. The default |
| is on. |
| |
| 'set print pascal_static-members off' |
| Do not print static members when displaying a Pascal object. |
| |
| 'show print pascal_static-members' |
| Show whether Pascal static members are printed or not. |
| |
| 'set print vtbl' |
| 'set print vtbl on' |
| Pretty print C++ virtual function tables. The default is off. |
| (The 'vtbl' commands do not work on programs compiled with the HP |
| ANSI C++ compiler ('aCC').) |
| |
| 'set print vtbl off' |
| Do not pretty print C++ virtual function tables. |
| |
| 'show print vtbl' |
| Show whether C++ virtual function tables are pretty printed, or |
| not. |
| |
| |
| File: gdb.info, Node: Pretty Printing, Next: Value History, Prev: Print Settings, Up: Data |
| |
| 10.9 Pretty Printing |
| ==================== |
| |
| GDB provides a mechanism to allow pretty-printing of values using Python |
| code. It greatly simplifies the display of complex objects. This |
| mechanism works for both MI and the CLI. |
| |
| * Menu: |
| |
| * Pretty-Printer Introduction:: Introduction to pretty-printers |
| * Pretty-Printer Example:: An example pretty-printer |
| * Pretty-Printer Commands:: Pretty-printer commands |
| |
| |
| File: gdb.info, Node: Pretty-Printer Introduction, Next: Pretty-Printer Example, Up: Pretty Printing |
| |
| 10.9.1 Pretty-Printer Introduction |
| ---------------------------------- |
| |
| When GDB prints a value, it first sees if there is a pretty-printer |
| registered for the value. If there is then GDB invokes the |
| pretty-printer to print the value. Otherwise the value is printed |
| normally. |
| |
| Pretty-printers are normally named. This makes them easy to manage. |
| The 'info pretty-printer' command will list all the installed |
| pretty-printers with their names. If a pretty-printer can handle |
| multiple data types, then its "subprinters" are the printers for the |
| individual data types. Each such subprinter has its own name. The |
| format of the name is PRINTER-NAME;SUBPRINTER-NAME. |
| |
| Pretty-printers are installed by "registering" them with GDB. |
| Typically they are automatically loaded and registered when the |
| corresponding debug information is loaded, thus making them available |
| without having to do anything special. |
| |
| There are three places where a pretty-printer can be registered. |
| |
| * Pretty-printers registered globally are available when debugging |
| all inferiors. |
| |
| * Pretty-printers registered with a program space are available only |
| when debugging that program. *Note Progspaces In Python::, for |
| more details on program spaces in Python. |
| |
| * Pretty-printers registered with an objfile are loaded and unloaded |
| with the corresponding objfile (e.g., shared library). *Note |
| Objfiles In Python::, for more details on objfiles in Python. |
| |
| *Note Selecting Pretty-Printers::, for further information on how |
| pretty-printers are selected, |
| |
| *Note Writing a Pretty-Printer::, for implementing pretty printers |
| for new types. |
| |
| |
| File: gdb.info, Node: Pretty-Printer Example, Next: Pretty-Printer Commands, Prev: Pretty-Printer Introduction, Up: Pretty Printing |
| |
| 10.9.2 Pretty-Printer Example |
| ----------------------------- |
| |
| Here is how a C++ 'std::string' looks without a pretty-printer: |
| |
| (gdb) print s |
| $1 = { |
| static npos = 4294967295, |
| _M_dataplus = { |
| <std::allocator<char>> = { |
| <__gnu_cxx::new_allocator<char>> = { |
| <No data fields>}, <No data fields> |
| }, |
| members of std::basic_string<char, std::char_traits<char>, |
| std::allocator<char> >::_Alloc_hider: |
| _M_p = 0x804a014 "abcd" |
| } |
| } |
| |
| With a pretty-printer for 'std::string' only the contents are |
| printed: |
| |
| (gdb) print s |
| $2 = "abcd" |
| |
| |
| File: gdb.info, Node: Pretty-Printer Commands, Prev: Pretty-Printer Example, Up: Pretty Printing |
| |
| 10.9.3 Pretty-Printer Commands |
| ------------------------------ |
| |
| 'info pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' |
| Print the list of installed pretty-printers. This includes |
| disabled pretty-printers, which are marked as such. |
| |
| OBJECT-REGEXP is a regular expression matching the objects whose |
| pretty-printers to list. Objects can be 'global', the program |
| space's file (*note Progspaces In Python::), and the object files |
| within that program space (*note Objfiles In Python::). *Note |
| Selecting Pretty-Printers::, for details on how GDB looks up a |
| printer from these three objects. |
| |
| NAME-REGEXP is a regular expression matching the name of the |
| printers to list. |
| |
| 'disable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' |
| Disable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. A |
| disabled pretty-printer is not forgotten, it may be enabled again |
| later. |
| |
| 'enable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' |
| Enable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. |
| |
| Example: |
| |
| Suppose we have three pretty-printers installed: one from library1.so |
| named 'foo' that prints objects of type 'foo', and another from |
| library2.so named 'bar' that prints two types of objects, 'bar1' and |
| 'bar2'. |
| |
| (gdb) info pretty-printer |
| library1.so: |
| foo |
| library2.so: |
| bar |
| bar1 |
| bar2 |
| (gdb) info pretty-printer library2 |
| library2.so: |
| bar |
| bar1 |
| bar2 |
| (gdb) disable pretty-printer library1 |
| 1 printer disabled |
| 2 of 3 printers enabled |
| (gdb) info pretty-printer |
| library1.so: |
| foo [disabled] |
| library2.so: |
| bar |
| bar1 |
| bar2 |
| (gdb) disable pretty-printer library2 bar:bar1 |
| 1 printer disabled |
| 1 of 3 printers enabled |
| (gdb) info pretty-printer library2 |
| library1.so: |
| foo [disabled] |
| library2.so: |
| bar |
| bar1 [disabled] |
| bar2 |
| (gdb) disable pretty-printer library2 bar |
| 1 printer disabled |
| 0 of 3 printers enabled |
| (gdb) info pretty-printer library2 |
| library1.so: |
| foo [disabled] |
| library2.so: |
| bar [disabled] |
| bar1 [disabled] |
| bar2 |
| |
| Note that for 'bar' the entire printer can be disabled, as can each |
| individual subprinter. |
| |
| |
| File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Pretty Printing, Up: Data |
| |
| 10.10 Value History |
| =================== |
| |
| Values printed by the 'print' command are saved in the GDB "value |
| history". This allows you to refer to them in other expressions. |
| Values are kept until the symbol table is re-read or discarded (for |
| example with the 'file' or 'symbol-file' commands). When the symbol |
| table changes, the value history is discarded, since the values may |
| contain pointers back to the types defined in the symbol table. |
| |
| The values printed are given "history numbers" by which you can refer |
| to them. These are successive integers starting with one. 'print' |
| shows you the history number assigned to a value by printing '$NUM = ' |
| before the value; here NUM is the history number. |
| |
| To refer to any previous value, use '$' followed by the value's |
| history number. The way 'print' labels its output is designed to remind |
| you of this. Just '$' refers to the most recent value in the history, |
| and '$$' refers to the value before that. '$$N' refers to the Nth value |
| from the end; '$$2' is the value just prior to '$$', '$$1' is equivalent |
| to '$$', and '$$0' is equivalent to '$'. |
| |
| For example, suppose you have just printed a pointer to a structure |
| and want to see the contents of the structure. It suffices to type |
| |
| p *$ |
| |
| If you have a chain of structures where the component 'next' points |
| to the next one, you can print the contents of the next one with this: |
| |
| p *$.next |
| |
| You can print successive links in the chain by repeating this |
| command--which you can do by just typing <RET>. |
| |
| Note that the history records values, not expressions. If the value |
| of 'x' is 4 and you type these commands: |
| |
| print x |
| set x=5 |
| |
| then the value recorded in the value history by the 'print' command |
| remains 4 even though the value of 'x' has changed. |
| |
| 'show values' |
| Print the last ten values in the value history, with their item |
| numbers. This is like 'p $$9' repeated ten times, except that |
| 'show values' does not change the history. |
| |
| 'show values N' |
| Print ten history values centered on history item number N. |
| |
| 'show values +' |
| Print ten history values just after the values last printed. If no |
| more values are available, 'show values +' produces no display. |
| |
| Pressing <RET> to repeat 'show values N' has exactly the same effect |
| as 'show values +'. |
| |
| |
| File: gdb.info, Node: Convenience Vars, Next: Convenience Funs, Prev: Value History, Up: Data |
| |
| 10.11 Convenience Variables |
| =========================== |
| |
| GDB provides "convenience variables" that you can use within GDB to hold |
| on to a value and refer to it later. These variables exist entirely |
| within GDB; they are not part of your program, and setting a convenience |
| variable has no direct effect on further execution of your program. |
| That is why you can use them freely. |
| |
| Convenience variables are prefixed with '$'. Any name preceded by |
| '$' can be used for a convenience variable, unless it is one of the |
| predefined machine-specific register names (*note Registers: |
| Registers.). (Value history references, in contrast, are _numbers_ |
| preceded by '$'. *Note Value History: Value History.) |
| |
| You can save a value in a convenience variable with an assignment |
| expression, just as you would set a variable in your program. For |
| example: |
| |
| set $foo = *object_ptr |
| |
| would save in '$foo' the value contained in the object pointed to by |
| 'object_ptr'. |
| |
| Using a convenience variable for the first time creates it, but its |
| value is 'void' until you assign a new value. You can alter the value |
| with another assignment at any time. |
| |
| Convenience variables have no fixed types. You can assign a |
| convenience variable any type of value, including structures and arrays, |
| even if that variable already has a value of a different type. The |
| convenience variable, when used as an expression, has the type of its |
| current value. |
| |
| 'show convenience' |
| Print a list of convenience variables used so far, and their |
| values, as well as a list of the convenience functions. |
| Abbreviated 'show conv'. |
| |
| 'init-if-undefined $VARIABLE = EXPRESSION' |
| Set a convenience variable if it has not already been set. This is |
| useful for user-defined commands that keep some state. It is |
| similar, in concept, to using local static variables with |
| initializers in C (except that convenience variables are global). |
| It can also be used to allow users to override default values used |
| in a command script. |
| |
| If the variable is already defined then the expression is not |
| evaluated so any side-effects do not occur. |
| |
| One of the ways to use a convenience variable is as a counter to be |
| incremented or a pointer to be advanced. For example, to print a field |
| from successive elements of an array of structures: |
| |
| set $i = 0 |
| print bar[$i++]->contents |
| |
| Repeat that command by typing <RET>. |
| |
| Some convenience variables are created automatically by GDB and given |
| values likely to be useful. |
| |
| '$_' |
| The variable '$_' is automatically set by the 'x' command to the |
| last address examined (*note Examining Memory: Memory.). Other |
| commands which provide a default address for 'x' to examine also |
| set '$_' to that address; these commands include 'info line' and |
| 'info breakpoint'. The type of '$_' is 'void *' except when set by |
| the 'x' command, in which case it is a pointer to the type of |
| '$__'. |
| |
| '$__' |
| The variable '$__' is automatically set by the 'x' command to the |
| value found in the last address examined. Its type is chosen to |
| match the format in which the data was printed. |
| |
| '$_exitcode' |
| When the program being debugged terminates normally, GDB |
| automatically sets this variable to the exit code of the program, |
| and resets '$_exitsignal' to 'void'. |
| |
| '$_exitsignal' |
| When the program being debugged dies due to an uncaught signal, GDB |
| automatically sets this variable to that signal's number, and |
| resets '$_exitcode' to 'void'. |
| |
| To distinguish between whether the program being debugged has |
| exited (i.e., '$_exitcode' is not 'void') or signalled (i.e., |
| '$_exitsignal' is not 'void'), the convenience function '$_isvoid' |
| can be used (*note Convenience Functions: Convenience Funs.). For |
| example, considering the following source code: |
| |
| #include <signal.h> |
| |
| int |
| main (int argc, char *argv[]) |
| { |
| raise (SIGALRM); |
| return 0; |
| } |
| |
| A valid way of telling whether the program being debugged has |
| exited or signalled would be: |
| |
| (gdb) define has_exited_or_signalled |
| Type commands for definition of ``has_exited_or_signalled''. |
| End with a line saying just ``end''. |
| >if $_isvoid ($_exitsignal) |
| >echo The program has exited\n |
| >else |
| >echo The program has signalled\n |
| >end |
| >end |
| (gdb) run |
| Starting program: |
| |
| Program terminated with signal SIGALRM, Alarm clock. |
| The program no longer exists. |
| (gdb) has_exited_or_signalled |
| The program has signalled |
| |
| As can be seen, GDB correctly informs that the program being |
| debugged has signalled, since it calls 'raise' and raises a |
| 'SIGALRM' signal. If the program being debugged had not called |
| 'raise', then GDB would report a normal exit: |
| |
| (gdb) has_exited_or_signalled |
| The program has exited |
| |
| '$_exception' |
| The variable '$_exception' is set to the exception object being |
| thrown at an exception-related catchpoint. *Note Set |
| Catchpoints::. |
| |
| '$_probe_argc' |
| '$_probe_arg0...$_probe_arg11' |
| Arguments to a static probe. *Note Static Probe Points::. |
| |
| '$_sdata' |
| The variable '$_sdata' contains extra collected static tracepoint |
| data. *Note Tracepoint Action Lists: Tracepoint Actions. Note |
| that '$_sdata' could be empty, if not inspecting a trace buffer, or |
| if extra static tracepoint data has not been collected. |
| |
| '$_siginfo' |
| The variable '$_siginfo' contains extra signal information (*note |
| extra signal information::). Note that '$_siginfo' could be empty, |
| if the application has not yet received any signals. For example, |
| it will be empty before you execute the 'run' command. |
| |
| '$_tlb' |
| The variable '$_tlb' is automatically set when debugging |
| applications running on MS-Windows in native mode or connected to |
| gdbserver that supports the 'qGetTIBAddr' request. *Note General |
| Query Packets::. This variable contains the address of the thread |
| information block. |
| |
| On HP-UX systems, if you refer to a function or variable name that |
| begins with a dollar sign, GDB searches for a user or system name first, |
| before it searches for a convenience variable. |
| |
| |
| File: gdb.info, Node: Convenience Funs, Next: Registers, Prev: Convenience Vars, Up: Data |
| |
| 10.12 Convenience Functions |
| =========================== |
| |
| GDB also supplies some "convenience functions". These have a syntax |
| similar to convenience variables. A convenience function can be used in |
| an expression just like an ordinary function; however, a convenience |
| function is implemented internally to GDB. |
| |
| These functions do not require GDB to be configured with 'Python' |
| support, which means that they are always available. |
| |
| '$_isvoid (EXPR)' |
| Return one if the expression EXPR is 'void'. Otherwise it returns |
| zero. |
| |
| A 'void' expression is an expression where the type of the result |
| is 'void'. For example, you can examine a convenience variable |
| (see *note Convenience Variables: Convenience Vars.) to check |
| whether it is 'void': |
| |
| (gdb) print $_exitcode |
| $1 = void |
| (gdb) print $_isvoid ($_exitcode) |
| $2 = 1 |
| (gdb) run |
| Starting program: ./a.out |
| [Inferior 1 (process 29572) exited normally] |
| (gdb) print $_exitcode |
| $3 = 0 |
| (gdb) print $_isvoid ($_exitcode) |
| $4 = 0 |
| |
| In the example above, we used '$_isvoid' to check whether |
| '$_exitcode' is 'void' before and after the execution of the |
| program being debugged. Before the execution there is no exit code |
| to be examined, therefore '$_exitcode' is 'void'. After the |
| execution the program being debugged returned zero, therefore |
| '$_exitcode' is zero, which means that it is not 'void' anymore. |
| |
| The 'void' expression can also be a call of a function from the |
| program being debugged. For example, given the following function: |
| |
| void |
| foo (void) |
| { |
| } |
| |
| The result of calling it inside GDB is 'void': |
| |
| (gdb) print foo () |
| $1 = void |
| (gdb) print $_isvoid (foo ()) |
| $2 = 1 |
| (gdb) set $v = foo () |
| (gdb) print $v |
| $3 = void |
| (gdb) print $_isvoid ($v) |
| $4 = 1 |
| |
| These functions require GDB to be configured with 'Python' support. |
| |
| '$_memeq(BUF1, BUF2, LENGTH)' |
| Returns one if the LENGTH bytes at the addresses given by BUF1 and |
| BUF2 are equal. Otherwise it returns zero. |
| |
| '$_regex(STR, REGEX)' |
| Returns one if the string STR matches the regular expression REGEX. |
| Otherwise it returns zero. The syntax of the regular expression is |
| that specified by 'Python''s regular expression support. |
| |
| '$_streq(STR1, STR2)' |
| Returns one if the strings STR1 and STR2 are equal. Otherwise it |
| returns zero. |
| |
| '$_strlen(STR)' |
| Returns the length of string STR. |
| |
| '$_caller_is(NAME[, NUMBER_OF_FRAMES])' |
| Returns one if the calling function's name is equal to NAME. |
| Otherwise it returns zero. |
| |
| If the optional argument NUMBER_OF_FRAMES is provided, it is the |
| number of frames up in the stack to look. The default is 1. |
| |
| Example: |
| |
| (gdb) backtrace |
| #0 bottom_func () |
| at testsuite/gdb.python/py-caller-is.c:21 |
| #1 0x00000000004005a0 in middle_func () |
| at testsuite/gdb.python/py-caller-is.c:27 |
| #2 0x00000000004005ab in top_func () |
| at testsuite/gdb.python/py-caller-is.c:33 |
| #3 0x00000000004005b6 in main () |
| at testsuite/gdb.python/py-caller-is.c:39 |
| (gdb) print $_caller_is ("middle_func") |
| $1 = 1 |
| (gdb) print $_caller_is ("top_func", 2) |
| $1 = 1 |
| |
| '$_caller_matches(REGEXP[, NUMBER_OF_FRAMES])' |
| Returns one if the calling function's name matches the regular |
| expression REGEXP. Otherwise it returns zero. |
| |
| If the optional argument NUMBER_OF_FRAMES is provided, it is the |
| number of frames up in the stack to look. The default is 1. |
| |
| '$_any_caller_is(NAME[, NUMBER_OF_FRAMES])' |
| Returns one if any calling function's name is equal to NAME. |
| Otherwise it returns zero. |
| |
| If the optional argument NUMBER_OF_FRAMES is provided, it is the |
| number of frames up in the stack to look. The default is 1. |
| |
| This function differs from '$_caller_is' in that this function |
| checks all stack frames from the immediate caller to the frame |
| specified by NUMBER_OF_FRAMES, whereas '$_caller_is' only checks |
| the frame specified by NUMBER_OF_FRAMES. |
| |
| '$_any_caller_matches(REGEXP[, NUMBER_OF_FRAMES])' |
| Returns one if any calling function's name matches the regular |
| expression REGEXP. Otherwise it returns zero. |
| |
| If the optional argument NUMBER_OF_FRAMES is provided, it is the |
| number of frames up in the stack to look. The default is 1. |
| |
| This function differs from '$_caller_matches' in that this function |
| checks all stack frames from the immediate caller to the frame |
| specified by NUMBER_OF_FRAMES, whereas '$_caller_matches' only |
| checks the frame specified by NUMBER_OF_FRAMES. |
| |
| GDB provides the ability to list and get help on convenience |
| functions. |
| |
| 'help function' |
| Print a list of all convenience functions. |
| |
| |
| File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Funs, Up: Data |
| |
| 10.13 Registers |
| =============== |
| |
| You can refer to machine register contents, in expressions, as variables |
| with names starting with '$'. The names of registers are different for |
| each machine; use 'info registers' to see the names used on your |
| machine. |
| |
| 'info registers' |
| Print the names and values of all registers except floating-point |
| and vector registers (in the selected stack frame). |
| |
| 'info all-registers' |
| Print the names and values of all registers, including |
| floating-point and vector registers (in the selected stack frame). |
| |
| 'info registers REGNAME ...' |
| Print the "relativized" value of each specified register REGNAME. |
| As discussed in detail below, register values are normally relative |
| to the selected stack frame. The REGNAME may be any register name |
| valid on the machine you are using, with or without the initial |
| '$'. |
| |
| GDB has four "standard" register names that are available (in |
| expressions) on most machines--whenever they do not conflict with an |
| architecture's canonical mnemonics for registers. The register names |
| '$pc' and '$sp' are used for the program counter register and the stack |
| pointer. '$fp' is used for a register that contains a pointer to the |
| current stack frame, and '$ps' is used for a register that contains the |
| processor status. For example, you could print the program counter in |
| hex with |
| |
| p/x $pc |
| |
| or print the instruction to be executed next with |
| |
| x/i $pc |
| |
| or add four to the stack pointer(1) with |
| |
| set $sp += 4 |
| |
| Whenever possible, these four standard register names are available |
| on your machine even though the machine has different canonical |
| mnemonics, so long as there is no conflict. The 'info registers' |
| command shows the canonical names. For example, on the SPARC, 'info |
| registers' displays the processor status register as '$psr' but you can |
| also refer to it as '$ps'; and on x86-based machines '$ps' is an alias |
| for the EFLAGS register. |
| |
| GDB always considers the contents of an ordinary register as an |
| integer when the register is examined in this way. Some machines have |
| special registers which can hold nothing but floating point; these |
| registers are considered to have floating point values. There is no way |
| to refer to the contents of an ordinary register as floating point value |
| (although you can _print_ it as a floating point value with 'print/f |
| $REGNAME'). |
| |
| Some registers have distinct "raw" and "virtual" data formats. This |
| means that the data format in which the register contents are saved by |
| the operating system is not the same one that your program normally |
| sees. For example, the registers of the 68881 floating point |
| coprocessor are always saved in "extended" (raw) format, but all C |
| programs expect to work with "double" (virtual) format. In such cases, |
| GDB normally works with the virtual format only (the format that makes |
| sense for your program), but the 'info registers' command prints the |
| data in both formats. |
| |
| Some machines have special registers whose contents can be |
| interpreted in several different ways. For example, modern x86-based |
| machines have SSE and MMX registers that can hold several values packed |
| together in several different formats. GDB refers to such registers in |
| 'struct' notation: |
| |
| (gdb) print $xmm1 |
| $1 = { |
| v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044}, |
| v2_double = {9.92129282474342e-303, 2.7585945287983262e-313}, |
| v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", |
| v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0}, |
| v4_int32 = {0, 20657912, 11, 13}, |
| v2_int64 = {88725056443645952, 55834574859}, |
| uint128 = 0x0000000d0000000b013b36f800000000 |
| } |
| |
| To set values of such registers, you need to tell GDB which view of the |
| register you wish to change, as if you were assigning value to a |
| 'struct' member: |
| |
| (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF |
| |
| Normally, register values are relative to the selected stack frame |
| (*note Selecting a Frame: Selection.). This means that you get the |
| value that the register would contain if all stack frames farther in |
| were exited and their saved registers restored. In order to see the |
| true contents of hardware registers, you must select the innermost frame |
| (with 'frame 0'). |
| |
| Usually ABIs reserve some registers as not needed to be saved by the |
| callee (a.k.a.: "caller-saved", "call-clobbered" or "volatile" |
| registers). It may therefore not be possible for GDB to know the value |
| a register had before the call (in other words, in the outer frame), if |
| the register value has since been changed by the callee. GDB tries to |
| deduce where the inner frame saved ("callee-saved") registers, from the |
| debug info, unwind info, or the machine code generated by your compiler. |
| If some register is not saved, and GDB knows the register is |
| "caller-saved" (via its own knowledge of the ABI, or because the |
| debug/unwind info explicitly says the register's value is undefined), |
| GDB displays '<not saved>' as the register's value. With targets that |
| GDB has no knowledge of the register saving convention, if a register |
| was not saved by the callee, then its value and location in the outer |
| frame are assumed to be the same of the inner frame. This is usually |
| harmless, because if the register is call-clobbered, the caller either |
| does not care what is in the register after the call, or has code to |
| restore the value that it does care about. Note, however, that if you |
| change such a register in the outer frame, you may also be affecting the |
| inner frame. Also, the more "outer" the frame is you're looking at, the |
| more likely a call-clobbered register's value is to be wrong, in the |
| sense that it doesn't actually represent the value the register had just |
| before the call. |
| |
| ---------- Footnotes ---------- |
| |
| (1) This is a way of removing one word from the stack, on machines |
| where stacks grow downward in memory (most machines, nowadays). This |
| assumes that the innermost stack frame is selected; setting '$sp' is not |
| allowed when other stack frames are selected. To pop entire frames off |
| the stack, regardless of machine architecture, use 'return'; see *note |
| Returning from a Function: Returning. |
| |
| |
| File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data |
| |
| 10.14 Floating Point Hardware |
| ============================= |
| |
| Depending on the configuration, GDB may be able to give you more |
| information about the status of the floating point hardware. |
| |
| 'info float' |
| Display hardware-dependent information about the floating point |
| unit. The exact contents and layout vary depending on the floating |
| point chip. Currently, 'info float' is supported on the ARM and |
| x86 machines. |
| |
| |
| File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data |
| |
| 10.15 Vector Unit |
| ================= |
| |
| Depending on the configuration, GDB may be able to give you more |
| information about the status of the vector unit. |
| |
| 'info vector' |
| Display information about the vector unit. The exact contents and |
| layout vary depending on the hardware. |
| |
| |
| File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data |
| |
| 10.16 Operating System Auxiliary Information |
| ============================================ |
| |
| GDB provides interfaces to useful OS facilities that can help you debug |
| your program. |
| |
| Some operating systems supply an "auxiliary vector" to programs at |
| startup. This is akin to the arguments and environment that you specify |
| for a program, but contains a system-dependent variety of binary values |
| that tell system libraries important details about the hardware, |
| operating system, and process. Each value's purpose is identified by an |
| integer tag; the meanings are well-known but system-specific. Depending |
| on the configuration and operating system facilities, GDB may be able to |
| show you this information. For remote targets, this functionality may |
| further depend on the remote stub's support of the 'qXfer:auxv:read' |
| packet, see *note qXfer auxiliary vector read::. |
| |
| 'info auxv' |
| Display the auxiliary vector of the inferior, which can be either a |
| live process or a core dump file. GDB prints each tag value |
| numerically, and also shows names and text descriptions for |
| recognized tags. Some values in the vector are numbers, some bit |
| masks, and some pointers to strings or other data. GDB displays |
| each value in the most appropriate form for a recognized tag, and |
| in hexadecimal for an unrecognized tag. |
| |
| On some targets, GDB can access operating system-specific information |
| and show it to you. The types of information available will differ |
| depending on the type of operating system running on the target. The |
| mechanism used to fetch the data is described in *note Operating System |
| Information::. For remote targets, this functionality depends on the |
| remote stub's support of the 'qXfer:osdata:read' packet, see *note qXfer |
| osdata read::. |
| |
| 'info os INFOTYPE' |
| |
| Display OS information of the requested type. |
| |
| On GNU/Linux, the following values of INFOTYPE are valid: |
| |
| 'cpus' |
| Display the list of all CPUs/cores. For each CPU/core, GDB |
| prints the available fields from /proc/cpuinfo. For each |
| supported architecture different fields are available. Two |
| common entries are processor which gives CPU number and |
| bogomips; a system constant that is calculated during kernel |
| initialization. |
| |
| 'files' |
| Display the list of open file descriptors on the target. For |
| each file descriptor, GDB prints the identifier of the process |
| owning the descriptor, the command of the owning process, the |
| value of the descriptor, and the target of the descriptor. |
| |
| 'modules' |
| Display the list of all loaded kernel modules on the target. |
| For each module, GDB prints the module name, the size of the |
| module in bytes, the number of times the module is used, the |
| dependencies of the module, the status of the module, and the |
| address of the loaded module in memory. |
| |
| 'msg' |
| Display the list of all System V message queues on the target. |
| For each message queue, GDB prints the message queue key, the |
| message queue identifier, the access permissions, the current |
| number of bytes on the queue, the current number of messages |
| on the queue, the processes that last sent and received a |
| message on the queue, the user and group of the owner and |
| creator of the message queue, the times at which a message was |
| last sent and received on the queue, and the time at which the |
| message queue was last changed. |
| |
| 'processes' |
| Display the list of processes on the target. For each |
| process, GDB prints the process identifier, the name of the |
| user, the command corresponding to the process, and the list |
| of processor cores that the process is currently running on. |
| (To understand what these properties mean, for this and the |
| following info types, please consult the general GNU/Linux |
| documentation.) |
| |
| 'procgroups' |
| Display the list of process groups on the target. For each |
| process, GDB prints the identifier of the process group that |
| it belongs to, the command corresponding to the process group |
| leader, the process identifier, and the command line of the |
| process. The list is sorted first by the process group |
| identifier, then by the process identifier, so that processes |
| belonging to the same process group are grouped together and |
| the process group leader is listed first. |
| |
| 'semaphores' |
| Display the list of all System V semaphore sets on the target. |
| For each semaphore set, GDB prints the semaphore set key, the |
| semaphore set identifier, the access permissions, the number |
| of semaphores in the set, the user and group of the owner and |
| creator of the semaphore set, and the times at which the |
| semaphore set was operated upon and changed. |
| |
| 'shm' |
| Display the list of all System V shared-memory regions on the |
| target. For each shared-memory region, GDB prints the region |
| key, the shared-memory identifier, the access permissions, the |
| size of the region, the process that created the region, the |
| process that last attached to or detached from the region, the |
| current number of live attaches to the region, and the times |
| at which the region was last attached to, detach from, and |
| changed. |
| |
| 'sockets' |
| Display the list of Internet-domain sockets on the target. |
| For each socket, GDB prints the address and port of the local |
| and remote endpoints, the current state of the connection, the |
| creator of the socket, the IP address family of the socket, |
| and the type of the connection. |
| |
| 'threads' |
| Display the list of threads running on the target. For each |
| thread, GDB prints the identifier of the process that the |
| thread belongs to, the command of the process, the thread |
| identifier, and the processor core that it is currently |
| running on. The main thread of a process is not listed. |
| |
| 'info os' |
| If INFOTYPE is omitted, then list the possible values for INFOTYPE |
| and the kind of OS information available for each INFOTYPE. If the |
| target does not return a list of possible types, this command will |
| report an error. |
| |
| |
| File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data |
| |
| 10.17 Memory Region Attributes |
| ============================== |
| |
| "Memory region attributes" allow you to describe special handling |
| required by regions of your target's memory. GDB uses attributes to |
| determine whether to allow certain types of memory accesses; whether to |
| use specific width accesses; and whether to cache target memory. By |
| default the description of memory regions is fetched from the target (if |
| the current target supports this), but the user can override the fetched |
| regions. |
| |
| Defined memory regions can be individually enabled and disabled. |
| When a memory region is disabled, GDB uses the default attributes when |
| accessing memory in that region. Similarly, if no memory regions have |
| been defined, GDB uses the default attributes when accessing all memory. |
| |
| When a memory region is defined, it is given a number to identify it; |
| to enable, disable, or remove a memory region, you specify that number. |
| |
| 'mem LOWER UPPER ATTRIBUTES...' |
| Define a memory region bounded by LOWER and UPPER with attributes |
| ATTRIBUTES..., and add it to the list of regions monitored by GDB. |
| Note that UPPER == 0 is a special case: it is treated as the |
| target's maximum memory address. (0xffff on 16 bit targets, |
| 0xffffffff on 32 bit targets, etc.) |
| |
| 'mem auto' |
| Discard any user changes to the memory regions and use |
| target-supplied regions, if available, or no regions if the target |
| does not support. |
| |
| 'delete mem NUMS...' |
| Remove memory regions NUMS... from the list of regions monitored by |
| GDB. |
| |
| 'disable mem NUMS...' |
| Disable monitoring of memory regions NUMS.... A disabled memory |
| region is not forgotten. It may be enabled again later. |
| |
| 'enable mem NUMS...' |
| Enable monitoring of memory regions NUMS.... |
| |
| 'info mem' |
| Print a table of all defined memory regions, with the following |
| columns for each region: |
| |
| _Memory Region Number_ |
| _Enabled or Disabled._ |
| Enabled memory regions are marked with 'y'. Disabled memory |
| regions are marked with 'n'. |
| |
| _Lo Address_ |
| The address defining the inclusive lower bound of the memory |
| region. |
| |
| _Hi Address_ |
| The address defining the exclusive upper bound of the memory |
| region. |
| |
| _Attributes_ |
| The list of attributes set for this memory region. |
| |
| 10.17.1 Attributes |
| ------------------ |
| |
| 10.17.1.1 Memory Access Mode |
| ............................ |
| |
| The access mode attributes set whether GDB may make read or write |
| accesses to a memory region. |
| |
| While these attributes prevent GDB from performing invalid memory |
| accesses, they do nothing to prevent the target system, I/O DMA, etc. |
| from accessing memory. |
| |
| 'ro' |
| Memory is read only. |
| 'wo' |
| Memory is write only. |
| 'rw' |
| Memory is read/write. This is the default. |
| |
| 10.17.1.2 Memory Access Size |
| ............................ |
| |
| The access size attribute tells GDB to use specific sized accesses in |
| the memory region. Often memory mapped device registers require |
| specific sized accesses. If no access size attribute is specified, GDB |
| may use accesses of any size. |
| |
| '8' |
| Use 8 bit memory accesses. |
| '16' |
| Use 16 bit memory accesses. |
| '32' |
| Use 32 bit memory accesses. |
| '64' |
| Use 64 bit memory accesses. |
| |
| 10.17.1.3 Data Cache |
| .................... |
| |
| The data cache attributes set whether GDB will cache target memory. |
| While this generally improves performance by reducing debug protocol |
| overhead, it can lead to incorrect results because GDB does not know |
| about volatile variables or memory mapped device registers. |
| |
| 'cache' |
| Enable GDB to cache target memory. |
| 'nocache' |
| Disable GDB from caching target memory. This is the default. |
| |
| 10.17.2 Memory Access Checking |
| ------------------------------ |
| |
| GDB can be instructed to refuse accesses to memory that is not |
| explicitly described. This can be useful if accessing such regions has |
| undesired effects for a specific target, or to provide better error |
| checking. The following commands control this behaviour. |
| |
| 'set mem inaccessible-by-default [on|off]' |
| If 'on' is specified, make GDB treat memory not explicitly |
| described by the memory ranges as non-existent and refuse accesses |
| to such memory. The checks are only performed if there's at least |
| one memory range defined. If 'off' is specified, make GDB treat |
| the memory not explicitly described by the memory ranges as RAM. |
| The default value is 'on'. |
| 'show mem inaccessible-by-default' |
| Show the current handling of accesses to unknown memory. |
| |
| |
| File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data |
| |
| 10.18 Copy Between Memory and a File |
| ==================================== |
| |
| You can use the commands 'dump', 'append', and 'restore' to copy data |
| between target memory and a file. The 'dump' and 'append' commands |
| write data to a file, and the 'restore' command reads data from a file |
| back into the inferior's memory. Files may be in binary, Motorola |
| S-record, Intel hex, Tektronix Hex, or Verilog Hex format; however, GDB |
| can only append to binary files, and cannot read from Verilog Hex files. |
| |
| 'dump [FORMAT] memory FILENAME START_ADDR END_ADDR' |
| 'dump [FORMAT] value FILENAME EXPR' |
| Dump the contents of memory from START_ADDR to END_ADDR, or the |
| value of EXPR, to FILENAME in the given format. |
| |
| The FORMAT parameter may be any one of: |
| 'binary' |
| Raw binary form. |
| 'ihex' |
| Intel hex format. |
| 'srec' |
| Motorola S-record format. |
| 'tekhex' |
| Tektronix Hex format. |
| 'verilog' |
| Verilog Hex format. |
| |
| GDB uses the same definitions of these formats as the GNU binary |
| utilities, like 'objdump' and 'objcopy'. If FORMAT is omitted, GDB |
| dumps the data in raw binary form. |
| |
| 'append [binary] memory FILENAME START_ADDR END_ADDR' |
| 'append [binary] value FILENAME EXPR' |
| Append the contents of memory from START_ADDR to END_ADDR, or the |
| value of EXPR, to the file FILENAME, in raw binary form. (GDB can |
| only append data to files in raw binary form.) |
| |
| 'restore FILENAME [binary] BIAS START END' |
| Restore the contents of file FILENAME into memory. The 'restore' |
| command can automatically recognize any known BFD file format, |
| except for raw binary. To restore a raw binary file you must |
| specify the optional keyword 'binary' after the filename. |
| |
| If BIAS is non-zero, its value will be added to the addresses |
| contained in the file. Binary files always start at address zero, |
| so they will be restored at address BIAS. Other bfd files have a |
| built-in location; they will be restored at offset BIAS from that |
| location. |
| |
| If START and/or END are non-zero, then only data between file |
| offset START and file offset END will be restored. These offsets |
| are relative to the addresses in the file, before the BIAS argument |
| is applied. |
| |
| |
| File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data |
| |
| 10.19 How to Produce a Core File from Your Program |
| ================================================== |
| |
| A "core file" or "core dump" is a file that records the memory image of |
| a running process and its process status (register values etc.). Its |
| primary use is post-mortem debugging of a program that crashed while it |
| ran outside a debugger. A program that crashes automatically produces a |
| core file, unless this feature is disabled by the user. *Note Files::, |
| for information on invoking GDB in the post-mortem debugging mode. |
| |
| Occasionally, you may wish to produce a core file of the program you |
| are debugging in order to preserve a snapshot of its state. GDB has a |
| special command for that. |
| |
| 'generate-core-file [FILE]' |
| 'gcore [FILE]' |
| Produce a core dump of the inferior process. The optional argument |
| FILE specifies the file name where to put the core dump. If not |
| specified, the file name defaults to 'core.PID', where PID is the |
| inferior process ID. |
| |
| Note that this command is implemented only for some systems (as of |
| this writing, GNU/Linux, FreeBSD, Solaris, and S390). |
| |
| On GNU/Linux, this command can take into account the value of the |
| file '/proc/PID/coredump_filter' when generating the core dump |
| (*note set use-coredump-filter::). |
| |
| 'set use-coredump-filter on' |
| 'set use-coredump-filter off' |
| Enable or disable the use of the file '/proc/PID/coredump_filter' |
| when generating core dump files. This file is used by the Linux |
| kernel to decide what types of memory mappings will be dumped or |
| ignored when generating a core dump file. PID is the process ID of |
| a currently running process. |
| |
| To make use of this feature, you have to write in the |
| '/proc/PID/coredump_filter' file a value, in hexadecimal, which is |
| a bit mask representing the memory mapping types. If a bit is set |
| in the bit mask, then the memory mappings of the corresponding |
| types will be dumped; otherwise, they will be ignored. This |
| configuration is inherited by child processes. For more |
| information about the bits that can be set in the |
| '/proc/PID/coredump_filter' file, please refer to the manpage of |
| 'core(5)'. |
| |
| By default, this option is 'on'. If this option is turned 'off', |
| GDB does not read the 'coredump_filter' file and instead uses the |
| same default value as the Linux kernel in order to decide which |
| pages will be dumped in the core dump file. This value is |
| currently '0x33', which means that bits '0' (anonymous private |
| mappings), '1' (anonymous shared mappings), '4' (ELF headers) and |
| '5' (private huge pages) are active. This will cause these memory |
| mappings to be dumped automatically. |
| |
| |
| File: gdb.info, Node: Character Sets, Next: Caching Target Data, Prev: Core File Generation, Up: Data |
| |
| 10.20 Character Sets |
| ==================== |
| |
| If the program you are debugging uses a different character set to |
| represent characters and strings than the one GDB uses itself, GDB can |
| automatically translate between the character sets for you. The |
| character set GDB uses we call the "host character set"; the one the |
| inferior program uses we call the "target character set". |
| |
| For example, if you are running GDB on a GNU/Linux system, which uses |
| the ISO Latin 1 character set, but you are using GDB's remote protocol |
| (*note Remote Debugging::) to debug a program running on an IBM |
| mainframe, which uses the EBCDIC character set, then the host character |
| set is Latin-1, and the target character set is EBCDIC. If you give GDB |
| the command 'set target-charset EBCDIC-US', then GDB translates between |
| EBCDIC and Latin 1 as you print character or string values, or use |
| character and string literals in expressions. |
| |
| GDB has no way to automatically recognize which character set the |
| inferior program uses; you must tell it, using the 'set target-charset' |
| command, described below. |
| |
| Here are the commands for controlling GDB's character set support: |
| |
| 'set target-charset CHARSET' |
| Set the current target character set to CHARSET. To display the |
| list of supported target character sets, type |
| 'set target-charset <TAB><TAB>'. |
| |
| 'set host-charset CHARSET' |
| Set the current host character set to CHARSET. |
| |
| By default, GDB uses a host character set appropriate to the system |
| it is running on; you can override that default using the 'set |
| host-charset' command. On some systems, GDB cannot automatically |
| determine the appropriate host character set. In this case, GDB |
| uses 'UTF-8'. |
| |
| GDB can only use certain character sets as its host character set. |
| If you type 'set host-charset <TAB><TAB>', GDB will list the host |
| character sets it supports. |
| |
| 'set charset CHARSET' |
| Set the current host and target character sets to CHARSET. As |
| above, if you type 'set charset <TAB><TAB>', GDB will list the |
| names of the character sets that can be used for both host and |
| target. |
| |
| 'show charset' |
| Show the names of the current host and target character sets. |
| |
| 'show host-charset' |
| Show the name of the current host character set. |
| |
| 'show target-charset' |
| Show the name of the current target character set. |
| |
| 'set target-wide-charset CHARSET' |
| Set the current target's wide character set to CHARSET. This is |
| the character set used by the target's 'wchar_t' type. To display |
| the list of supported wide character sets, type |
| 'set target-wide-charset <TAB><TAB>'. |
| |
| 'show target-wide-charset' |
| Show the name of the current target's wide character set. |
| |
| Here is an example of GDB's character set support in action. Assume |
| that the following source code has been placed in the file |
| 'charset-test.c': |
| |
| #include <stdio.h> |
| |
| char ascii_hello[] |
| = {72, 101, 108, 108, 111, 44, 32, 119, |
| 111, 114, 108, 100, 33, 10, 0}; |
| char ibm1047_hello[] |
| = {200, 133, 147, 147, 150, 107, 64, 166, |
| 150, 153, 147, 132, 90, 37, 0}; |
| |
| main () |
| { |
| printf ("Hello, world!\n"); |
| } |
| |
| In this program, 'ascii_hello' and 'ibm1047_hello' are arrays |
| containing the string 'Hello, world!' followed by a newline, encoded in |
| the ASCII and IBM1047 character sets. |
| |
| We compile the program, and invoke the debugger on it: |
| |
| $ gcc -g charset-test.c -o charset-test |
| $ gdb -nw charset-test |
| GNU gdb 2001-12-19-cvs |
| Copyright 2001 Free Software Foundation, Inc. |
| ... |
| (gdb) |
| |
| We can use the 'show charset' command to see what character sets GDB |
| is currently using to interpret and display characters and strings: |
| |
| (gdb) show charset |
| The current host and target character set is `ISO-8859-1'. |
| (gdb) |
| |
| For the sake of printing this manual, let's use ASCII as our initial |
| character set: |
| (gdb) set charset ASCII |
| (gdb) show charset |
| The current host and target character set is `ASCII'. |
| (gdb) |
| |
| Let's assume that ASCII is indeed the correct character set for our |
| host system -- in other words, let's assume that if GDB prints |
| characters using the ASCII character set, our terminal will display them |
| properly. Since our current target character set is also ASCII, the |
| contents of 'ascii_hello' print legibly: |
| |
| (gdb) print ascii_hello |
| $1 = 0x401698 "Hello, world!\n" |
| (gdb) print ascii_hello[0] |
| $2 = 72 'H' |
| (gdb) |
| |
| GDB uses the target character set for character and string literals |
| you use in expressions: |
| |
| (gdb) print '+' |
| $3 = 43 '+' |
| (gdb) |
| |
| The ASCII character set uses the number 43 to encode the '+' |
| character. |
| |
| GDB relies on the user to tell it which character set the target |
| program uses. If we print 'ibm1047_hello' while our target character |
| set is still ASCII, we get jibberish: |
| |
| (gdb) print ibm1047_hello |
| $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%" |
| (gdb) print ibm1047_hello[0] |
| $5 = 200 '\310' |
| (gdb) |
| |
| If we invoke the 'set target-charset' followed by <TAB><TAB>, GDB |
| tells us the character sets it supports: |
| |
| (gdb) set target-charset |
| ASCII EBCDIC-US IBM1047 ISO-8859-1 |
| (gdb) set target-charset |
| |
| We can select IBM1047 as our target character set, and examine the |
| program's strings again. Now the ASCII string is wrong, but GDB |
| translates the contents of 'ibm1047_hello' from the target character |
| set, IBM1047, to the host character set, ASCII, and they display |
| correctly: |
| |
| (gdb) set target-charset IBM1047 |
| (gdb) show charset |
| The current host character set is `ASCII'. |
| The current target character set is `IBM1047'. |
| (gdb) print ascii_hello |
| $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" |
| (gdb) print ascii_hello[0] |
| $7 = 72 '\110' |
| (gdb) print ibm1047_hello |
| $8 = 0x4016a8 "Hello, world!\n" |
| (gdb) print ibm1047_hello[0] |
| $9 = 200 'H' |
| (gdb) |
| |
| As above, GDB uses the target character set for character and string |
| literals you use in expressions: |
| |
| (gdb) print '+' |
| $10 = 78 '+' |
| (gdb) |
| |
| The IBM1047 character set uses the number 78 to encode the '+' |
| character. |
| |
| |
| File: gdb.info, Node: Caching Target Data, Next: Searching Memory, Prev: Character Sets, Up: Data |
| |
| 10.21 Caching Data of Targets |
| ============================= |
| |
| GDB caches data exchanged between the debugger and a target. Each cache |
| is associated with the address space of the inferior. *Note Inferiors |
| and Programs::, about inferior and address space. Such caching |
| generally improves performance in remote debugging (*note Remote |
| Debugging::), because it reduces the overhead of the remote protocol by |
| bundling memory reads and writes into large chunks. Unfortunately, |
| simply caching everything would lead to incorrect results, since GDB |
| does not necessarily know anything about volatile values, memory-mapped |
| I/O addresses, etc. Furthermore, in non-stop mode (*note Non-Stop |
| Mode::) memory can be changed _while_ a gdb command is executing. |
| Therefore, by default, GDB only caches data known to be on the stack(1) |
| or in the code segment. Other regions of memory can be explicitly |
| marked as cacheable; *note Memory Region Attributes::. |
| |
| 'set remotecache on' |
| 'set remotecache off' |
| This option no longer does anything; it exists for compatibility |
| with old scripts. |
| |
| 'show remotecache' |
| Show the current state of the obsolete remotecache flag. |
| |
| 'set stack-cache on' |
| 'set stack-cache off' |
| Enable or disable caching of stack accesses. When 'on', use |
| caching. By default, this option is 'on'. |
| |
| 'show stack-cache' |
| Show the current state of data caching for memory accesses. |
| |
| 'set code-cache on' |
| 'set code-cache off' |
| Enable or disable caching of code segment accesses. When 'on', use |
| caching. By default, this option is 'on'. This improves |
| performance of disassembly in remote debugging. |
| |
| 'show code-cache' |
| Show the current state of target memory cache for code segment |
| accesses. |
| |
| 'info dcache [line]' |
| Print the information about the performance of data cache of the |
| current inferior's address space. The information displayed |
| includes the dcache width and depth, and for each cache line, its |
| number, address, and how many times it was referenced. This |
| command is useful for debugging the data cache operation. |
| |
| If a line number is specified, the contents of that line will be |
| printed in hex. |
| |
| 'set dcache size SIZE' |
| Set maximum number of entries in dcache (dcache depth above). |
| |
| 'set dcache line-size LINE-SIZE' |
| Set number of bytes each dcache entry caches (dcache width above). |
| Must be a power of 2. |
| |
| 'show dcache size' |
| Show maximum number of dcache entries. *Note info dcache: Caching |
| Target Data. |
| |
| 'show dcache line-size' |
| Show default size of dcache lines. |
| |
| ---------- Footnotes ---------- |
| |
| (1) In non-stop mode, it is moderately rare for a running thread to |
| modify the stack of a stopped thread in a way that would interfere with |
| a backtrace, and caching of stack reads provides a significant speed up |
| of remote backtraces. |
| |
| |
| File: gdb.info, Node: Searching Memory, Prev: Caching Target Data, Up: Data |
| |
| 10.22 Search Memory |
| =================== |
| |
| Memory can be searched for a particular sequence of bytes with the |
| 'find' command. |
| |
| 'find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]' |
| 'find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]' |
| Search memory for the sequence of bytes specified by VAL1, VAL2, |
| etc. The search begins at address START_ADDR and continues for |
| either LEN bytes or through to END_ADDR inclusive. |
| |
| S and N are optional parameters. They may be specified in either |
| order, apart or together. |
| |
| S, search query size |
| The size of each search query value. |
| |
| 'b' |
| bytes |
| 'h' |
| halfwords (two bytes) |
| 'w' |
| words (four bytes) |
| 'g' |
| giant words (eight bytes) |
| |
| All values are interpreted in the current language. This means, |
| for example, that if the current source language is C/C++ then |
| searching for the string "hello" includes the trailing '\0'. |
| |
| If the value size is not specified, it is taken from the value's |
| type in the current language. This is useful when one wants to |
| specify the search pattern as a mixture of types. Note that this |
| means, for example, that in the case of C-like languages a search |
| for an untyped 0x42 will search for '(int) 0x42' which is typically |
| four bytes. |
| |
| N, maximum number of finds |
| The maximum number of matches to print. The default is to print |
| all finds. |
| |
| You can use strings as search values. Quote them with double-quotes |
| ('"'). The string value is copied into the search pattern byte by byte, |
| regardless of the endianness of the target and the size specification. |
| |
| The address of each match found is printed as well as a count of the |
| number of matches found. |
| |
| The address of the last value found is stored in convenience variable |
| '$_'. A count of the number of matches is stored in '$numfound'. |
| |
| For example, if stopped at the 'printf' in this function: |
| |
| void |
| hello () |
| { |
| static char hello[] = "hello-hello"; |
| static struct { char c; short s; int i; } |
| __attribute__ ((packed)) mixed |
| = { 'c', 0x1234, 0x87654321 }; |
| printf ("%s\n", hello); |
| } |
| |
| you get during debugging: |
| |
| (gdb) find &hello[0], +sizeof(hello), "hello" |
| 0x804956d <hello.1620+6> |
| 1 pattern found |
| (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' |
| 0x8049567 <hello.1620> |
| 0x804956d <hello.1620+6> |
| 2 patterns found |
| (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' |
| 0x8049567 <hello.1620> |
| 1 pattern found |
| (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 |
| 0x8049560 <mixed.1625> |
| 1 pattern found |
| (gdb) print $numfound |
| $1 = 1 |
| (gdb) print $_ |
| $2 = (void *) 0x8049560 |
| |
| |
| File: gdb.info, Node: Optimized Code, Next: Macros, Prev: Data, Up: Top |
| |
| 11 Debugging Optimized Code |
| *************************** |
| |
| Almost all compilers support optimization. With optimization disabled, |
| the compiler generates assembly code that corresponds directly to your |
| source code, in a simplistic way. As the compiler applies more powerful |
| optimizations, the generated assembly code diverges from your original |
| source code. With help from debugging information generated by the |
| compiler, GDB can map from the running program back to constructs from |
| your original source. |
| |
| GDB is more accurate with optimization disabled. If you can |
| recompile without optimization, it is easier to follow the progress of |
| your program during debugging. But, there are many cases where you may |
| need to debug an optimized version. |
| |
| When you debug a program compiled with '-g -O', remember that the |
| optimizer has rearranged your code; the debugger shows you what is |
| really there. Do not be too surprised when the execution path does not |
| exactly match your source file! An extreme example: if you define a |
| variable, but never use it, GDB never sees that variable--because the |
| compiler optimizes it out of existence. |
| |
| Some things do not work as well with '-g -O' as with just '-g', |
| particularly on machines with instruction scheduling. If in doubt, |
| recompile with '-g' alone, and if this fixes the problem, please report |
| it to us as a bug (including a test case!). *Note Variables::, for more |
| information about debugging optimized code. |
| |
| * Menu: |
| |
| * Inline Functions:: How GDB presents inlining |
| * Tail Call Frames:: GDB analysis of jumps to functions |
| |
| |
| File: gdb.info, Node: Inline Functions, Next: Tail Call Frames, Up: Optimized Code |
| |
| 11.1 Inline Functions |
| ===================== |
| |
| "Inlining" is an optimization that inserts a copy of the function body |
| directly at each call site, instead of jumping to a shared routine. GDB |
| displays inlined functions just like non-inlined functions. They appear |
| in backtraces. You can view their arguments and local variables, step |
| into them with 'step', skip them with 'next', and escape from them with |
| 'finish'. You can check whether a function was inlined by using the |
| 'info frame' command. |
| |
| For GDB to support inlined functions, the compiler must record |
| information about inlining in the debug information -- GCC using the |
| DWARF 2 format does this, and several other compilers do also. GDB only |
| supports inlined functions when using DWARF 2. Versions of GCC before |
| 4.1 do not emit two required attributes ('DW_AT_call_file' and |
| 'DW_AT_call_line'); GDB does not display inlined function calls with |
| earlier versions of GCC. It instead displays the arguments and local |
| variables of inlined functions as local variables in the caller. |
| |
| The body of an inlined function is directly included at its call |
| site; unlike a non-inlined function, there are no instructions devoted |
| to the call. GDB still pretends that the call site and the start of the |
| inlined function are different instructions. Stepping to the call site |
| shows the call site, and then stepping again shows the first line of the |
| inlined function, even though no additional instructions are executed. |
| |
| This makes source-level debugging much clearer; you can see both the |
| context of the call and then the effect of the call. Only stepping by a |
| single instruction using 'stepi' or 'nexti' does not do this; single |
| instruction steps always show the inlined body. |
| |
| There are some ways that GDB does not pretend that inlined function |
| calls are the same as normal calls: |
| |
| * Setting breakpoints at the call site of an inlined function may not |
| work, because the call site does not contain any code. GDB may |
| incorrectly move the breakpoint to the next line of the enclosing |
| function, after the call. This limitation will be removed in a |
| future version of GDB; until then, set a breakpoint on an earlier |
| line or inside the inlined function instead. |
| |
| * GDB cannot locate the return value of inlined calls after using the |
| 'finish' command. This is a limitation of compiler-generated |
| debugging information; after 'finish', you can step to the next |
| line and print a variable where your program stored the return |
| value. |
| |
| |
| File: gdb.info, Node: Tail Call Frames, Prev: Inline Functions, Up: Optimized Code |
| |
| 11.2 Tail Call Frames |
| ===================== |
| |
| Function 'B' can call function 'C' in its very last statement. In |
| unoptimized compilation the call of 'C' is immediately followed by |
| return instruction at the end of 'B' code. Optimizing compiler may |
| replace the call and return in function 'B' into one jump to function |
| 'C' instead. Such use of a jump instruction is called "tail call". |
| |
| During execution of function 'C', there will be no indication in the |
| function call stack frames that it was tail-called from 'B'. If |
| function 'A' regularly calls function 'B' which tail-calls function 'C', |
| then GDB will see 'A' as the caller of 'C'. However, in some cases GDB |
| can determine that 'C' was tail-called from 'B', and it will then create |
| fictitious call frame for that, with the return address set up as if 'B' |
| called 'C' normally. |
| |
| This functionality is currently supported only by DWARF 2 debugging |
| format and the compiler has to produce 'DW_TAG_GNU_call_site' tags. |
| With GCC, you need to specify '-O -g' during compilation, to get this |
| information. |
| |
| 'info frame' command (*note Frame Info::) will indicate the tail call |
| frame kind by text 'tail call frame' such as in this sample GDB output: |
| |
| (gdb) x/i $pc - 2 |
| 0x40066b <b(int, double)+11>: jmp 0x400640 <c(int, double)> |
| (gdb) info frame |
| Stack level 1, frame at 0x7fffffffda30: |
| rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 |
| tail call frame, caller of frame at 0x7fffffffda30 |
| source language c++. |
| Arglist at unknown address. |
| Locals at unknown address, Previous frame's sp is 0x7fffffffda30 |
| |
| The detection of all the possible code path executions can find them |
| ambiguous. There is no execution history stored (possible *note Reverse |
| Execution:: is never used for this purpose) and the last known caller |
| could have reached the known callee by multiple different jump |
| sequences. In such case GDB still tries to show at least all the |
| unambiguous top tail callers and all the unambiguous bottom tail calees, |
| if any. |
| |
| 'set debug entry-values' |
| When set to on, enables printing of analysis messages for both |
| frame argument values at function entry and tail calls. It will |
| show all the possible valid tail calls code paths it has |
| considered. It will also print the intersection of them with the |
| final unambiguous (possibly partial or even empty) code path |
| result. |
| |
| 'show debug entry-values' |
| Show the current state of analysis messages printing for both frame |
| argument values at function entry and tail calls. |
| |
| The analysis messages for tail calls can for example show why the |
| virtual tail call frame for function 'c' has not been recognized (due to |
| the indirect reference by variable 'x'): |
| |
| static void __attribute__((noinline, noclone)) c (void); |
| void (*x) (void) = c; |
| static void __attribute__((noinline, noclone)) a (void) { x++; } |
| static void __attribute__((noinline, noclone)) c (void) { a (); } |
| int main (void) { x (); return 0; } |
| |
| Breakpoint 1, DW_OP_GNU_entry_value resolving cannot find |
| DW_TAG_GNU_call_site 0x40039a in main |
| a () at t.c:3 |
| 3 static void __attribute__((noinline, noclone)) a (void) { x++; } |
| (gdb) bt |
| #0 a () at t.c:3 |
| #1 0x000000000040039a in main () at t.c:5 |
| |
| Another possibility is an ambiguous virtual tail call frames |
| resolution: |
| |
| int i; |
| static void __attribute__((noinline, noclone)) f (void) { i++; } |
| static void __attribute__((noinline, noclone)) e (void) { f (); } |
| static void __attribute__((noinline, noclone)) d (void) { f (); } |
| static void __attribute__((noinline, noclone)) c (void) { d (); } |
| static void __attribute__((noinline, noclone)) b (void) |
| { if (i) c (); else e (); } |
| static void __attribute__((noinline, noclone)) a (void) { b (); } |
| int main (void) { a (); return 0; } |
| |
| tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d) |
| tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e) |
| tailcall: reduced: 0x4004d2(a) | |
| (gdb) bt |
| #0 f () at t.c:2 |
| #1 0x00000000004004d2 in a () at t.c:8 |
| #2 0x0000000000400395 in main () at t.c:9 |
| |
| Frames #0 and #2 are real, #1 is a virtual tail call frame. The code |
| can have possible execution paths 'main->a->b->c->d->f' or |
| 'main->a->b->e->f', GDB cannot find which one from the inferior state. |
| |
| 'initial:' state shows some random possible calling sequence GDB has |
| found. It then finds another possible calling sequcen - that one is |
| prefixed by 'compare:'. The non-ambiguous intersection of these two is |
| printed as the 'reduced:' calling sequence. That one could have many |
| futher 'compare:' and 'reduced:' statements as long as there remain any |
| non-ambiguous sequence entries. |
| |
| For the frame of function 'b' in both cases there are different |
| possible '$pc' values ('0x4004cc' or '0x4004ce'), therefore this frame |
| is also ambigous. The only non-ambiguous frame is the one for function |
| 'a', therefore this one is displayed to the user while the ambiguous |
| frames are omitted. |
| |
| There can be also reasons why printing of frame argument values at |
| function entry may fail: |
| |
| int v; |
| static void __attribute__((noinline, noclone)) c (int i) { v++; } |
| static void __attribute__((noinline, noclone)) a (int i); |
| static void __attribute__((noinline, noclone)) b (int i) { a (i); } |
| static void __attribute__((noinline, noclone)) a (int i) |
| { if (i) b (i - 1); else c (0); } |
| int main (void) { a (5); return 0; } |
| |
| (gdb) bt |
| #0 c (i=i@entry=0) at t.c:2 |
| #1 0x0000000000400428 in a (DW_OP_GNU_entry_value resolving has found |
| function "a" at 0x400420 can call itself via tail calls |
| i=<optimized out>) at t.c:6 |
| #2 0x000000000040036e in main () at t.c:7 |
| |
| GDB cannot find out from the inferior state if and how many times did |
| function 'a' call itself (via function 'b') as these calls would be tail |
| calls. Such tail calls would modify thue 'i' variable, therefore GDB |
| cannot be sure the value it knows would be right - GDB prints |
| '<optimized out>' instead. |
| |
| |
| File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Optimized Code, Up: Top |
| |
| 12 C Preprocessor Macros |
| ************************ |
| |
| Some languages, such as C and C++, provide a way to define and invoke |
| "preprocessor macros" which expand into strings of tokens. GDB can |
| evaluate expressions containing macro invocations, show the result of |
| macro expansion, and show a macro's definition, including where it was |
| defined. |
| |
| You may need to compile your program specially to provide GDB with |
| information about preprocessor macros. Most compilers do not include |
| macros in their debugging information, even when you compile with the |
| '-g' flag. *Note Compilation::. |
| |
| A program may define a macro at one point, remove that definition |
| later, and then provide a different definition after that. Thus, at |
| different points in the program, a macro may have different definitions, |
| or have no definition at all. If there is a current stack frame, GDB |
| uses the macros in scope at that frame's source code line. Otherwise, |
| GDB uses the macros in scope at the current listing location; see *note |
| List::. |
| |
| Whenever GDB evaluates an expression, it always expands any macro |
| invocations present in the expression. GDB also provides the following |
| commands for working with macros explicitly. |
| |
| 'macro expand EXPRESSION' |
| 'macro exp EXPRESSION' |
| Show the results of expanding all preprocessor macro invocations in |
| EXPRESSION. Since GDB simply expands macros, but does not parse |
| the result, EXPRESSION need not be a valid expression; it can be |
| any string of tokens. |
| |
| 'macro expand-once EXPRESSION' |
| 'macro exp1 EXPRESSION' |
| (This command is not yet implemented.) Show the results of |
| expanding those preprocessor macro invocations that appear |
| explicitly in EXPRESSION. Macro invocations appearing in that |
| expansion are left unchanged. This command allows you to see the |
| effect of a particular macro more clearly, without being confused |
| by further expansions. Since GDB simply expands macros, but does |
| not parse the result, EXPRESSION need not be a valid expression; it |
| can be any string of tokens. |
| |
| 'info macro [-a|-all] [--] MACRO' |
| Show the current definition or all definitions of the named MACRO, |
| and describe the source location or compiler command-line where |
| that definition was established. The optional double dash is to |
| signify the end of argument processing and the beginning of MACRO |
| for non C-like macros where the macro may begin with a hyphen. |
| |
| 'info macros LINESPEC' |
| Show all macro definitions that are in effect at the location |
| specified by LINESPEC, and describe the source location or compiler |
| command-line where those definitions were established. |
| |
| 'macro define MACRO REPLACEMENT-LIST' |
| 'macro define MACRO(ARGLIST) REPLACEMENT-LIST' |
| Introduce a definition for a preprocessor macro named MACRO, |
| invocations of which are replaced by the tokens given in |
| REPLACEMENT-LIST. The first form of this command defines an |
| "object-like" macro, which takes no arguments; the second form |
| defines a "function-like" macro, which takes the arguments given in |
| ARGLIST. |
| |
| A definition introduced by this command is in scope in every |
| expression evaluated in GDB, until it is removed with the 'macro |
| undef' command, described below. The definition overrides all |
| definitions for MACRO present in the program being debugged, as |
| well as any previous user-supplied definition. |
| |
| 'macro undef MACRO' |
| Remove any user-supplied definition for the macro named MACRO. |
| This command only affects definitions provided with the 'macro |
| define' command, described above; it cannot remove definitions |
| present in the program being debugged. |
| |
| 'macro list' |
| List all the macros defined using the 'macro define' command. |
| |
| Here is a transcript showing the above commands in action. First, we |
| show our source files: |
| |
| $ cat sample.c |
| #include <stdio.h> |
| #include "sample.h" |
| |
| #define M 42 |
| #define ADD(x) (M + x) |
| |
| main () |
| { |
| #define N 28 |
| printf ("Hello, world!\n"); |
| #undef N |
| printf ("We're so creative.\n"); |
| #define N 1729 |
| printf ("Goodbye, world!\n"); |
| } |
| $ cat sample.h |
| #define Q < |
| $ |
| |
| Now, we compile the program using the GNU C compiler, GCC. We pass |
| the '-gdwarf-2'(1) _and_ '-g3' flags to ensure the compiler includes |
| information about preprocessor macros in the debugging information. |
| |
| $ gcc -gdwarf-2 -g3 sample.c -o sample |
| $ |
| |
| Now, we start GDB on our sample program: |
| |
| $ gdb -nw sample |
| GNU gdb 2002-05-06-cvs |
| Copyright 2002 Free Software Foundation, Inc. |
| GDB is free software, ... |
| (gdb) |
| |
| We can expand macros and examine their definitions, even when the |
| program is not running. GDB uses the current listing position to decide |
| which macro definitions are in scope: |
| |
| (gdb) list main |
| 3 |
| 4 #define M 42 |
| 5 #define ADD(x) (M + x) |
| 6 |
| 7 main () |
| 8 { |
| 9 #define N 28 |
| 10 printf ("Hello, world!\n"); |
| 11 #undef N |
| 12 printf ("We're so creative.\n"); |
| (gdb) info macro ADD |
| Defined at /home/jimb/gdb/macros/play/sample.c:5 |
| #define ADD(x) (M + x) |
| (gdb) info macro Q |
| Defined at /home/jimb/gdb/macros/play/sample.h:1 |
| included at /home/jimb/gdb/macros/play/sample.c:2 |
| #define Q < |
| (gdb) macro expand ADD(1) |
| expands to: (42 + 1) |
| (gdb) macro expand-once ADD(1) |
| expands to: once (M + 1) |
| (gdb) |
| |
| In the example above, note that 'macro expand-once' expands only the |
| macro invocation explicit in the original text -- the invocation of |
| 'ADD' -- but does not expand the invocation of the macro 'M', which was |
| introduced by 'ADD'. |
| |
| Once the program is running, GDB uses the macro definitions in force |
| at the source line of the current stack frame: |
| |
| (gdb) break main |
| Breakpoint 1 at 0x8048370: file sample.c, line 10. |
| (gdb) run |
| Starting program: /home/jimb/gdb/macros/play/sample |
| |
| Breakpoint 1, main () at sample.c:10 |
| 10 printf ("Hello, world!\n"); |
| (gdb) |
| |
| At line 10, the definition of the macro 'N' at line 9 is in force: |
| |
| (gdb) info macro N |
| Defined at /home/jimb/gdb/macros/play/sample.c:9 |
| #define N 28 |
| (gdb) macro expand N Q M |
| expands to: 28 < 42 |
| (gdb) print N Q M |
| $1 = 1 |
| (gdb) |
| |
| As we step over directives that remove 'N''s definition, and then |
| give it a new definition, GDB finds the definition (or lack thereof) in |
| force at each point: |
| |
| (gdb) next |
| Hello, world! |
| 12 printf ("We're so creative.\n"); |
| (gdb) info macro N |
| The symbol `N' has no definition as a C/C++ preprocessor macro |
| at /home/jimb/gdb/macros/play/sample.c:12 |
| (gdb) next |
| We're so creative. |
| 14 printf ("Goodbye, world!\n"); |
| (gdb) info macro N |
| Defined at /home/jimb/gdb/macros/play/sample.c:13 |
| #define N 1729 |
| (gdb) macro expand N Q M |
| expands to: 1729 < 42 |
| (gdb) print N Q M |
| $2 = 0 |
| (gdb) |
| |
| In addition to source files, macros can be defined on the compilation |
| command line using the '-DNAME=VALUE' syntax. For macros defined in |
| such a way, GDB displays the location of their definition as line zero |
| of the source file submitted to the compiler. |
| |
| (gdb) info macro __STDC__ |
| Defined at /home/jimb/gdb/macros/play/sample.c:0 |
| -D__STDC__=1 |
| (gdb) |
| |
| ---------- Footnotes ---------- |
| |
| (1) This is the minimum. Recent versions of GCC support '-gdwarf-3' |
| and '-gdwarf-4'; we recommend always choosing the most recent version of |
| DWARF. |
| |
| |
| File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top |
| |
| 13 Tracepoints |
| ************** |
| |
| In some applications, it is not feasible for the debugger to interrupt |
| the program's execution long enough for the developer to learn anything |
| helpful about its behavior. If the program's correctness depends on its |
| real-time behavior, delays introduced by a debugger might cause the |
| program to change its behavior drastically, or perhaps fail, even when |
| the code itself is correct. It is useful to be able to observe the |
| program's behavior without interrupting it. |
| |
| Using GDB's 'trace' and 'collect' commands, you can specify locations |
| in the program, called "tracepoints", and arbitrary expressions to |
| evaluate when those tracepoints are reached. Later, using the 'tfind' |
| command, you can examine the values those expressions had when the |
| program hit the tracepoints. The expressions may also denote objects in |
| memory--structures or arrays, for example--whose values GDB should |
| record; while visiting a particular tracepoint, you may inspect those |
| objects as if they were in memory at that moment. However, because GDB |
| records these values without interacting with you, it can do so quickly |
| and unobtrusively, hopefully not disturbing the program's behavior. |
| |
| The tracepoint facility is currently available only for remote |
| targets. *Note Targets::. In addition, your remote target must know |
| how to collect trace data. This functionality is implemented in the |
| remote stub; however, none of the stubs distributed with GDB support |
| tracepoints as of this writing. The format of the remote packets used |
| to implement tracepoints are described in *note Tracepoint Packets::. |
| |
| It is also possible to get trace data from a file, in a manner |
| reminiscent of corefiles; you specify the filename, and use 'tfind' to |
| search through the file. *Note Trace Files::, for more details. |
| |
| This chapter describes the tracepoint commands and features. |
| |
| * Menu: |
| |
| * Set Tracepoints:: |
| * Analyze Collected Data:: |
| * Tracepoint Variables:: |
| * Trace Files:: |
| |
| |
| File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints |
| |
| 13.1 Commands to Set Tracepoints |
| ================================ |
| |
| Before running such a "trace experiment", an arbitrary number of |
| tracepoints can be set. A tracepoint is actually a special type of |
| breakpoint (*note Set Breaks::), so you can manipulate it using standard |
| breakpoint commands. For instance, as with breakpoints, tracepoint |
| numbers are successive integers starting from one, and many of the |
| commands associated with tracepoints take the tracepoint number as their |
| argument, to identify which tracepoint to work on. |
| |
| For each tracepoint, you can specify, in advance, some arbitrary set |
| of data that you want the target to collect in the trace buffer when it |
| hits that tracepoint. The collected data can include registers, local |
| variables, or global data. Later, you can use GDB commands to examine |
| the values these data had at the time the tracepoint was hit. |
| |
| Tracepoints do not support every breakpoint feature. Ignore counts |
| on tracepoints have no effect, and tracepoints cannot run GDB commands |
| when they are hit. Tracepoints may not be thread-specific either. |
| |
| Some targets may support "fast tracepoints", which are inserted in a |
| different way (such as with a jump instead of a trap), that is faster |
| but possibly restricted in where they may be installed. |
| |
| Regular and fast tracepoints are dynamic tracing facilities, meaning |
| that they can be used to insert tracepoints at (almost) any location in |
| the target. Some targets may also support controlling "static |
| tracepoints" from GDB. With static tracing, a set of instrumentation |
| points, also known as "markers", are embedded in the target program, and |
| can be activated or deactivated by name or address. These are usually |
| placed at locations which facilitate investigating what the target is |
| actually doing. GDB's support for static tracing includes being able to |
| list instrumentation points, and attach them with GDB defined high level |
| tracepoints that expose the whole range of convenience of GDB's |
| tracepoints support. Namely, support for collecting registers values |
| and values of global or local (to the instrumentation point) variables; |
| tracepoint conditions and trace state variables. The act of installing |
| a GDB static tracepoint on an instrumentation point, or marker, is |
| referred to as "probing" a static tracepoint marker. |
| |
| 'gdbserver' supports tracepoints on some target systems. *Note |
| Tracepoints support in 'gdbserver': Server. |
| |
| This section describes commands to set tracepoints and associated |
| conditions and actions. |
| |
| * Menu: |
| |
| * Create and Delete Tracepoints:: |
| * Enable and Disable Tracepoints:: |
| * Tracepoint Passcounts:: |
| * Tracepoint Conditions:: |
| * Trace State Variables:: |
| * Tracepoint Actions:: |
| * Listing Tracepoints:: |
| * Listing Static Tracepoint Markers:: |
| * Starting and Stopping Trace Experiments:: |
| * Tracepoint Restrictions:: |
| |
| |
| File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints |
| |
| 13.1.1 Create and Delete Tracepoints |
| ------------------------------------ |
| |
| 'trace LOCATION' |
| The 'trace' command is very similar to the 'break' command. Its |
| argument LOCATION can be a source line, a function name, or an |
| address in the target program. *Note Specify Location::. The |
| 'trace' command defines a tracepoint, which is a point in the |
| target program where the debugger will briefly stop, collect some |
| data, and then allow the program to continue. Setting a tracepoint |
| or changing its actions takes effect immediately if the remote stub |
| supports the 'InstallInTrace' feature (*note install tracepoint in |
| tracing::). If remote stub doesn't support the 'InstallInTrace' |
| feature, all these changes don't take effect until the next |
| 'tstart' command, and once a trace experiment is running, further |
| changes will not have any effect until the next trace experiment |
| starts. In addition, GDB supports "pending |
| tracepoints"--tracepoints whose address is not yet resolved. (This |
| is similar to pending breakpoints.) Pending tracepoints are not |
| downloaded to the target and not installed until they are resolved. |
| The resolution of pending tracepoints requires GDB support--when |
| debugging with the remote target, and GDB disconnects from the |
| remote stub (*note disconnected tracing::), pending tracepoints can |
| not be resolved (and downloaded to the remote stub) while GDB is |
| disconnected. |
| |
| Here are some examples of using the 'trace' command: |
| |
| (gdb) trace foo.c:121 // a source file and line number |
| |
| (gdb) trace +2 // 2 lines forward |
| |
| (gdb) trace my_function // first source line of function |
| |
| (gdb) trace *my_function // EXACT start address of function |
| |
| (gdb) trace *0x2117c4 // an address |
| |
| You can abbreviate 'trace' as 'tr'. |
| |
| 'trace LOCATION if COND' |
| Set a tracepoint with condition COND; evaluate the expression COND |
| each time the tracepoint is reached, and collect data only if the |
| value is nonzero--that is, if COND evaluates as true. *Note |
| Tracepoint Conditions: Tracepoint Conditions, for more information |
| on tracepoint conditions. |
| |
| 'ftrace LOCATION [ if COND ]' |
| The 'ftrace' command sets a fast tracepoint. For targets that |
| support them, fast tracepoints will use a more efficient but |
| possibly less general technique to trigger data collection, such as |
| a jump instruction instead of a trap, or some sort of hardware |
| support. It may not be possible to create a fast tracepoint at the |
| desired location, in which case the command will exit with an |
| explanatory message. |
| |
| GDB handles arguments to 'ftrace' exactly as for 'trace'. |
| |
| On 32-bit x86-architecture systems, fast tracepoints normally need |
| to be placed at an instruction that is 5 bytes or longer, but can |
| be placed at 4-byte instructions if the low 64K of memory of the |
| target program is available to install trampolines. Some Unix-type |
| systems, such as GNU/Linux, exclude low addresses from the |
| program's address space; but for instance with the Linux kernel it |
| is possible to let GDB use this area by doing a 'sysctl' command to |
| set the 'mmap_min_addr' kernel parameter, as in |
| |
| sudo sysctl -w vm.mmap_min_addr=32768 |
| |
| which sets the low address to 32K, which leaves plenty of room for |
| trampolines. The minimum address should be set to a page boundary. |
| |
| 'strace LOCATION [ if COND ]' |
| The 'strace' command sets a static tracepoint. For targets that |
| support it, setting a static tracepoint probes a static |
| instrumentation point, or marker, found at LOCATION. It may not be |
| possible to set a static tracepoint at the desired location, in |
| which case the command will exit with an explanatory message. |
| |
| GDB handles arguments to 'strace' exactly as for 'trace', with the |
| addition that the user can also specify '-m MARKER' as LOCATION. |
| This probes the marker identified by the MARKER string identifier. |
| This identifier depends on the static tracepoint backend library |
| your program is using. You can find all the marker identifiers in |
| the 'ID' field of the 'info static-tracepoint-markers' command |
| output. *Note Listing Static Tracepoint Markers: Listing Static |
| Tracepoint Markers. For example, in the following small program |
| using the UST tracing engine: |
| |
| main () |
| { |
| trace_mark(ust, bar33, "str %s", "FOOBAZ"); |
| } |
| |
| the marker id is composed of joining the first two arguments to the |
| 'trace_mark' call with a slash, which translates to: |
| |
| (gdb) info static-tracepoint-markers |
| Cnt Enb ID Address What |
| 1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 |
| Data: "str %s" |
| [etc...] |
| |
| so you may probe the marker above with: |
| |
| (gdb) strace -m ust/bar33 |
| |
| Static tracepoints accept an extra collect action -- 'collect |
| $_sdata'. This collects arbitrary user data passed in the probe |
| point call to the tracing library. In the UST example above, |
| you'll see that the third argument to 'trace_mark' is a printf-like |
| format string. The user data is then the result of running that |
| formating string against the following arguments. Note that 'info |
| static-tracepoint-markers' command output lists that format string |
| in the 'Data:' field. |
| |
| You can inspect this data when analyzing the trace buffer, by |
| printing the $_sdata variable like any other variable available to |
| GDB. *Note Tracepoint Action Lists: Tracepoint Actions. |
| |
| The convenience variable '$tpnum' records the tracepoint number of |
| the most recently set tracepoint. |
| |
| 'delete tracepoint [NUM]' |
| Permanently delete one or more tracepoints. With no argument, the |
| default is to delete all tracepoints. Note that the regular |
| 'delete' command can remove tracepoints also. |
| |
| Examples: |
| |
| (gdb) delete trace 1 2 3 // remove three tracepoints |
| |
| (gdb) delete trace // remove all tracepoints |
| |
| You can abbreviate this command as 'del tr'. |
| |
| |
| File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints |
| |
| 13.1.2 Enable and Disable Tracepoints |
| ------------------------------------- |
| |
| These commands are deprecated; they are equivalent to plain 'disable' |
| and 'enable'. |
| |
| 'disable tracepoint [NUM]' |
| Disable tracepoint NUM, or all tracepoints if no argument NUM is |
| given. A disabled tracepoint will have no effect during a trace |
| experiment, but it is not forgotten. You can re-enable a disabled |
| tracepoint using the 'enable tracepoint' command. If the command |
| is issued during a trace experiment and the debug target has |
| support for disabling tracepoints during a trace experiment, then |
| the change will be effective immediately. Otherwise, it will be |
| applied to the next trace experiment. |
| |
| 'enable tracepoint [NUM]' |
| Enable tracepoint NUM, or all tracepoints. If this command is |
| issued during a trace experiment and the debug target supports |
| enabling tracepoints during a trace experiment, then the enabled |
| tracepoints will become effective immediately. Otherwise, they |
| will become effective the next time a trace experiment is run. |
| |
| |
| File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Conditions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints |
| |
| 13.1.3 Tracepoint Passcounts |
| ---------------------------- |
| |
| 'passcount [N [NUM]]' |
| Set the "passcount" of a tracepoint. The passcount is a way to |
| automatically stop a trace experiment. If a tracepoint's passcount |
| is N, then the trace experiment will be automatically stopped on |
| the N'th time that tracepoint is hit. If the tracepoint number NUM |
| is not specified, the 'passcount' command sets the passcount of the |
| most recently defined tracepoint. If no passcount is given, the |
| trace experiment will run until stopped explicitly by the user. |
| |
| Examples: |
| |
| (gdb) passcount 5 2 // Stop on the 5th execution of |
| // tracepoint 2 |
| |
| (gdb) passcount 12 // Stop on the 12th execution of the |
| // most recently defined tracepoint. |
| (gdb) trace foo |
| (gdb) pass 3 |
| (gdb) trace bar |
| (gdb) pass 2 |
| (gdb) trace baz |
| (gdb) pass 1 // Stop tracing when foo has been |
| // executed 3 times OR when bar has |
| // been executed 2 times |
| // OR when baz has been executed 1 time. |
| |
| |
| File: gdb.info, Node: Tracepoint Conditions, Next: Trace State Variables, Prev: Tracepoint Passcounts, Up: Set Tracepoints |
| |
| 13.1.4 Tracepoint Conditions |
| ---------------------------- |
| |
| The simplest sort of tracepoint collects data every time your program |
| reaches a specified place. You can also specify a "condition" for a |
| tracepoint. A condition is just a Boolean expression in your |
| programming language (*note Expressions: Expressions.). A tracepoint |
| with a condition evaluates the expression each time your program reaches |
| it, and data collection happens only if the condition is true. |
| |
| Tracepoint conditions can be specified when a tracepoint is set, by |
| using 'if' in the arguments to the 'trace' command. *Note Setting |
| Tracepoints: Create and Delete Tracepoints. They can also be set or |
| changed at any time with the 'condition' command, just as with |
| breakpoints. |
| |
| Unlike breakpoint conditions, GDB does not actually evaluate the |
| conditional expression itself. Instead, GDB encodes the expression into |
| an agent expression (*note Agent Expressions::) suitable for execution |
| on the target, independently of GDB. Global variables become raw memory |
| locations, locals become stack accesses, and so forth. |
| |
| For instance, suppose you have a function that is usually called |
| frequently, but should not be called after an error has occurred. You |
| could use the following tracepoint command to collect data about calls |
| of that function that happen while the error code is propagating through |
| the program; an unconditional tracepoint could end up collecting |
| thousands of useless trace frames that you would have to search through. |
| |
| (gdb) trace normal_operation if errcode > 0 |
| |
| |
| File: gdb.info, Node: Trace State Variables, Next: Tracepoint Actions, Prev: Tracepoint Conditions, Up: Set Tracepoints |
| |
| 13.1.5 Trace State Variables |
| ---------------------------- |
| |
| A "trace state variable" is a special type of variable that is created |
| and managed by target-side code. The syntax is the same as that for |
| GDB's convenience variables (a string prefixed with "$"), but they are |
| stored on the target. They must be created explicitly, using a |
| 'tvariable' command. They are always 64-bit signed integers. |
| |
| Trace state variables are remembered by GDB, and downloaded to the |
| target along with tracepoint information when the trace experiment |
| starts. There are no intrinsic limits on the number of trace state |
| variables, beyond memory limitations of the target. |
| |
| Although trace state variables are managed by the target, you can use |
| them in print commands and expressions as if they were convenience |
| variables; GDB will get the current value from the target while the |
| trace experiment is running. Trace state variables share the same |
| namespace as other "$" variables, which means that you cannot have trace |
| state variables with names like '$23' or '$pc', nor can you have a trace |
| state variable and a convenience variable with the same name. |
| |
| 'tvariable $NAME [ = EXPRESSION ]' |
| The 'tvariable' command creates a new trace state variable named |
| '$NAME', and optionally gives it an initial value of EXPRESSION. |
| The EXPRESSION is evaluated when this command is entered; the |
| result will be converted to an integer if possible, otherwise GDB |
| will report an error. A subsequent 'tvariable' command specifying |
| the same name does not create a variable, but instead assigns the |
| supplied initial value to the existing variable of that name, |
| overwriting any previous initial value. The default initial value |
| is 0. |
| |
| 'info tvariables' |
| List all the trace state variables along with their initial values. |
| Their current values may also be displayed, if the trace experiment |
| is currently running. |
| |
| 'delete tvariable [ $NAME ... ]' |
| Delete the given trace state variables, or all of them if no |
| arguments are specified. |
| |
| |
| File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Trace State Variables, Up: Set Tracepoints |
| |
| 13.1.6 Tracepoint Action Lists |
| ------------------------------ |
| |
| 'actions [NUM]' |
| This command will prompt for a list of actions to be taken when the |
| tracepoint is hit. If the tracepoint number NUM is not specified, |
| this command sets the actions for the one that was most recently |
| defined (so that you can define a tracepoint and then say 'actions' |
| without bothering about its number). You specify the actions |
| themselves on the following lines, one action at a time, and |
| terminate the actions list with a line containing just 'end'. So |
| far, the only defined actions are 'collect', 'teval', and |
| 'while-stepping'. |
| |
| 'actions' is actually equivalent to 'commands' (*note Breakpoint |
| Command Lists: Break Commands.), except that only the defined |
| actions are allowed; any other GDB command is rejected. |
| |
| To remove all actions from a tracepoint, type 'actions NUM' and |
| follow it immediately with 'end'. |
| |
| (gdb) collect DATA // collect some data |
| |
| (gdb) while-stepping 5 // single-step 5 times, collect data |
| |
| (gdb) end // signals the end of actions. |
| |
| In the following example, the action list begins with 'collect' |
| commands indicating the things to be collected when the tracepoint |
| is hit. Then, in order to single-step and collect additional data |
| following the tracepoint, a 'while-stepping' command is used, |
| followed by the list of things to be collected after each step in a |
| sequence of single steps. The 'while-stepping' command is |
| terminated by its own separate 'end' command. Lastly, the action |
| list is terminated by an 'end' command. |
| |
| (gdb) trace foo |
| (gdb) actions |
| Enter actions for tracepoint 1, one per line: |
| > collect bar,baz |
| > collect $regs |
| > while-stepping 12 |
| > collect $pc, arr[i] |
| > end |
| end |
| |
| 'collect[/MODS] EXPR1, EXPR2, ...' |
| Collect values of the given expressions when the tracepoint is hit. |
| This command accepts a comma-separated list of any valid |
| expressions. In addition to global, static, or local variables, |
| the following special arguments are supported: |
| |
| '$regs' |
| Collect all registers. |
| |
| '$args' |
| Collect all function arguments. |
| |
| '$locals' |
| Collect all local variables. |
| |
| '$_ret' |
| Collect the return address. This is helpful if you want to |
| see more of a backtrace. |
| |
| '$_probe_argc' |
| Collects the number of arguments from the static probe at |
| which the tracepoint is located. *Note Static Probe Points::. |
| |
| '$_probe_argN' |
| N is an integer between 0 and 11. Collects the Nth argument |
| from the static probe at which the tracepoint is located. |
| *Note Static Probe Points::. |
| |
| '$_sdata' |
| Collect static tracepoint marker specific data. Only |
| available for static tracepoints. *Note Tracepoint Action |
| Lists: Tracepoint Actions. On the UST static tracepoints |
| library backend, an instrumentation point resembles a 'printf' |
| function call. The tracing library is able to collect user |
| specified data formatted to a character string using the |
| format provided by the programmer that instrumented the |
| program. Other backends have similar mechanisms. Here's an |
| example of a UST marker call: |
| |
| const char master_name[] = "$your_name"; |
| trace_mark(channel1, marker1, "hello %s", master_name) |
| |
| In this case, collecting '$_sdata' collects the string 'hello |
| $yourname'. When analyzing the trace buffer, you can inspect |
| '$_sdata' like any other variable available to GDB. |
| |
| You can give several consecutive 'collect' commands, each one with |
| a single argument, or one 'collect' command with several arguments |
| separated by commas; the effect is the same. |
| |
| The optional MODS changes the usual handling of the arguments. 's' |
| requests that pointers to chars be handled as strings, in |
| particular collecting the contents of the memory being pointed at, |
| up to the first zero. The upper bound is by default the value of |
| the 'print elements' variable; if 's' is followed by a decimal |
| number, that is the upper bound instead. So for instance |
| 'collect/s25 mystr' collects as many as 25 characters at 'mystr'. |
| |
| The command 'info scope' (*note info scope: Symbols.) is |
| particularly useful for figuring out what data to collect. |
| |
| 'teval EXPR1, EXPR2, ...' |
| Evaluate the given expressions when the tracepoint is hit. This |
| command accepts a comma-separated list of expressions. The results |
| are discarded, so this is mainly useful for assigning values to |
| trace state variables (*note Trace State Variables::) without |
| adding those values to the trace buffer, as would be the case if |
| the 'collect' action were used. |
| |
| 'while-stepping N' |
| Perform N single-step instruction traces after the tracepoint, |
| collecting new data after each step. The 'while-stepping' command |
| is followed by the list of what to collect while stepping (followed |
| by its own 'end' command): |
| |
| > while-stepping 12 |
| > collect $regs, myglobal |
| > end |
| > |
| |
| Note that '$pc' is not automatically collected by 'while-stepping'; |
| you need to explicitly collect that register if you need it. You |
| may abbreviate 'while-stepping' as 'ws' or 'stepping'. |
| |
| 'set default-collect EXPR1, EXPR2, ...' |
| This variable is a list of expressions to collect at each |
| tracepoint hit. It is effectively an additional 'collect' action |
| prepended to every tracepoint action list. The expressions are |
| parsed individually for each tracepoint, so for instance a variable |
| named 'xyz' may be interpreted as a global for one tracepoint, and |
| a local for another, as appropriate to the tracepoint's location. |
| |
| 'show default-collect' |
| Show the list of expressions that are collected by default at each |
| tracepoint hit. |
| |
| |
| File: gdb.info, Node: Listing Tracepoints, Next: Listing Static Tracepoint Markers, Prev: Tracepoint Actions, Up: Set Tracepoints |
| |
| 13.1.7 Listing Tracepoints |
| -------------------------- |
| |
| 'info tracepoints [NUM...]' |
| Display information about the tracepoint NUM. If you don't specify |
| a tracepoint number, displays information about all the tracepoints |
| defined so far. The format is similar to that used for 'info |
| breakpoints'; in fact, 'info tracepoints' is the same command, |
| simply restricting itself to tracepoints. |
| |
| A tracepoint's listing may include additional information specific |
| to tracing: |
| |
| * its passcount as given by the 'passcount N' command |
| |
| * the state about installed on target of each location |
| |
| (gdb) info trace |
| Num Type Disp Enb Address What |
| 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 |
| while-stepping 20 |
| collect globfoo, $regs |
| end |
| collect globfoo2 |
| end |
| pass count 1200 |
| 2 tracepoint keep y <MULTIPLE> |
| collect $eip |
| 2.1 y 0x0804859c in func4 at change-loc.h:35 |
| installed on target |
| 2.2 y 0xb7ffc480 in func4 at change-loc.h:35 |
| installed on target |
| 2.3 y <PENDING> set_tracepoint |
| 3 tracepoint keep y 0x080485b1 in foo at change-loc.c:29 |
| not installed on target |
| (gdb) |
| |
| This command can be abbreviated 'info tp'. |
| |
| |
| File: gdb.info, Node: Listing Static Tracepoint Markers, Next: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints |
| |
| 13.1.8 Listing Static Tracepoint Markers |
| ---------------------------------------- |
| |
| 'info static-tracepoint-markers' |
| Display information about all static tracepoint markers defined in |
| the program. |
| |
| For each marker, the following columns are printed: |
| |
| _Count_ |
| An incrementing counter, output to help readability. This is |
| not a stable identifier. |
| _ID_ |
| The marker ID, as reported by the target. |
| _Enabled or Disabled_ |
| Probed markers are tagged with 'y'. 'n' identifies marks that |
| are not enabled. |
| _Address_ |
| Where the marker is in your program, as a memory address. |
| _What_ |
| Where the marker is in the source for your program, as a file |
| and line number. If the debug information included in the |
| program does not allow GDB to locate the source of the marker, |
| this column will be left blank. |
| |
| In addition, the following information may be printed for each |
| marker: |
| |
| _Data_ |
| User data passed to the tracing library by the marker call. |
| In the UST backend, this is the format string passed as |
| argument to the marker call. |
| _Static tracepoints probing the marker_ |
| The list of static tracepoints attached to the marker. |
| |
| (gdb) info static-tracepoint-markers |
| Cnt ID Enb Address What |
| 1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 |
| Data: number1 %d number2 %d |
| Probed by static tracepoints: #2 |
| 2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 |
| Data: str %s |
| (gdb) |
| |
| |
| File: gdb.info, Node: Starting and Stopping Trace Experiments, Next: Tracepoint Restrictions, Prev: Listing Static Tracepoint Markers, Up: Set Tracepoints |
| |
| 13.1.9 Starting and Stopping Trace Experiments |
| ---------------------------------------------- |
| |
| 'tstart' |
| This command starts the trace experiment, and begins collecting |
| data. It has the side effect of discarding all the data collected |
| in the trace buffer during the previous trace experiment. If any |
| arguments are supplied, they are taken as a note and stored with |
| the trace experiment's state. The notes may be arbitrary text, and |
| are especially useful with disconnected tracing in a multi-user |
| context; the notes can explain what the trace is doing, supply user |
| contact information, and so forth. |
| |
| 'tstop' |
| This command stops the trace experiment. If any arguments are |
| supplied, they are recorded with the experiment as a note. This is |
| useful if you are stopping a trace started by someone else, for |
| instance if the trace is interfering with the system's behavior and |
| needs to be stopped quickly. |
| |
| *Note*: a trace experiment and data collection may stop |
| automatically if any tracepoint's passcount is reached (*note |
| Tracepoint Passcounts::), or if the trace buffer becomes full. |
| |
| 'tstatus' |
| This command displays the status of the current trace data |
| collection. |
| |
| Here is an example of the commands we described so far: |
| |
| (gdb) trace gdb_c_test |
| (gdb) actions |
| Enter actions for tracepoint #1, one per line. |
| > collect $regs,$locals,$args |
| > while-stepping 11 |
| > collect $regs |
| > end |
| > end |
| (gdb) tstart |
| [time passes ...] |
| (gdb) tstop |
| |
| You can choose to continue running the trace experiment even if GDB |
| disconnects from the target, voluntarily or involuntarily. For commands |
| such as 'detach', the debugger will ask what you want to do with the |
| trace. But for unexpected terminations (GDB crash, network outage), it |
| would be unfortunate to lose hard-won trace data, so the variable |
| 'disconnected-tracing' lets you decide whether the trace should continue |
| running without GDB. |
| |
| 'set disconnected-tracing on' |
| 'set disconnected-tracing off' |
| Choose whether a tracing run should continue to run if GDB has |
| disconnected from the target. Note that 'detach' or 'quit' will |
| ask you directly what to do about a running trace no matter what |
| this variable's setting, so the variable is mainly useful for |
| handling unexpected situations, such as loss of the network. |
| |
| 'show disconnected-tracing' |
| Show the current choice for disconnected tracing. |
| |
| When you reconnect to the target, the trace experiment may or may not |
| still be running; it might have filled the trace buffer in the meantime, |
| or stopped for one of the other reasons. If it is running, it will |
| continue after reconnection. |
| |
| Upon reconnection, the target will upload information about the |
| tracepoints in effect. GDB will then compare that information to the |
| set of tracepoints currently defined, and attempt to match them up, |
| allowing for the possibility that the numbers may have changed due to |
| creation and deletion in the meantime. If one of the target's |
| tracepoints does not match any in GDB, the debugger will create a new |
| tracepoint, so that you have a number with which to specify that |
| tracepoint. This matching-up process is necessarily heuristic, and it |
| may result in useless tracepoints being created; you may simply delete |
| them if they are of no use. |
| |
| If your target agent supports a "circular trace buffer", then you can |
| run a trace experiment indefinitely without filling the trace buffer; |
| when space runs out, the agent deletes already-collected trace frames, |
| oldest first, until there is enough room to continue collecting. This |
| is especially useful if your tracepoints are being hit too often, and |
| your trace gets terminated prematurely because the buffer is full. To |
| ask for a circular trace buffer, simply set 'circular-trace-buffer' to |
| on. You can set this at any time, including during tracing; if the |
| agent can do it, it will change buffer handling on the fly, otherwise it |
| will not take effect until the next run. |
| |
| 'set circular-trace-buffer on' |
| 'set circular-trace-buffer off' |
| Choose whether a tracing run should use a linear or circular buffer |
| for trace data. A linear buffer will not lose any trace data, but |
| may fill up prematurely, while a circular buffer will discard old |
| trace data, but it will have always room for the latest tracepoint |
| hits. |
| |
| 'show circular-trace-buffer' |
| Show the current choice for the trace buffer. Note that this may |
| not match the agent's current buffer handling, nor is it guaranteed |
| to match the setting that might have been in effect during a past |
| run, for instance if you are looking at frames from a trace file. |
| |
| 'set trace-buffer-size N' |
| 'set trace-buffer-size unlimited' |
| Request that the target use a trace buffer of N bytes. Not all |
| targets will honor the request; they may have a compiled-in size |
| for the trace buffer, or some other limitation. Set to a value of |
| 'unlimited' or '-1' to let the target use whatever size it likes. |
| This is also the default. |
| |
| 'show trace-buffer-size' |
| Show the current requested size for the trace buffer. Note that |
| this will only match the actual size if the target supports |
| size-setting, and was able to handle the requested size. For |
| instance, if the target can only change buffer size between runs, |
| this variable will not reflect the change until the next run |
| starts. Use 'tstatus' to get a report of the actual buffer size. |
| |
| 'set trace-user TEXT' |
| |
| 'show trace-user' |
| |
| 'set trace-notes TEXT' |
| Set the trace run's notes. |
| |
| 'show trace-notes' |
| Show the trace run's notes. |
| |
| 'set trace-stop-notes TEXT' |
| Set the trace run's stop notes. The handling of the note is as for |
| 'tstop' arguments; the set command is convenient way to fix a stop |
| note that is mistaken or incomplete. |
| |
| 'show trace-stop-notes' |
| Show the trace run's stop notes. |
| |
| |
| File: gdb.info, Node: Tracepoint Restrictions, Prev: Starting and Stopping Trace Experiments, Up: Set Tracepoints |
| |
| 13.1.10 Tracepoint Restrictions |
| ------------------------------- |
| |
| There are a number of restrictions on the use of tracepoints. As |
| described above, tracepoint data gathering occurs on the target without |
| interaction from GDB. Thus the full capabilities of the debugger are |
| not available during data gathering, and then at data examination time, |
| you will be limited by only having what was collected. The following |
| items describe some common problems, but it is not exhaustive, and you |
| may run into additional difficulties not mentioned here. |
| |
| * Tracepoint expressions are intended to gather objects (lvalues). |
| Thus the full flexibility of GDB's expression evaluator is not |
| available. You cannot call functions, cast objects to aggregate |
| types, access convenience variables or modify values (except by |
| assignment to trace state variables). Some language features may |
| implicitly call functions (for instance Objective-C fields with |
| accessors), and therefore cannot be collected either. |
| |
| * Collection of local variables, either individually or in bulk with |
| '$locals' or '$args', during 'while-stepping' may behave |
| erratically. The stepping action may enter a new scope (for |
| instance by stepping into a function), or the location of the |
| variable may change (for instance it is loaded into a register). |
| The tracepoint data recorded uses the location information for the |
| variables that is correct for the tracepoint location. When the |
| tracepoint is created, it is not possible, in general, to determine |
| where the steps of a 'while-stepping' sequence will advance the |
| program--particularly if a conditional branch is stepped. |
| |
| * Collection of an incompletely-initialized or partially-destroyed |
| object may result in something that GDB cannot display, or displays |
| in a misleading way. |
| |
| * When GDB displays a pointer to character it automatically |
| dereferences the pointer to also display characters of the string |
| being pointed to. However, collecting the pointer during tracing |
| does not automatically collect the string. You need to explicitly |
| dereference the pointer and provide size information if you want to |
| collect not only the pointer, but the memory pointed to. For |
| example, '*ptr@50' can be used to collect the 50 element array |
| pointed to by 'ptr'. |
| |
| * It is not possible to collect a complete stack backtrace at a |
| tracepoint. Instead, you may collect the registers and a few |
| hundred bytes from the stack pointer with something like |
| '*(unsigned char *)$esp@300' (adjust to use the name of the actual |
| stack pointer register on your target architecture, and the amount |
| of stack you wish to capture). Then the 'backtrace' command will |
| show a partial backtrace when using a trace frame. The number of |
| stack frames that can be examined depends on the sizes of the |
| frames in the collected stack. Note that if you ask for a block so |
| large that it goes past the bottom of the stack, the target agent |
| may report an error trying to read from an invalid address. |
| |
| * If you do not collect registers at a tracepoint, GDB can infer that |
| the value of '$pc' must be the same as the address of the |
| tracepoint and use that when you are looking at a trace frame for |
| that tracepoint. However, this cannot work if the tracepoint has |
| multiple locations (for instance if it was set in a function that |
| was inlined), or if it has a 'while-stepping' loop. In those cases |
| GDB will warn you that it can't infer '$pc', and default it to |
| zero. |
| |
| |
| File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints |
| |
| 13.2 Using the Collected Data |
| ============================= |
| |
| After the tracepoint experiment ends, you use GDB commands for examining |
| the trace data. The basic idea is that each tracepoint collects a trace |
| "snapshot" every time it is hit and another snapshot every time it |
| single-steps. All these snapshots are consecutively numbered from zero |
| and go into a buffer, and you can examine them later. The way you |
| examine them is to "focus" on a specific trace snapshot. When the |
| remote stub is focused on a trace snapshot, it will respond to all GDB |
| requests for memory and registers by reading from the buffer which |
| belongs to that snapshot, rather than from _real_ memory or registers of |
| the program being debugged. This means that *all* GDB commands |
| ('print', 'info registers', 'backtrace', etc.) will behave as if we |
| were currently debugging the program state as it was when the tracepoint |
| occurred. Any requests for data that are not in the buffer will fail. |
| |
| * Menu: |
| |
| * tfind:: How to select a trace snapshot |
| * tdump:: How to display all data for a snapshot |
| * save tracepoints:: How to save tracepoints for a future run |
| |
| |
| File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data |
| |
| 13.2.1 'tfind N' |
| ---------------- |
| |
| The basic command for selecting a trace snapshot from the buffer is |
| 'tfind N', which finds trace snapshot number N, counting from zero. If |
| no argument N is given, the next snapshot is selected. |
| |
| Here are the various forms of using the 'tfind' command. |
| |
| 'tfind start' |
| Find the first snapshot in the buffer. This is a synonym for |
| 'tfind 0' (since 0 is the number of the first snapshot). |
| |
| 'tfind none' |
| Stop debugging trace snapshots, resume _live_ debugging. |
| |
| 'tfind end' |
| Same as 'tfind none'. |
| |
| 'tfind' |
| No argument means find the next trace snapshot. |
| |
| 'tfind -' |
| Find the previous trace snapshot before the current one. This |
| permits retracing earlier steps. |
| |
| 'tfind tracepoint NUM' |
| Find the next snapshot associated with tracepoint NUM. Search |
| proceeds forward from the last examined trace snapshot. If no |
| argument NUM is given, it means find the next snapshot collected |
| for the same tracepoint as the current snapshot. |
| |
| 'tfind pc ADDR' |
| Find the next snapshot associated with the value ADDR of the |
| program counter. Search proceeds forward from the last examined |
| trace snapshot. If no argument ADDR is given, it means find the |
| next snapshot with the same value of PC as the current snapshot. |
| |
| 'tfind outside ADDR1, ADDR2' |
| Find the next snapshot whose PC is outside the given range of |
| addresses (exclusive). |
| |
| 'tfind range ADDR1, ADDR2' |
| Find the next snapshot whose PC is between ADDR1 and ADDR2 |
| (inclusive). |
| |
| 'tfind line [FILE:]N' |
| Find the next snapshot associated with the source line N. If the |
| optional argument FILE is given, refer to line N in that source |
| file. Search proceeds forward from the last examined trace |
| snapshot. If no argument N is given, it means find the next line |
| other than the one currently being examined; thus saying 'tfind |
| line' repeatedly can appear to have the same effect as stepping |
| from line to line in a _live_ debugging session. |
| |
| The default arguments for the 'tfind' commands are specifically |
| designed to make it easy to scan through the trace buffer. For |
| instance, 'tfind' with no argument selects the next trace snapshot, and |
| 'tfind -' with no argument selects the previous trace snapshot. So, by |
| giving one 'tfind' command, and then simply hitting <RET> repeatedly you |
| can examine all the trace snapshots in order. Or, by saying 'tfind -' |
| and then hitting <RET> repeatedly you can examine the snapshots in |
| reverse order. The 'tfind line' command with no argument selects the |
| snapshot for the next source line executed. The 'tfind pc' command with |
| no argument selects the next snapshot with the same program counter (PC) |
| as the current frame. The 'tfind tracepoint' command with no argument |
| selects the next trace snapshot collected by the same tracepoint as the |
| current one. |
| |
| In addition to letting you scan through the trace buffer manually, |
| these commands make it easy to construct GDB scripts that scan through |
| the trace buffer and print out whatever collected data you are |
| interested in. Thus, if we want to examine the PC, FP, and SP registers |
| from each trace frame in the buffer, we can say this: |
| |
| (gdb) tfind start |
| (gdb) while ($trace_frame != -1) |
| > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ |
| $trace_frame, $pc, $sp, $fp |
| > tfind |
| > end |
| |
| Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 |
| Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 |
| Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 |
| Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 |
| Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 |
| Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 |
| Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 |
| Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 |
| Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 |
| Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 |
| Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 |
| |
| Or, if we want to examine the variable 'X' at each source line in the |
| buffer: |
| |
| (gdb) tfind start |
| (gdb) while ($trace_frame != -1) |
| > printf "Frame %d, X == %d\n", $trace_frame, X |
| > tfind line |
| > end |
| |
| Frame 0, X = 1 |
| Frame 7, X = 2 |
| Frame 13, X = 255 |
| |
| |
| File: gdb.info, Node: tdump, Next: save tracepoints, Prev: tfind, Up: Analyze Collected Data |
| |
| 13.2.2 'tdump' |
| -------------- |
| |
| This command takes no arguments. It prints all the data collected at |
| the current trace snapshot. |
| |
| (gdb) trace 444 |
| (gdb) actions |
| Enter actions for tracepoint #2, one per line: |
| > collect $regs, $locals, $args, gdb_long_test |
| > end |
| |
| (gdb) tstart |
| |
| (gdb) tfind line 444 |
| #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) |
| at gdb_test.c:444 |
| 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) |
| |
| (gdb) tdump |
| Data collected at tracepoint 2, trace frame 1: |
| d0 0xc4aa0085 -995491707 |
| d1 0x18 24 |
| d2 0x80 128 |
| d3 0x33 51 |
| d4 0x71aea3d 119204413 |
| d5 0x22 34 |
| d6 0xe0 224 |
| d7 0x380035 3670069 |
| a0 0x19e24a 1696330 |
| a1 0x3000668 50333288 |
| a2 0x100 256 |
| a3 0x322000 3284992 |
| a4 0x3000698 50333336 |
| a5 0x1ad3cc 1758156 |
| fp 0x30bf3c 0x30bf3c |
| sp 0x30bf34 0x30bf34 |
| ps 0x0 0 |
| pc 0x20b2c8 0x20b2c8 |
| fpcontrol 0x0 0 |
| fpstatus 0x0 0 |
| fpiaddr 0x0 0 |
| p = 0x20e5b4 "gdb-test" |
| p1 = (void *) 0x11 |
| p2 = (void *) 0x22 |
| p3 = (void *) 0x33 |
| p4 = (void *) 0x44 |
| p5 = (void *) 0x55 |
| p6 = (void *) 0x66 |
| gdb_long_test = 17 '\021' |
| |
| (gdb) |
| |
| 'tdump' works by scanning the tracepoint's current collection actions |
| and printing the value of each expression listed. So 'tdump' can fail, |
| if after a run, you change the tracepoint's actions to mention variables |
| that were not collected during the run. |
| |
| Also, for tracepoints with 'while-stepping' loops, 'tdump' uses the |
| collected value of '$pc' to distinguish between trace frames that were |
| collected at the tracepoint hit, and frames that were collected while |
| stepping. This allows it to correctly choose whether to display the |
| basic list of collections, or the collections from the body of the |
| while-stepping loop. However, if '$pc' was not collected, then 'tdump' |
| will always attempt to dump using the basic collection list, and may |
| fail if a while-stepping frame does not include all the same data that |
| is collected at the tracepoint hit. |
| |
| |
| File: gdb.info, Node: save tracepoints, Prev: tdump, Up: Analyze Collected Data |
| |
| 13.2.3 'save tracepoints FILENAME' |
| ---------------------------------- |
| |
| This command saves all current tracepoint definitions together with |
| their actions and passcounts, into a file 'FILENAME' suitable for use in |
| a later debugging session. To read the saved tracepoint definitions, |
| use the 'source' command (*note Command Files::). The 'save-tracepoints' |
| command is a deprecated alias for 'save tracepoints' |
| |
| |
| File: gdb.info, Node: Tracepoint Variables, Next: Trace Files, Prev: Analyze Collected Data, Up: Tracepoints |
| |
| 13.3 Convenience Variables for Tracepoints |
| ========================================== |
| |
| '(int) $trace_frame' |
| The current trace snapshot (a.k.a. "frame") number, or -1 if no |
| snapshot is selected. |
| |
| '(int) $tracepoint' |
| The tracepoint for the current trace snapshot. |
| |
| '(int) $trace_line' |
| The line number for the current trace snapshot. |
| |
| '(char []) $trace_file' |
| The source file for the current trace snapshot. |
| |
| '(char []) $trace_func' |
| The name of the function containing '$tracepoint'. |
| |
| Note: '$trace_file' is not suitable for use in 'printf', use 'output' |
| instead. |
| |
| Here's a simple example of using these convenience variables for |
| stepping through all the trace snapshots and printing some of their |
| data. Note that these are not the same as trace state variables, which |
| are managed by the target. |
| |
| (gdb) tfind start |
| |
| (gdb) while $trace_frame != -1 |
| > output $trace_file |
| > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint |
| > tfind |
| > end |
| |
| |
| File: gdb.info, Node: Trace Files, Prev: Tracepoint Variables, Up: Tracepoints |
| |
| 13.4 Using Trace Files |
| ====================== |
| |
| In some situations, the target running a trace experiment may no longer |
| be available; perhaps it crashed, or the hardware was needed for a |
| different activity. To handle these cases, you can arrange to dump the |
| trace data into a file, and later use that file as a source of trace |
| data, via the 'target tfile' command. |
| |
| 'tsave [ -r ] FILENAME' |
| 'tsave [-ctf] DIRNAME' |
| Save the trace data to FILENAME. By default, this command assumes |
| that FILENAME refers to the host filesystem, so if necessary GDB |
| will copy raw trace data up from the target and then save it. If |
| the target supports it, you can also supply the optional argument |
| '-r' ("remote") to direct the target to save the data directly into |
| FILENAME in its own filesystem, which may be more efficient if the |
| trace buffer is very large. (Note, however, that 'target tfile' |
| can only read from files accessible to the host.) By default, this |
| command will save trace frame in tfile format. You can supply the |
| optional argument '-ctf' to save date in CTF format. The "Common |
| Trace Format" (CTF) is proposed as a trace format that can be |
| shared by multiple debugging and tracing tools. Please go to |
| 'http://www.efficios.com/ctf' to get more information. |
| |
| 'target tfile FILENAME' |
| 'target ctf DIRNAME' |
| Use the file named FILENAME or directory named DIRNAME as a source |
| of trace data. Commands that examine data work as they do with a |
| live target, but it is not possible to run any new trace |
| experiments. 'tstatus' will report the state of the trace run at |
| the moment the data was saved, as well as the current trace frame |
| you are examining. Both FILENAME and DIRNAME must be on a |
| filesystem accessible to the host. |
| |
| (gdb) target ctf ctf.ctf |
| (gdb) tfind |
| Found trace frame 0, tracepoint 2 |
| 39 ++a; /* set tracepoint 1 here */ |
| (gdb) tdump |
| Data collected at tracepoint 2, trace frame 0: |
| i = 0 |
| a = 0 |
| b = 1 '\001' |
| c = {"123", "456", "789", "123", "456", "789"} |
| d = {{{a = 1, b = 2}, {a = 3, b = 4}}, {{a = 5, b = 6}, {a = 7, b = 8}}} |
| (gdb) p b |
| $1 = 1 |
| |
| |
| File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top |
| |
| 14 Debugging Programs That Use Overlays |
| *************************************** |
| |
| If your program is too large to fit completely in your target system's |
| memory, you can sometimes use "overlays" to work around this problem. |
| GDB provides some support for debugging programs that use overlays. |
| |
| * Menu: |
| |
| * How Overlays Work:: A general explanation of overlays. |
| * Overlay Commands:: Managing overlays in GDB. |
| * Automatic Overlay Debugging:: GDB can find out which overlays are |
| mapped by asking the inferior. |
| * Overlay Sample Program:: A sample program using overlays. |
| |
| |
| File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays |
| |
| 14.1 How Overlays Work |
| ====================== |
| |
| Suppose you have a computer whose instruction address space is only 64 |
| kilobytes long, but which has much more memory which can be accessed by |
| other means: special instructions, segment registers, or memory |
| management hardware, for example. Suppose further that you want to |
| adapt a program which is larger than 64 kilobytes to run on this system. |
| |
| One solution is to identify modules of your program which are |
| relatively independent, and need not call each other directly; call |
| these modules "overlays". Separate the overlays from the main program, |
| and place their machine code in the larger memory. Place your main |
| program in instruction memory, but leave at least enough space there to |
| hold the largest overlay as well. |
| |
| Now, to call a function located in an overlay, you must first copy |
| that overlay's machine code from the large memory into the space set |
| aside for it in the instruction memory, and then jump to its entry point |
| there. |
| |
| Data Instruction Larger |
| Address Space Address Space Address Space |
| +-----------+ +-----------+ +-----------+ |
| | | | | | | |
| +-----------+ +-----------+ +-----------+<-- overlay 1 |
| | program | | main | .----| overlay 1 | load address |
| | variables | | program | | +-----------+ |
| | and heap | | | | | | |
| +-----------+ | | | +-----------+<-- overlay 2 |
| | | +-----------+ | | | load address |
| +-----------+ | | | .-| overlay 2 | |
| | | | | | | |
| mapped --->+-----------+ | | +-----------+ |
| address | | | | | | |
| | overlay | <-' | | | |
| | area | <---' +-----------+<-- overlay 3 |
| | | <---. | | load address |
| +-----------+ `--| overlay 3 | |
| | | | | |
| +-----------+ | | |
| +-----------+ |
| | | |
| +-----------+ |
| |
| A code overlay |
| |
| The diagram (*note A code overlay::) shows a system with separate |
| data and instruction address spaces. To map an overlay, the program |
| copies its code from the larger address space to the instruction address |
| space. Since the overlays shown here all use the same mapped address, |
| only one may be mapped at a time. For a system with a single address |
| space for data and instructions, the diagram would be similar, except |
| that the program variables and heap would share an address space with |
| the main program and the overlay area. |
| |
| An overlay loaded into instruction memory and ready for use is called |
| a "mapped" overlay; its "mapped address" is its address in the |
| instruction memory. An overlay not present (or only partially present) |
| in instruction memory is called "unmapped"; its "load address" is its |
| address in the larger memory. The mapped address is also called the |
| "virtual memory address", or "VMA"; the load address is also called the |
| "load memory address", or "LMA". |
| |
| Unfortunately, overlays are not a completely transparent way to adapt |
| a program to limited instruction memory. They introduce a new set of |
| global constraints you must keep in mind as you design your program: |
| |
| * Before calling or returning to a function in an overlay, your |
| program must make sure that overlay is actually mapped. Otherwise, |
| the call or return will transfer control to the right address, but |
| in the wrong overlay, and your program will probably crash. |
| |
| * If the process of mapping an overlay is expensive on your system, |
| you will need to choose your overlays carefully to minimize their |
| effect on your program's performance. |
| |
| * The executable file you load onto your system must contain each |
| overlay's instructions, appearing at the overlay's load address, |
| not its mapped address. However, each overlay's instructions must |
| be relocated and its symbols defined as if the overlay were at its |
| mapped address. You can use GNU linker scripts to specify |
| different load and relocation addresses for pieces of your program; |
| see *note (ld.info)Overlay Description::. |
| |
| * The procedure for loading executable files onto your system must be |
| able to load their contents into the larger address space as well |
| as the instruction and data spaces. |
| |
| The overlay system described above is rather simple, and could be |
| improved in many ways: |
| |
| * If your system has suitable bank switch registers or memory |
| management hardware, you could use those facilities to make an |
| overlay's load area contents simply appear at their mapped address |
| in instruction space. This would probably be faster than copying |
| the overlay to its mapped area in the usual way. |
| |
| * If your overlays are small enough, you could set aside more than |
| one overlay area, and have more than one overlay mapped at a time. |
| |
| * You can use overlays to manage data, as well as instructions. In |
| general, data overlays are even less transparent to your design |
| than code overlays: whereas code overlays only require care when |
| you call or return to functions, data overlays require care every |
| time you access the data. Also, if you change the contents of a |
| data overlay, you must copy its contents back out to its load |
| address before you can copy a different data overlay into the same |
| mapped area. |
| |
| |
| File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays |
| |
| 14.2 Overlay Commands |
| ===================== |
| |
| To use GDB's overlay support, each overlay in your program must |
| correspond to a separate section of the executable file. The section's |
| virtual memory address and load memory address must be the overlay's |
| mapped and load addresses. Identifying overlays with sections allows |
| GDB to determine the appropriate address of a function or variable, |
| depending on whether the overlay is mapped or not. |
| |
| GDB's overlay commands all start with the word 'overlay'; you can |
| abbreviate this as 'ov' or 'ovly'. The commands are: |
| |
| 'overlay off' |
| Disable GDB's overlay support. When overlay support is disabled, |
| GDB assumes that all functions and variables are always present at |
| their mapped addresses. By default, GDB's overlay support is |
| disabled. |
| |
| 'overlay manual' |
| Enable "manual" overlay debugging. In this mode, GDB relies on you |
| to tell it which overlays are mapped, and which are not, using the |
| 'overlay map-overlay' and 'overlay unmap-overlay' commands |
| described below. |
| |
| 'overlay map-overlay OVERLAY' |
| 'overlay map OVERLAY' |
| Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of |
| the object file section containing the overlay. When an overlay is |
| mapped, GDB assumes it can find the overlay's functions and |
| variables at their mapped addresses. GDB assumes that any other |
| overlays whose mapped ranges overlap that of OVERLAY are now |
| unmapped. |
| |
| 'overlay unmap-overlay OVERLAY' |
| 'overlay unmap OVERLAY' |
| Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the name |
| of the object file section containing the overlay. When an overlay |
| is unmapped, GDB assumes it can find the overlay's functions and |
| variables at their load addresses. |
| |
| 'overlay auto' |
| Enable "automatic" overlay debugging. In this mode, GDB consults a |
| data structure the overlay manager maintains in the inferior to see |
| which overlays are mapped. For details, see *note Automatic |
| Overlay Debugging::. |
| |
| 'overlay load-target' |
| 'overlay load' |
| Re-read the overlay table from the inferior. Normally, GDB |
| re-reads the table GDB automatically each time the inferior stops, |
| so this command should only be necessary if you have changed the |
| overlay mapping yourself using GDB. This command is only useful |
| when using automatic overlay debugging. |
| |
| 'overlay list-overlays' |
| 'overlay list' |
| Display a list of the overlays currently mapped, along with their |
| mapped addresses, load addresses, and sizes. |
| |
| Normally, when GDB prints a code address, it includes the name of the |
| function the address falls in: |
| |
| (gdb) print main |
| $3 = {int ()} 0x11a0 <main> |
| When overlay debugging is enabled, GDB recognizes code in unmapped |
| overlays, and prints the names of unmapped functions with asterisks |
| around them. For example, if 'foo' is a function in an unmapped |
| overlay, GDB prints it this way: |
| |
| (gdb) overlay list |
| No sections are mapped. |
| (gdb) print foo |
| $5 = {int (int)} 0x100000 <*foo*> |
| When 'foo''s overlay is mapped, GDB prints the function's name normally: |
| |
| (gdb) overlay list |
| Section .ov.foo.text, loaded at 0x100000 - 0x100034, |
| mapped at 0x1016 - 0x104a |
| (gdb) print foo |
| $6 = {int (int)} 0x1016 <foo> |
| |
| When overlay debugging is enabled, GDB can find the correct address |
| for functions and variables in an overlay, whether or not the overlay is |
| mapped. This allows most GDB commands, like 'break' and 'disassemble', |
| to work normally, even on unmapped code. However, GDB's breakpoint |
| support has some limitations: |
| |
| * You can set breakpoints in functions in unmapped overlays, as long |
| as GDB can write to the overlay at its load address. |
| * GDB can not set hardware or simulator-based breakpoints in unmapped |
| overlays. However, if you set a breakpoint at the end of your |
| overlay manager (and tell GDB which overlays are now mapped, if you |
| are using manual overlay management), GDB will re-set its |
| breakpoints properly. |
| |
| |
| File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays |
| |
| 14.3 Automatic Overlay Debugging |
| ================================ |
| |
| GDB can automatically track which overlays are mapped and which are not, |
| given some simple co-operation from the overlay manager in the inferior. |
| If you enable automatic overlay debugging with the 'overlay auto' |
| command (*note Overlay Commands::), GDB looks in the inferior's memory |
| for certain variables describing the current state of the overlays. |
| |
| Here are the variables your overlay manager must define to support |
| GDB's automatic overlay debugging: |
| |
| '_ovly_table': |
| This variable must be an array of the following structures: |
| |
| struct |
| { |
| /* The overlay's mapped address. */ |
| unsigned long vma; |
| |
| /* The size of the overlay, in bytes. */ |
| unsigned long size; |
| |
| /* The overlay's load address. */ |
| unsigned long lma; |
| |
| /* Non-zero if the overlay is currently mapped; |
| zero otherwise. */ |
| unsigned long mapped; |
| } |
| |
| '_novlys': |
| This variable must be a four-byte signed integer, holding the total |
| number of elements in '_ovly_table'. |
| |
| To decide whether a particular overlay is mapped or not, GDB looks |
| for an entry in '_ovly_table' whose 'vma' and 'lma' members equal the |
| VMA and LMA of the overlay's section in the executable file. When GDB |
| finds a matching entry, it consults the entry's 'mapped' member to |
| determine whether the overlay is currently mapped. |
| |
| In addition, your overlay manager may define a function called |
| '_ovly_debug_event'. If this function is defined, GDB will silently set |
| a breakpoint there. If the overlay manager then calls this function |
| whenever it has changed the overlay table, this will enable GDB to |
| accurately keep track of which overlays are in program memory, and |
| update any breakpoints that may be set in overlays. This will allow |
| breakpoints to work even if the overlays are kept in ROM or other |
| non-writable memory while they are not being executed. |
| |
| |
| File: gdb.info, Node: Overlay Sample Program, Prev: Automatic Overlay Debugging, Up: Overlays |
| |
| 14.4 Overlay Sample Program |
| =========================== |
| |
| When linking a program which uses overlays, you must place the overlays |
| at their load addresses, while relocating them to run at their mapped |
| addresses. To do this, you must write a linker script (*note |
| (ld.info)Overlay Description::). Unfortunately, since linker scripts |
| are specific to a particular host system, target architecture, and |
| target memory layout, this manual cannot provide portable sample code |
| demonstrating GDB's overlay support. |
| |
| However, the GDB source distribution does contain an overlaid |
| program, with linker scripts for a few systems, as part of its test |
| suite. The program consists of the following files from |
| 'gdb/testsuite/gdb.base': |
| |
| 'overlays.c' |
| The main program file. |
| 'ovlymgr.c' |
| A simple overlay manager, used by 'overlays.c'. |
| 'foo.c' |
| 'bar.c' |
| 'baz.c' |
| 'grbx.c' |
| Overlay modules, loaded and used by 'overlays.c'. |
| 'd10v.ld' |
| 'm32r.ld' |
| Linker scripts for linking the test program on the 'd10v-elf' and |
| 'm32r-elf' targets. |
| |
| You can build the test program using the 'd10v-elf' GCC |
| cross-compiler like this: |
| |
| $ d10v-elf-gcc -g -c overlays.c |
| $ d10v-elf-gcc -g -c ovlymgr.c |
| $ d10v-elf-gcc -g -c foo.c |
| $ d10v-elf-gcc -g -c bar.c |
| $ d10v-elf-gcc -g -c baz.c |
| $ d10v-elf-gcc -g -c grbx.c |
| $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ |
| baz.o grbx.o -Wl,-Td10v.ld -o overlays |
| |
| The build process is identical for any other architecture, except |
| that you must substitute the appropriate compiler and linker script for |
| the target system for 'd10v-elf-gcc' and 'd10v.ld'. |
| |
| |
| File: gdb.info, Node: Languages, Next: Symbols, Prev: Overlays, Up: Top |
| |
| 15 Using GDB with Different Languages |
| ************************************* |
| |
| Although programming languages generally have common aspects, they are |
| rarely expressed in the same manner. For instance, in ANSI C, |
| dereferencing a pointer 'p' is accomplished by '*p', but in Modula-2, it |
| is accomplished by 'p^'. Values can also be represented (and displayed) |
| differently. Hex numbers in C appear as '0x1ae', while in Modula-2 they |
| appear as '1AEH'. |
| |
| Language-specific information is built into GDB for some languages, |
| allowing you to express operations like the above in your program's |
| native language, and allowing GDB to output values in a manner |
| consistent with the syntax of your program's native language. The |
| language you use to build expressions is called the "working language". |
| |
| * Menu: |
| |
| * Setting:: Switching between source languages |
| * Show:: Displaying the language |
| * Checks:: Type and range checks |
| * Supported Languages:: Supported languages |
| * Unsupported Languages:: Unsupported languages |
| |
| |
| File: gdb.info, Node: Setting, Next: Show, Up: Languages |
| |
| 15.1 Switching Between Source Languages |
| ======================================= |
| |
| There are two ways to control the working language--either have GDB set |
| it automatically, or select it manually yourself. You can use the 'set |
| language' command for either purpose. On startup, GDB defaults to |
| setting the language automatically. The working language is used to |
| determine how expressions you type are interpreted, how values are |
| printed, etc. |
| |
| In addition to the working language, every source file that GDB knows |
| about has its own working language. For some object file formats, the |
| compiler might indicate which language a particular source file is in. |
| However, most of the time GDB infers the language from the name of the |
| file. The language of a source file controls whether C++ names are |
| demangled--this way 'backtrace' can show each frame appropriately for |
| its own language. There is no way to set the language of a source file |
| from within GDB, but you can set the language associated with a filename |
| extension. *Note Displaying the Language: Show. |
| |
| This is most commonly a problem when you use a program, such as |
| 'cfront' or 'f2c', that generates C but is written in another language. |
| In that case, make the program use '#line' directives in its C output; |
| that way GDB will know the correct language of the source code of the |
| original program, and will display that source code, not the generated C |
| code. |
| |
| * Menu: |
| |
| * Filenames:: Filename extensions and languages. |
| * Manually:: Setting the working language manually |
| * Automatically:: Having GDB infer the source language |
| |
| |
| File: gdb.info, Node: Filenames, Next: Manually, Up: Setting |
| |
| 15.1.1 List of Filename Extensions and Languages |
| ------------------------------------------------ |
| |
| If a source file name ends in one of the following extensions, then GDB |
| infers that its language is the one indicated. |
| |
| '.ada' |
| '.ads' |
| '.adb' |
| '.a' |
| Ada source file. |
| |
| '.c' |
| C source file |
| |
| '.C' |
| '.cc' |
| '.cp' |
| '.cpp' |
| '.cxx' |
| '.c++' |
| C++ source file |
| |
| '.d' |
| D source file |
| |
| '.m' |
| Objective-C source file |
| |
| '.f' |
| '.F' |
| Fortran source file |
| |
| '.mod' |
| Modula-2 source file |
| |
| '.s' |
| '.S' |
| Assembler source file. This actually behaves almost like C, but |
| GDB does not skip over function prologues when stepping. |
| |
| In addition, you may set the language associated with a filename |
| extension. *Note Displaying the Language: Show. |
| |
| |
| File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting |
| |
| 15.1.2 Setting the Working Language |
| ----------------------------------- |
| |
| If you allow GDB to set the language automatically, expressions are |
| interpreted the same way in your debugging session and your program. |
| |
| If you wish, you may set the language manually. To do this, issue |
| the command 'set language LANG', where LANG is the name of a language, |
| such as 'c' or 'modula-2'. For a list of the supported languages, type |
| 'set language'. |
| |
| Setting the language manually prevents GDB from updating the working |
| language automatically. This can lead to confusion if you try to debug |
| a program when the working language is not the same as the source |
| language, when an expression is acceptable to both languages--but means |
| different things. For instance, if the current source file were written |
| in C, and GDB was parsing Modula-2, a command such as: |
| |
| print a = b + c |
| |
| might not have the effect you intended. In C, this means to add 'b' and |
| 'c' and place the result in 'a'. The result printed would be the value |
| of 'a'. In Modula-2, this means to compare 'a' to the result of 'b+c', |
| yielding a 'BOOLEAN' value. |
| |
| |
| File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting |
| |
| 15.1.3 Having GDB Infer the Source Language |
| ------------------------------------------- |
| |
| To have GDB set the working language automatically, use 'set language |
| local' or 'set language auto'. GDB then infers the working language. |
| That is, when your program stops in a frame (usually by encountering a |
| breakpoint), GDB sets the working language to the language recorded for |
| the function in that frame. If the language for a frame is unknown |
| (that is, if the function or block corresponding to the frame was |
| defined in a source file that does not have a recognized extension), the |
| current working language is not changed, and GDB issues a warning. |
| |
| This may not seem necessary for most programs, which are written |
| entirely in one source language. However, program modules and libraries |
| written in one source language can be used by a main program written in |
| a different source language. Using 'set language auto' in this case |
| frees you from having to set the working language manually. |
| |
| |
| File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages |
| |
| 15.2 Displaying the Language |
| ============================ |
| |
| The following commands help you find out which language is the working |
| language, and also what language source files were written in. |
| |
| 'show language' |
| Display the current working language. This is the language you can |
| use with commands such as 'print' to build and compute expressions |
| that may involve variables in your program. |
| |
| 'info frame' |
| Display the source language for this frame. This language becomes |
| the working language if you use an identifier from this frame. |
| *Note Information about a Frame: Frame Info, to identify the other |
| information listed here. |
| |
| 'info source' |
| Display the source language of this source file. *Note Examining |
| the Symbol Table: Symbols, to identify the other information listed |
| here. |
| |
| In unusual circumstances, you may have source files with extensions |
| not in the standard list. You can then set the extension associated |
| with a language explicitly: |
| |
| 'set extension-language EXT LANGUAGE' |
| Tell GDB that source files with extension EXT are to be assumed as |
| written in the source language LANGUAGE. |
| |
| 'info extensions' |
| List all the filename extensions and the associated languages. |
| |
| |
| File: gdb.info, Node: Checks, Next: Supported Languages, Prev: Show, Up: Languages |
| |
| 15.3 Type and Range Checking |
| ============================ |
| |
| Some languages are designed to guard you against making seemingly common |
| errors through a series of compile- and run-time checks. These include |
| checking the type of arguments to functions and operators and making |
| sure mathematical overflows are caught at run time. Checks such as |
| these help to ensure a program's correctness once it has been compiled |
| by eliminating type mismatches and providing active checks for range |
| errors when your program is running. |
| |
| By default GDB checks for these errors according to the rules of the |
| current source language. Although GDB does not check the statements in |
| your program, it can check expressions entered directly into GDB for |
| evaluation via the 'print' command, for example. |
| |
| * Menu: |
| |
| * Type Checking:: An overview of type checking |
| * Range Checking:: An overview of range checking |
| |
| |
| File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks |
| |
| 15.3.1 An Overview of Type Checking |
| ----------------------------------- |
| |
| Some languages, such as C and C++, are strongly typed, meaning that the |
| arguments to operators and functions have to be of the correct type, |
| otherwise an error occurs. These checks prevent type mismatch errors |
| from ever causing any run-time problems. For example, |
| |
| int klass::my_method(char *b) { return b ? 1 : 2; } |
| |
| (gdb) print obj.my_method (0) |
| $1 = 2 |
| but |
| (gdb) print obj.my_method (0x1234) |
| Cannot resolve method klass::my_method to any overloaded instance |
| |
| The second example fails because in C++ the integer constant '0x1234' |
| is not type-compatible with the pointer parameter type. |
| |
| For the expressions you use in GDB commands, you can tell GDB to not |
| enforce strict type checking or to treat any mismatches as errors and |
| abandon the expression; When type checking is disabled, GDB successfully |
| evaluates expressions like the second example above. |
| |
| Even if type checking is off, there may be other reasons related to |
| type that prevent GDB from evaluating an expression. For instance, GDB |
| does not know how to add an 'int' and a 'struct foo'. These particular |
| type errors have nothing to do with the language in use and usually |
| arise from expressions which make little sense to evaluate anyway. |
| |
| GDB provides some additional commands for controlling type checking: |
| |
| 'set check type on' |
| 'set check type off' |
| Set strict type checking on or off. If any type mismatches occur |
| in evaluating an expression while type checking is on, GDB prints a |
| message and aborts evaluation of the expression. |
| |
| 'show check type' |
| Show the current setting of type checking and whether GDB is |
| enforcing strict type checking rules. |
| |
| |
| File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks |
| |
| 15.3.2 An Overview of Range Checking |
| ------------------------------------ |
| |
| In some languages (such as Modula-2), it is an error to exceed the |
| bounds of a type; this is enforced with run-time checks. Such range |
| checking is meant to ensure program correctness by making sure |
| computations do not overflow, or indices on an array element access do |
| not exceed the bounds of the array. |
| |
| For expressions you use in GDB commands, you can tell GDB to treat |
| range errors in one of three ways: ignore them, always treat them as |
| errors and abandon the expression, or issue warnings but evaluate the |
| expression anyway. |
| |
| A range error can result from numerical overflow, from exceeding an |
| array index bound, or when you type a constant that is not a member of |
| any type. Some languages, however, do not treat overflows as an error. |
| In many implementations of C, mathematical overflow causes the result to |
| "wrap around" to lower values--for example, if M is the largest integer |
| value, and S is the smallest, then |
| |
| M + 1 => S |
| |
| This, too, is specific to individual languages, and in some cases |
| specific to individual compilers or machines. *Note Supported |
| Languages: Supported Languages, for further details on specific |
| languages. |
| |
| GDB provides some additional commands for controlling the range |
| checker: |
| |
| 'set check range auto' |
| Set range checking on or off based on the current working language. |
| *Note Supported Languages: Supported Languages, for the default |
| settings for each language. |
| |
| 'set check range on' |
| 'set check range off' |
| Set range checking on or off, overriding the default setting for |
| the current working language. A warning is issued if the setting |
| does not match the language default. If a range error occurs and |
| range checking is on, then a message is printed and evaluation of |
| the expression is aborted. |
| |
| 'set check range warn' |
| Output messages when the GDB range checker detects a range error, |
| but attempt to evaluate the expression anyway. Evaluating the |
| expression may still be impossible for other reasons, such as |
| accessing memory that the process does not own (a typical example |
| from many Unix systems). |
| |
| 'show range' |
| Show the current setting of the range checker, and whether or not |
| it is being set automatically by GDB. |
| |
| |
| File: gdb.info, Node: Supported Languages, Next: Unsupported Languages, Prev: Checks, Up: Languages |
| |
| 15.4 Supported Languages |
| ======================== |
| |
| GDB supports C, C++, D, Go, Objective-C, Fortran, Java, OpenCL C, |
| Pascal, assembly, Modula-2, and Ada. Some GDB features may be used in |
| expressions regardless of the language you use: the GDB '@' and '::' |
| operators, and the '{type}addr' construct (*note Expressions: |
| Expressions.) can be used with the constructs of any supported language. |
| |
| The following sections detail to what degree each source language is |
| supported by GDB. These sections are not meant to be language tutorials |
| or references, but serve only as a reference guide to what the GDB |
| expression parser accepts, and what input and output formats should look |
| like for different languages. There are many good books written on each |
| of these languages; please look to these for a language reference or |
| tutorial. |
| |
| * Menu: |
| |
| * C:: C and C++ |
| * D:: D |
| * Go:: Go |
| * Objective-C:: Objective-C |
| * OpenCL C:: OpenCL C |
| * Fortran:: Fortran |
| * Pascal:: Pascal |
| * Modula-2:: Modula-2 |
| * Ada:: Ada |
| |
| |
| File: gdb.info, Node: C, Next: D, Up: Supported Languages |
| |
| 15.4.1 C and C++ |
| ---------------- |
| |
| Since C and C++ are so closely related, many features of GDB apply to |
| both languages. Whenever this is the case, we discuss those languages |
| together. |
| |
| The C++ debugging facilities are jointly implemented by the C++ |
| compiler and GDB. Therefore, to debug your C++ code effectively, you |
| must compile your C++ programs with a supported C++ compiler, such as |
| GNU 'g++', or the HP ANSI C++ compiler ('aCC'). |
| |
| * Menu: |
| |
| * C Operators:: C and C++ operators |
| * C Constants:: C and C++ constants |
| * C Plus Plus Expressions:: C++ expressions |
| * C Defaults:: Default settings for C and C++ |
| * C Checks:: C and C++ type and range checks |
| * Debugging C:: GDB and C |
| * Debugging C Plus Plus:: GDB features for C++ |
| * Decimal Floating Point:: Numbers in Decimal Floating Point format |
| |
| |
| File: gdb.info, Node: C Operators, Next: C Constants, Up: C |
| |
| 15.4.1.1 C and C++ Operators |
| ............................ |
| |
| Operators must be defined on values of specific types. For instance, |
| '+' is defined on numbers, but not on structures. Operators are often |
| defined on groups of types. |
| |
| For the purposes of C and C++, the following definitions hold: |
| |
| * _Integral types_ include 'int' with any of its storage-class |
| specifiers; 'char'; 'enum'; and, for C++, 'bool'. |
| |
| * _Floating-point types_ include 'float', 'double', and 'long double' |
| (if supported by the target platform). |
| |
| * _Pointer types_ include all types defined as '(TYPE *)'. |
| |
| * _Scalar types_ include all of the above. |
| |
| The following operators are supported. They are listed here in order of |
| increasing precedence: |
| |
| ',' |
| The comma or sequencing operator. Expressions in a comma-separated |
| list are evaluated from left to right, with the result of the |
| entire expression being the last expression evaluated. |
| |
| '=' |
| Assignment. The value of an assignment expression is the value |
| assigned. Defined on scalar types. |
| |
| 'OP=' |
| Used in an expression of the form 'A OP= B', and translated to |
| 'A = A OP B'. 'OP=' and '=' have the same precedence. The |
| operator OP is any one of the operators '|', '^', '&', '<<', '>>', |
| '+', '-', '*', '/', '%'. |
| |
| '?:' |
| The ternary operator. 'A ? B : C' can be thought of as: if A then |
| B else C. The argument A should be of an integral type. |
| |
| '||' |
| Logical OR. Defined on integral types. |
| |
| '&&' |
| Logical AND. Defined on integral types. |
| |
| '|' |
| Bitwise OR. Defined on integral types. |
| |
| '^' |
| Bitwise exclusive-OR. Defined on integral types. |
| |
| '&' |
| Bitwise AND. Defined on integral types. |
| |
| '==, !=' |
| Equality and inequality. Defined on scalar types. The value of |
| these expressions is 0 for false and non-zero for true. |
| |
| '<, >, <=, >=' |
| Less than, greater than, less than or equal, greater than or equal. |
| Defined on scalar types. The value of these expressions is 0 for |
| false and non-zero for true. |
| |
| '<<, >>' |
| left shift, and right shift. Defined on integral types. |
| |
| '@' |
| The GDB "artificial array" operator (*note Expressions: |
| Expressions.). |
| |
| '+, -' |
| Addition and subtraction. Defined on integral types, |
| floating-point types and pointer types. |
| |
| '*, /, %' |
| Multiplication, division, and modulus. Multiplication and division |
| are defined on integral and floating-point types. Modulus is |
| defined on integral types. |
| |
| '++, --' |
| Increment and decrement. When appearing before a variable, the |
| operation is performed before the variable is used in an |
| expression; when appearing after it, the variable's value is used |
| before the operation takes place. |
| |
| '*' |
| Pointer dereferencing. Defined on pointer types. Same precedence |
| as '++'. |
| |
| '&' |
| Address operator. Defined on variables. Same precedence as '++'. |
| |
| For debugging C++, GDB implements a use of '&' beyond what is |
| allowed in the C++ language itself: you can use '&(&REF)' to |
| examine the address where a C++ reference variable (declared with |
| '&REF') is stored. |
| |
| '-' |
| Negative. Defined on integral and floating-point types. Same |
| precedence as '++'. |
| |
| '!' |
| Logical negation. Defined on integral types. Same precedence as |
| '++'. |
| |
| '~' |
| Bitwise complement operator. Defined on integral types. Same |
| precedence as '++'. |
| |
| '., ->' |
| Structure member, and pointer-to-structure member. For |
| convenience, GDB regards the two as equivalent, choosing whether to |
| dereference a pointer based on the stored type information. |
| Defined on 'struct' and 'union' data. |
| |
| '.*, ->*' |
| Dereferences of pointers to members. |
| |
| '[]' |
| Array indexing. 'A[I]' is defined as '*(A+I)'. Same precedence as |
| '->'. |
| |
| '()' |
| Function parameter list. Same precedence as '->'. |
| |
| '::' |
| C++ scope resolution operator. Defined on 'struct', 'union', and |
| 'class' types. |
| |
| '::' |
| Doubled colons also represent the GDB scope operator (*note |
| Expressions: Expressions.). Same precedence as '::', above. |
| |
| If an operator is redefined in the user code, GDB usually attempts to |
| invoke the redefined version instead of using the operator's predefined |
| meaning. |
| |
| |
| File: gdb.info, Node: C Constants, Next: C Plus Plus Expressions, Prev: C Operators, Up: C |
| |
| 15.4.1.2 C and C++ Constants |
| ............................ |
| |
| GDB allows you to express the constants of C and C++ in the following |
| ways: |
| |
| * Integer constants are a sequence of digits. Octal constants are |
| specified by a leading '0' (i.e. zero), and hexadecimal constants |
| by a leading '0x' or '0X'. Constants may also end with a letter |
| 'l', specifying that the constant should be treated as a 'long' |
| value. |
| |
| * Floating point constants are a sequence of digits, followed by a |
| decimal point, followed by a sequence of digits, and optionally |
| followed by an exponent. An exponent is of the form: |
| 'e[[+]|-]NNN', where NNN is another sequence of digits. The '+' is |
| optional for positive exponents. A floating-point constant may |
| also end with a letter 'f' or 'F', specifying that the constant |
| should be treated as being of the 'float' (as opposed to the |
| default 'double') type; or with a letter 'l' or 'L', which |
| specifies a 'long double' constant. |
| |
| * Enumerated constants consist of enumerated identifiers, or their |
| integral equivalents. |
| |
| * Character constants are a single character surrounded by single |
| quotes ('''), or a number--the ordinal value of the corresponding |
| character (usually its ASCII value). Within quotes, the single |
| character may be represented by a letter or by "escape sequences", |
| which are of the form '\NNN', where NNN is the octal representation |
| of the character's ordinal value; or of the form '\X', where 'X' is |
| a predefined special character--for example, '\n' for newline. |
| |
| Wide character constants can be written by prefixing a character |
| constant with 'L', as in C. For example, 'L'x'' is the wide form of |
| 'x'. The target wide character set is used when computing the |
| value of this constant (*note Character Sets::). |
| |
| * String constants are a sequence of character constants surrounded |
| by double quotes ('"'). Any valid character constant (as described |
| above) may appear. Double quotes within the string must be |
| preceded by a backslash, so for instance '"a\"b'c"' is a string of |
| five characters. |
| |
| Wide string constants can be written by prefixing a string constant |
| with 'L', as in C. The target wide character set is used when |
| computing the value of this constant (*note Character Sets::). |
| |
| * Pointer constants are an integral value. You can also write |
| pointers to constants using the C operator '&'. |
| |
| * Array constants are comma-separated lists surrounded by braces '{' |
| and '}'; for example, '{1,2,3}' is a three-element array of |
| integers, '{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and |
| '{&"hi", &"there", &"fred"}' is a three-element array of pointers. |
| |
| |
| File: gdb.info, Node: C Plus Plus Expressions, Next: C Defaults, Prev: C Constants, Up: C |
| |
| 15.4.1.3 C++ Expressions |
| ........................ |
| |
| GDB expression handling can interpret most C++ expressions. |
| |
| _Warning:_ GDB can only debug C++ code if you use the proper |
| compiler and the proper debug format. Currently, GDB works best |
| when debugging C++ code that is compiled with the most recent |
| version of GCC possible. The DWARF debugging format is preferred; |
| GCC defaults to this on most popular platforms. Other compilers |
| and/or debug formats are likely to work badly or not at all when |
| using GDB to debug C++ code. *Note Compilation::. |
| |
| 1. Member function calls are allowed; you can use expressions like |
| |
| count = aml->GetOriginal(x, y) |
| |
| 2. While a member function is active (in the selected stack frame), |
| your expressions have the same namespace available as the member |
| function; that is, GDB allows implicit references to the class |
| instance pointer 'this' following the same rules as C++. 'using' |
| declarations in the current scope are also respected by GDB. |
| |
| 3. You can call overloaded functions; GDB resolves the function call |
| to the right definition, with some restrictions. GDB does not |
| perform overload resolution involving user-defined type |
| conversions, calls to constructors, or instantiations of templates |
| that do not exist in the program. It also cannot handle ellipsis |
| argument lists or default arguments. |
| |
| It does perform integral conversions and promotions, floating-point |
| promotions, arithmetic conversions, pointer conversions, |
| conversions of class objects to base classes, and standard |
| conversions such as those of functions or arrays to pointers; it |
| requires an exact match on the number of function arguments. |
| |
| Overload resolution is always performed, unless you have specified |
| 'set overload-resolution off'. *Note GDB Features for C++: |
| Debugging C Plus Plus. |
| |
| You must specify 'set overload-resolution off' in order to use an |
| explicit function signature to call an overloaded function, as in |
| p 'foo(char,int)'('x', 13) |
| |
| The GDB command-completion facility can simplify this; see *note |
| Command Completion: Completion. |
| |
| 4. GDB understands variables declared as C++ references; you can use |
| them in expressions just as you do in C++ source--they are |
| automatically dereferenced. |
| |
| In the parameter list shown when GDB displays a frame, the values |
| of reference variables are not displayed (unlike other variables); |
| this avoids clutter, since references are often used for large |
| structures. The _address_ of a reference variable is always shown, |
| unless you have specified 'set print address off'. |
| |
| 5. GDB supports the C++ name resolution operator '::'--your |
| expressions can use it just as expressions in your program do. |
| Since one scope may be defined in another, you can use '::' |
| repeatedly if necessary, for example in an expression like |
| 'SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by |
| reference to source files, in both C and C++ debugging (*note |
| Program Variables: Variables.). |
| |
| 6. GDB performs argument-dependent lookup, following the C++ |
| specification. |
| |
| |
| File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C Plus Plus Expressions, Up: C |
| |
| 15.4.1.4 C and C++ Defaults |
| ........................... |
| |
| If you allow GDB to set range checking automatically, it defaults to |
| 'off' whenever the working language changes to C or C++. This happens |
| regardless of whether you or GDB selects the working language. |
| |
| If you allow GDB to set the language automatically, it recognizes |
| source files whose names end with '.c', '.C', or '.cc', etc, and when |
| GDB enters code compiled from one of these files, it sets the working |
| language to C or C++. *Note Having GDB Infer the Source Language: |
| Automatically, for further details. |
| |
| |
| File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C |
| |
| 15.4.1.5 C and C++ Type and Range Checks |
| ........................................ |
| |
| By default, when GDB parses C or C++ expressions, strict type checking |
| is used. However, if you turn type checking off, GDB will allow certain |
| non-standard conversions, such as promoting integer constants to |
| pointers. |
| |
| Range checking, if turned on, is done on mathematical operations. |
| Array indices are not checked, since they are often used to index a |
| pointer that is not itself an array. |
| |
| |
| File: gdb.info, Node: Debugging C, Next: Debugging C Plus Plus, Prev: C Checks, Up: C |
| |
| 15.4.1.6 GDB and C |
| .................. |
| |
| The 'set print union' and 'show print union' commands apply to the |
| 'union' type. When set to 'on', any 'union' that is inside a 'struct' |
| or 'class' is also printed. Otherwise, it appears as '{...}'. |
| |
| The '@' operator aids in the debugging of dynamic arrays, formed with |
| pointers and a memory allocation function. *Note Expressions: |
| Expressions. |
| |
| |
| File: gdb.info, Node: Debugging C Plus Plus, Next: Decimal Floating Point, Prev: Debugging C, Up: C |
| |
| 15.4.1.7 GDB Features for C++ |
| ............................. |
| |
| Some GDB commands are particularly useful with C++, and some are |
| designed specifically for use with C++. Here is a summary: |
| |
| 'breakpoint menus' |
| When you want a breakpoint in a function whose name is overloaded, |
| GDB has the capability to display a menu of possible breakpoint |
| locations to help you specify which function definition you want. |
| *Note Ambiguous Expressions: Ambiguous Expressions. |
| |
| 'rbreak REGEX' |
| Setting breakpoints using regular expressions is helpful for |
| setting breakpoints on overloaded functions that are not members of |
| any special classes. *Note Setting Breakpoints: Set Breaks. |
| |
| 'catch throw' |
| 'catch rethrow' |
| 'catch catch' |
| Debug C++ exception handling using these commands. *Note Setting |
| Catchpoints: Set Catchpoints. |
| |
| 'ptype TYPENAME' |
| Print inheritance relationships as well as other information for |
| type TYPENAME. *Note Examining the Symbol Table: Symbols. |
| |
| 'info vtbl EXPRESSION.' |
| The 'info vtbl' command can be used to display the virtual method |
| tables of the object computed by EXPRESSION. This shows one entry |
| per virtual table; there may be multiple virtual tables when |
| multiple inheritance is in use. |
| |
| 'demangle NAME' |
| Demangle NAME. *Note Symbols::, for a more complete description of |
| the 'demangle' command. |
| |
| 'set print demangle' |
| 'show print demangle' |
| 'set print asm-demangle' |
| 'show print asm-demangle' |
| Control whether C++ symbols display in their source form, both when |
| displaying code as C++ source and when displaying disassemblies. |
| *Note Print Settings: Print Settings. |
| |
| 'set print object' |
| 'show print object' |
| Choose whether to print derived (actual) or declared types of |
| objects. *Note Print Settings: Print Settings. |
| |
| 'set print vtbl' |
| 'show print vtbl' |
| Control the format for printing virtual function tables. *Note |
| Print Settings: Print Settings. (The 'vtbl' commands do not work |
| on programs compiled with the HP ANSI C++ compiler ('aCC').) |
| |
| 'set overload-resolution on' |
| Enable overload resolution for C++ expression evaluation. The |
| default is on. For overloaded functions, GDB evaluates the |
| arguments and searches for a function whose signature matches the |
| argument types, using the standard C++ conversion rules (see *note |
| C++ Expressions: C Plus Plus Expressions, for details). If it |
| cannot find a match, it emits a message. |
| |
| 'set overload-resolution off' |
| Disable overload resolution for C++ expression evaluation. For |
| overloaded functions that are not class member functions, GDB |
| chooses the first function of the specified name that it finds in |
| the symbol table, whether or not its arguments are of the correct |
| type. For overloaded functions that are class member functions, |
| GDB searches for a function whose signature _exactly_ matches the |
| argument types. |
| |
| 'show overload-resolution' |
| Show the current setting of overload resolution. |
| |
| 'Overloaded symbol names' |
| You can specify a particular definition of an overloaded symbol, |
| using the same notation that is used to declare such symbols in |
| C++: type 'SYMBOL(TYPES)' rather than just SYMBOL. You can also |
| use the GDB command-line word completion facilities to list the |
| available choices, or to finish the type list for you. *Note |
| Command Completion: Completion, for details on how to do this. |
| |
| |
| File: gdb.info, Node: Decimal Floating Point, Prev: Debugging C Plus Plus, Up: C |
| |
| 15.4.1.8 Decimal Floating Point format |
| ...................................... |
| |
| GDB can examine, set and perform computations with numbers in decimal |
| floating point format, which in the C language correspond to the |
| '_Decimal32', '_Decimal64' and '_Decimal128' types as specified by the |
| extension to support decimal floating-point arithmetic. |
| |
| There are two encodings in use, depending on the architecture: BID |
| (Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed |
| Decimal) for PowerPC and S/390. GDB will use the appropriate encoding |
| for the configured target. |
| |
| Because of a limitation in 'libdecnumber', the library used by GDB to |
| manipulate decimal floating point numbers, it is not possible to convert |
| (using a cast, for example) integers wider than 32-bit to decimal float. |
| |
| In addition, in order to imitate GDB's behaviour with binary floating |
| point computations, error checking in decimal float operations ignores |
| underflow, overflow and divide by zero exceptions. |
| |
| In the PowerPC architecture, GDB provides a set of pseudo-registers |
| to inspect '_Decimal128' values stored in floating point registers. See |
| *note PowerPC: PowerPC. for more details. |
| |
| |
| File: gdb.info, Node: D, Next: Go, Prev: C, Up: Supported Languages |
| |
| 15.4.2 D |
| -------- |
| |
| GDB can be used to debug programs written in D and compiled with GDC, |
| LDC or DMD compilers. Currently GDB supports only one D specific |
| feature -- dynamic arrays. |
| |
| |
| File: gdb.info, Node: Go, Next: Objective-C, Prev: D, Up: Supported Languages |
| |
| 15.4.3 Go |
| --------- |
| |
| GDB can be used to debug programs written in Go and compiled with |
| 'gccgo' or '6g' compilers. |
| |
| Here is a summary of the Go-specific features and restrictions: |
| |
| 'The current Go package' |
| The name of the current package does not need to be specified when |
| specifying global variables and functions. |
| |
| For example, given the program: |
| |
| package main |
| var myglob = "Shall we?" |
| func main () { |
| // ... |
| } |
| |
| When stopped inside 'main' either of these work: |
| |
| (gdb) p myglob |
| (gdb) p main.myglob |
| |
| 'Builtin Go types' |
| The 'string' type is recognized by GDB and is printed as a string. |
| |
| 'Builtin Go functions' |
| The GDB expression parser recognizes the 'unsafe.Sizeof' function |
| and handles it internally. |
| |
| 'Restrictions on Go expressions' |
| All Go operators are supported except '&^'. The Go '_' "blank |
| identifier" is not supported. Automatic dereferencing of pointers |
| is not supported. |
| |
| |
| File: gdb.info, Node: Objective-C, Next: OpenCL C, Prev: Go, Up: Supported Languages |
| |
| 15.4.4 Objective-C |
| ------------------ |
| |
| This section provides information about some commands and command |
| options that are useful for debugging Objective-C code. See also *note |
| info classes: Symbols, and *note info selectors: Symbols, for a few more |
| commands specific to Objective-C support. |
| |
| * Menu: |
| |
| * Method Names in Commands:: |
| * The Print Command with Objective-C:: |
| |
| |
| File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Up: Objective-C |
| |
| 15.4.4.1 Method Names in Commands |
| ................................. |
| |
| The following commands have been extended to accept Objective-C method |
| names as line specifications: |
| |
| * 'clear' |
| * 'break' |
| * 'info line' |
| * 'jump' |
| * 'list' |
| |
| A fully qualified Objective-C method name is specified as |
| |
| -[CLASS METHODNAME] |
| |
| where the minus sign is used to indicate an instance method and a |
| plus sign (not shown) is used to indicate a class method. The class |
| name CLASS and method name METHODNAME are enclosed in brackets, similar |
| to the way messages are specified in Objective-C source code. For |
| example, to set a breakpoint at the 'create' instance method of class |
| 'Fruit' in the program currently being debugged, enter: |
| |
| break -[Fruit create] |
| |
| To list ten program lines around the 'initialize' class method, |
| enter: |
| |
| list +[NSText initialize] |
| |
| In the current version of GDB, the plus or minus sign is required. |
| In future versions of GDB, the plus or minus sign will be optional, but |
| you can use it to narrow the search. It is also possible to specify |
| just a method name: |
| |
| break create |
| |
| You must specify the complete method name, including any colons. If |
| your program's source files contain more than one 'create' method, |
| you'll be presented with a numbered list of classes that implement that |
| method. Indicate your choice by number, or type '0' to exit if none |
| apply. |
| |
| As another example, to clear a breakpoint established at the |
| 'makeKeyAndOrderFront:' method of the 'NSWindow' class, enter: |
| |
| clear -[NSWindow makeKeyAndOrderFront:] |
| |
| |
| File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C |
| |
| 15.4.4.2 The Print Command With Objective-C |
| ........................................... |
| |
| The print command has also been extended to accept methods. For |
| example: |
| |
| print -[OBJECT hash] |
| |
| will tell GDB to send the 'hash' message to OBJECT and print the result. |
| Also, an additional command has been added, 'print-object' or 'po' for |
| short, which is meant to print the description of an object. However, |
| this command may only work with certain Objective-C libraries that have |
| a particular hook function, '_NSPrintForDebugger', defined. |
| |
| |
| File: gdb.info, Node: OpenCL C, Next: Fortran, Prev: Objective-C, Up: Supported Languages |
| |
| 15.4.5 OpenCL C |
| --------------- |
| |
| This section provides information about GDBs OpenCL C support. |
| |
| * Menu: |
| |
| * OpenCL C Datatypes:: |
| * OpenCL C Expressions:: |
| * OpenCL C Operators:: |
| |
| |
| File: gdb.info, Node: OpenCL C Datatypes, Next: OpenCL C Expressions, Up: OpenCL C |
| |
| 15.4.5.1 OpenCL C Datatypes |
| ........................... |
| |
| GDB supports the builtin scalar and vector datatypes specified by OpenCL |
| 1.1. In addition the half- and double-precision floating point data |
| types of the 'cl_khr_fp16' and 'cl_khr_fp64' OpenCL extensions are also |
| known to GDB. |
| |
| |
| File: gdb.info, Node: OpenCL C Expressions, Next: OpenCL C Operators, Prev: OpenCL C Datatypes, Up: OpenCL C |
| |
| 15.4.5.2 OpenCL C Expressions |
| ............................. |
| |
| GDB supports accesses to vector components including the access as |
| lvalue where possible. Since OpenCL C is based on C99 most C |
| expressions supported by GDB can be used as well. |
| |
| |
| File: gdb.info, Node: OpenCL C Operators, Prev: OpenCL C Expressions, Up: OpenCL C |
| |
| 15.4.5.3 OpenCL C Operators |
| ........................... |
| |
| GDB supports the operators specified by OpenCL 1.1 for scalar and vector |
| data types. |
| |
| |
| File: gdb.info, Node: Fortran, Next: Pascal, Prev: OpenCL C, Up: Supported Languages |
| |
| 15.4.6 Fortran |
| -------------- |
| |
| GDB can be used to debug programs written in Fortran, but it currently |
| supports only the features of Fortran 77 language. |
| |
| Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers among |
| them) append an underscore to the names of variables and functions. |
| When you debug programs compiled by those compilers, you will need to |
| refer to variables and functions with a trailing underscore. |
| |
| * Menu: |
| |
| * Fortran Operators:: Fortran operators and expressions |
| * Fortran Defaults:: Default settings for Fortran |
| * Special Fortran Commands:: Special GDB commands for Fortran |
| |
| |
| File: gdb.info, Node: Fortran Operators, Next: Fortran Defaults, Up: Fortran |
| |
| 15.4.6.1 Fortran Operators and Expressions |
| .......................................... |
| |
| Operators must be defined on values of specific types. For instance, |
| '+' is defined on numbers, but not on characters or other non- |
| arithmetic types. Operators are often defined on groups of types. |
| |
| '**' |
| The exponentiation operator. It raises the first operand to the |
| power of the second one. |
| |
| ':' |
| The range operator. Normally used in the form of array(low:high) |
| to represent a section of array. |
| |
| '%' |
| The access component operator. Normally used to access elements in |
| derived types. Also suitable for unions. As unions aren't part of |
| regular Fortran, this can only happen when accessing a register |
| that uses a gdbarch-defined union type. |
| |
| |
| File: gdb.info, Node: Fortran Defaults, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran |
| |
| 15.4.6.2 Fortran Defaults |
| ......................... |
| |
| Fortran symbols are usually case-insensitive, so GDB by default uses |
| case-insensitive matches for Fortran symbols. You can change that with |
| the 'set case-insensitive' command, see *note Symbols::, for the |
| details. |
| |
| |
| File: gdb.info, Node: Special Fortran Commands, Prev: Fortran Defaults, Up: Fortran |
| |
| 15.4.6.3 Special Fortran Commands |
| ................................. |
| |
| GDB has some commands to support Fortran-specific features, such as |
| displaying common blocks. |
| |
| 'info common [COMMON-NAME]' |
| This command prints the values contained in the Fortran 'COMMON' |
| block whose name is COMMON-NAME. With no argument, the names of |
| all 'COMMON' blocks visible at the current program location are |
| printed. |
| |
| |
| File: gdb.info, Node: Pascal, Next: Modula-2, Prev: Fortran, Up: Supported Languages |
| |
| 15.4.7 Pascal |
| ------------- |
| |
| Debugging Pascal programs which use sets, subranges, file variables, or |
| nested functions does not currently work. GDB does not support entering |
| expressions, printing values, or similar features using Pascal syntax. |
| |
| The Pascal-specific command 'set print pascal_static-members' |
| controls whether static members of Pascal objects are displayed. *Note |
| pascal_static-members: Print Settings. |
| |
| |
| File: gdb.info, Node: Modula-2, Next: Ada, Prev: Pascal, Up: Supported Languages |
| |
| 15.4.8 Modula-2 |
| --------------- |
| |
| The extensions made to GDB to support Modula-2 only support output from |
| the GNU Modula-2 compiler (which is currently being developed). Other |
| Modula-2 compilers are not currently supported, and attempting to debug |
| executables produced by them is most likely to give an error as GDB |
| reads in the executable's symbol table. |
| |
| * Menu: |
| |
| * M2 Operators:: Built-in operators |
| * Built-In Func/Proc:: Built-in functions and procedures |
| * M2 Constants:: Modula-2 constants |
| * M2 Types:: Modula-2 types |
| * M2 Defaults:: Default settings for Modula-2 |
| * Deviations:: Deviations from standard Modula-2 |
| * M2 Checks:: Modula-2 type and range checks |
| * M2 Scope:: The scope operators '::' and '.' |
| * GDB/M2:: GDB and Modula-2 |
| |
| |
| File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 |
| |
| 15.4.8.1 Operators |
| .................. |
| |
| Operators must be defined on values of specific types. For instance, |
| '+' is defined on numbers, but not on structures. Operators are often |
| defined on groups of types. For the purposes of Modula-2, the following |
| definitions hold: |
| |
| * _Integral types_ consist of 'INTEGER', 'CARDINAL', and their |
| subranges. |
| |
| * _Character types_ consist of 'CHAR' and its subranges. |
| |
| * _Floating-point types_ consist of 'REAL'. |
| |
| * _Pointer types_ consist of anything declared as 'POINTER TO TYPE'. |
| |
| * _Scalar types_ consist of all of the above. |
| |
| * _Set types_ consist of 'SET' and 'BITSET' types. |
| |
| * _Boolean types_ consist of 'BOOLEAN'. |
| |
| The following operators are supported, and appear in order of increasing |
| precedence: |
| |
| ',' |
| Function argument or array index separator. |
| |
| ':=' |
| Assignment. The value of VAR ':=' VALUE is VALUE. |
| |
| '<, >' |
| Less than, greater than on integral, floating-point, or enumerated |
| types. |
| |
| '<=, >=' |
| Less than or equal to, greater than or equal to on integral, |
| floating-point and enumerated types, or set inclusion on set types. |
| Same precedence as '<'. |
| |
| '=, <>, #' |
| Equality and two ways of expressing inequality, valid on scalar |
| types. Same precedence as '<'. In GDB scripts, only '<>' is |
| available for inequality, since '#' conflicts with the script |
| comment character. |
| |
| 'IN' |
| Set membership. Defined on set types and the types of their |
| members. Same precedence as '<'. |
| |
| 'OR' |
| Boolean disjunction. Defined on boolean types. |
| |
| 'AND, &' |
| Boolean conjunction. Defined on boolean types. |
| |
| '@' |
| The GDB "artificial array" operator (*note Expressions: |
| Expressions.). |
| |
| '+, -' |
| Addition and subtraction on integral and floating-point types, or |
| union and difference on set types. |
| |
| '*' |
| Multiplication on integral and floating-point types, or set |
| intersection on set types. |
| |
| '/' |
| Division on floating-point types, or symmetric set difference on |
| set types. Same precedence as '*'. |
| |
| 'DIV, MOD' |
| Integer division and remainder. Defined on integral types. Same |
| precedence as '*'. |
| |
| '-' |
| Negative. Defined on 'INTEGER' and 'REAL' data. |
| |
| '^' |
| Pointer dereferencing. Defined on pointer types. |
| |
| 'NOT' |
| Boolean negation. Defined on boolean types. Same precedence as |
| '^'. |
| |
| '.' |
| 'RECORD' field selector. Defined on 'RECORD' data. Same |
| precedence as '^'. |
| |
| '[]' |
| Array indexing. Defined on 'ARRAY' data. Same precedence as '^'. |
| |
| '()' |
| Procedure argument list. Defined on 'PROCEDURE' objects. Same |
| precedence as '^'. |
| |
| '::, .' |
| GDB and Modula-2 scope operators. |
| |
| _Warning:_ Set expressions and their operations are not yet |
| supported, so GDB treats the use of the operator 'IN', or the use |
| of operators '+', '-', '*', '/', '=', , '<>', '#', '<=', and '>=' |
| on sets as an error. |
| |
| |
| File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 |
| |
| 15.4.8.2 Built-in Functions and Procedures |
| .......................................... |
| |
| Modula-2 also makes available several built-in procedures and functions. |
| In describing these, the following metavariables are used: |
| |
| A |
| represents an 'ARRAY' variable. |
| |
| C |
| represents a 'CHAR' constant or variable. |
| |
| I |
| represents a variable or constant of integral type. |
| |
| M |
| represents an identifier that belongs to a set. Generally used in |
| the same function with the metavariable S. The type of S should be |
| 'SET OF MTYPE' (where MTYPE is the type of M). |
| |
| N |
| represents a variable or constant of integral or floating-point |
| type. |
| |
| R |
| represents a variable or constant of floating-point type. |
| |
| T |
| represents a type. |
| |
| V |
| represents a variable. |
| |
| X |
| represents a variable or constant of one of many types. See the |
| explanation of the function for details. |
| |
| All Modula-2 built-in procedures also return a result, described |
| below. |
| |
| 'ABS(N)' |
| Returns the absolute value of N. |
| |
| 'CAP(C)' |
| If C is a lower case letter, it returns its upper case equivalent, |
| otherwise it returns its argument. |
| |
| 'CHR(I)' |
| Returns the character whose ordinal value is I. |
| |
| 'DEC(V)' |
| Decrements the value in the variable V by one. Returns the new |
| value. |
| |
| 'DEC(V,I)' |
| Decrements the value in the variable V by I. Returns the new |
| value. |
| |
| 'EXCL(M,S)' |
| Removes the element M from the set S. Returns the new set. |
| |
| 'FLOAT(I)' |
| Returns the floating point equivalent of the integer I. |
| |
| 'HIGH(A)' |
| Returns the index of the last member of A. |
| |
| 'INC(V)' |
| Increments the value in the variable V by one. Returns the new |
| value. |
| |
| 'INC(V,I)' |
| Increments the value in the variable V by I. Returns the new |
| value. |
| |
| 'INCL(M,S)' |
| Adds the element M to the set S if it is not already there. |
| Returns the new set. |
| |
| 'MAX(T)' |
| Returns the maximum value of the type T. |
| |
| 'MIN(T)' |
| Returns the minimum value of the type T. |
| |
| 'ODD(I)' |
| Returns boolean TRUE if I is an odd number. |
| |
| 'ORD(X)' |
| Returns the ordinal value of its argument. For example, the |
| ordinal value of a character is its ASCII value (on machines |
| supporting the ASCII character set). The argument X must be of an |
| ordered type, which include integral, character and enumerated |
| types. |
| |
| 'SIZE(X)' |
| Returns the size of its argument. The argument X can be a variable |
| or a type. |
| |
| 'TRUNC(R)' |
| Returns the integral part of R. |
| |
| 'TSIZE(X)' |
| Returns the size of its argument. The argument X can be a variable |
| or a type. |
| |
| 'VAL(T,I)' |
| Returns the member of the type T whose ordinal value is I. |
| |
| _Warning:_ Sets and their operations are not yet supported, so GDB |
| treats the use of procedures 'INCL' and 'EXCL' as an error. |
| |
| |
| File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2 |
| |
| 15.4.8.3 Constants |
| .................. |
| |
| GDB allows you to express the constants of Modula-2 in the following |
| ways: |
| |
| * Integer constants are simply a sequence of digits. When used in an |
| expression, a constant is interpreted to be type-compatible with |
| the rest of the expression. Hexadecimal integers are specified by |
| a trailing 'H', and octal integers by a trailing 'B'. |
| |
| * Floating point constants appear as a sequence of digits, followed |
| by a decimal point and another sequence of digits. An optional |
| exponent can then be specified, in the form 'E[+|-]NNN', where |
| '[+|-]NNN' is the desired exponent. All of the digits of the |
| floating point constant must be valid decimal (base 10) digits. |
| |
| * Character constants consist of a single character enclosed by a |
| pair of like quotes, either single (''') or double ('"'). They may |
| also be expressed by their ordinal value (their ASCII value, |
| usually) followed by a 'C'. |
| |
| * String constants consist of a sequence of characters enclosed by a |
| pair of like quotes, either single (''') or double ('"'). Escape |
| sequences in the style of C are also allowed. *Note C and C++ |
| Constants: C Constants, for a brief explanation of escape |
| sequences. |
| |
| * Enumerated constants consist of an enumerated identifier. |
| |
| * Boolean constants consist of the identifiers 'TRUE' and 'FALSE'. |
| |
| * Pointer constants consist of integral values only. |
| |
| * Set constants are not yet supported. |
| |
| |
| File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2 |
| |
| 15.4.8.4 Modula-2 Types |
| ....................... |
| |
| Currently GDB can print the following data types in Modula-2 syntax: |
| array types, record types, set types, pointer types, procedure types, |
| enumerated types, subrange types and base types. You can also print the |
| contents of variables declared using these type. This section gives a |
| number of simple source code examples together with sample GDB sessions. |
| |
| The first example contains the following section of code: |
| |
| VAR |
| s: SET OF CHAR ; |
| r: [20..40] ; |
| |
| and you can request GDB to interrogate the type and value of 'r' and |
| 's'. |
| |
| (gdb) print s |
| {'A'..'C', 'Z'} |
| (gdb) ptype s |
| SET OF CHAR |
| (gdb) print r |
| 21 |
| (gdb) ptype r |
| [20..40] |
| |
| Likewise if your source code declares 's' as: |
| |
| VAR |
| s: SET ['A'..'Z'] ; |
| |
| then you may query the type of 's' by: |
| |
| (gdb) ptype s |
| type = SET ['A'..'Z'] |
| |
| Note that at present you cannot interactively manipulate set expressions |
| using the debugger. |
| |
| The following example shows how you might declare an array in |
| Modula-2 and how you can interact with GDB to print its type and |
| contents: |
| |
| VAR |
| s: ARRAY [-10..10] OF CHAR ; |
| |
| (gdb) ptype s |
| ARRAY [-10..10] OF CHAR |
| |
| Note that the array handling is not yet complete and although the |
| type is printed correctly, expression handling still assumes that all |
| arrays have a lower bound of zero and not '-10' as in the example above. |
| |
| Here are some more type related Modula-2 examples: |
| |
| TYPE |
| colour = (blue, red, yellow, green) ; |
| t = [blue..yellow] ; |
| VAR |
| s: t ; |
| BEGIN |
| s := blue ; |
| |
| The GDB interaction shows how you can query the data type and value of a |
| variable. |
| |
| (gdb) print s |
| $1 = blue |
| (gdb) ptype t |
| type = [blue..yellow] |
| |
| In this example a Modula-2 array is declared and its contents displayed. |
| Observe that the contents are written in the same way as their 'C' |
| counterparts. |
| |
| VAR |
| s: ARRAY [1..5] OF CARDINAL ; |
| BEGIN |
| s[1] := 1 ; |
| |
| (gdb) print s |
| $1 = {1, 0, 0, 0, 0} |
| (gdb) ptype s |
| type = ARRAY [1..5] OF CARDINAL |
| |
| The Modula-2 language interface to GDB also understands pointer types |
| as shown in this example: |
| |
| VAR |
| s: POINTER TO ARRAY [1..5] OF CARDINAL ; |
| BEGIN |
| NEW(s) ; |
| s^[1] := 1 ; |
| |
| and you can request that GDB describes the type of 's'. |
| |
| (gdb) ptype s |
| type = POINTER TO ARRAY [1..5] OF CARDINAL |
| |
| GDB handles compound types as we can see in this example. Here we |
| combine array types, record types, pointer types and subrange types: |
| |
| TYPE |
| foo = RECORD |
| f1: CARDINAL ; |
| f2: CHAR ; |
| f3: myarray ; |
| END ; |
| |
| myarray = ARRAY myrange OF CARDINAL ; |
| myrange = [-2..2] ; |
| VAR |
| s: POINTER TO ARRAY myrange OF foo ; |
| |
| and you can ask GDB to describe the type of 's' as shown below. |
| |
| (gdb) ptype s |
| type = POINTER TO ARRAY [-2..2] OF foo = RECORD |
| f1 : CARDINAL; |
| f2 : CHAR; |
| f3 : ARRAY [-2..2] OF CARDINAL; |
| END |
| |
| |
| File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2 |
| |
| 15.4.8.5 Modula-2 Defaults |
| .......................... |
| |
| If type and range checking are set automatically by GDB, they both |
| default to 'on' whenever the working language changes to Modula-2. This |
| happens regardless of whether you or GDB selected the working language. |
| |
| If you allow GDB to set the language automatically, then entering |
| code compiled from a file whose name ends with '.mod' sets the working |
| language to Modula-2. *Note Having GDB Infer the Source Language: |
| Automatically, for further details. |
| |
| |
| File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 |
| |
| 15.4.8.6 Deviations from Standard Modula-2 |
| .......................................... |
| |
| A few changes have been made to make Modula-2 programs easier to debug. |
| This is done primarily via loosening its type strictness: |
| |
| * Unlike in standard Modula-2, pointer constants can be formed by |
| integers. This allows you to modify pointer variables during |
| debugging. (In standard Modula-2, the actual address contained in |
| a pointer variable is hidden from you; it can only be modified |
| through direct assignment to another pointer variable or expression |
| that returned a pointer.) |
| |
| * C escape sequences can be used in strings and characters to |
| represent non-printable characters. GDB prints out strings with |
| these escape sequences embedded. Single non-printable characters |
| are printed using the 'CHR(NNN)' format. |
| |
| * The assignment operator (':=') returns the value of its right-hand |
| argument. |
| |
| * All built-in procedures both modify _and_ return their argument. |
| |
| |
| File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 |
| |
| 15.4.8.7 Modula-2 Type and Range Checks |
| ....................................... |
| |
| _Warning:_ in this release, GDB does not yet perform type or range |
| checking. |
| |
| GDB considers two Modula-2 variables type equivalent if: |
| |
| * They are of types that have been declared equivalent via a 'TYPE T1 |
| = T2' statement |
| |
| * They have been declared on the same line. (Note: This is true of |
| the GNU Modula-2 compiler, but it may not be true of other |
| compilers.) |
| |
| As long as type checking is enabled, any attempt to combine variables |
| whose types are not equivalent is an error. |
| |
| Range checking is done on all mathematical operations, assignment, |
| array index bounds, and all built-in functions and procedures. |
| |
| |
| File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 |
| |
| 15.4.8.8 The Scope Operators '::' and '.' |
| ......................................... |
| |
| There are a few subtle differences between the Modula-2 scope operator |
| ('.') and the GDB scope operator ('::'). The two have similar syntax: |
| |
| |
| MODULE . ID |
| SCOPE :: ID |
| |
| where SCOPE is the name of a module or a procedure, MODULE the name of a |
| module, and ID is any declared identifier within your program, except |
| another module. |
| |
| Using the '::' operator makes GDB search the scope specified by SCOPE |
| for the identifier ID. If it is not found in the specified scope, then |
| GDB searches all scopes enclosing the one specified by SCOPE. |
| |
| Using the '.' operator makes GDB search the current scope for the |
| identifier specified by ID that was imported from the definition module |
| specified by MODULE. With this operator, it is an error if the |
| identifier ID was not imported from definition module MODULE, or if ID |
| is not an identifier in MODULE. |
| |
| |
| File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 |
| |
| 15.4.8.9 GDB and Modula-2 |
| ......................... |
| |
| Some GDB commands have little use when debugging Modula-2 programs. |
| Five subcommands of 'set print' and 'show print' apply specifically to C |
| and C++: 'vtbl', 'demangle', 'asm-demangle', 'object', and 'union'. The |
| first four apply to C++, and the last to the C 'union' type, which has |
| no direct analogue in Modula-2. |
| |
| The '@' operator (*note Expressions: Expressions.), while available |
| with any language, is not useful with Modula-2. Its intent is to aid |
| the debugging of "dynamic arrays", which cannot be created in Modula-2 |
| as they can in C or C++. However, because an address can be specified |
| by an integral constant, the construct '{TYPE}ADREXP' is still useful. |
| |
| In GDB scripts, the Modula-2 inequality operator '#' is interpreted |
| as the beginning of a comment. Use '<>' instead. |
| |
| |
| File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages |
| |
| 15.4.9 Ada |
| ---------- |
| |
| The extensions made to GDB for Ada only support output from the GNU Ada |
| (GNAT) compiler. Other Ada compilers are not currently supported, and |
| attempting to debug executables produced by them is most likely to be |
| difficult. |
| |
| * Menu: |
| |
| * Ada Mode Intro:: General remarks on the Ada syntax |
| and semantics supported by Ada mode |
| in GDB. |
| * Omissions from Ada:: Restrictions on the Ada expression syntax. |
| * Additions to Ada:: Extensions of the Ada expression syntax. |
| * Stopping Before Main Program:: Debugging the program during elaboration. |
| * Ada Exceptions:: Ada Exceptions |
| * Ada Tasks:: Listing and setting breakpoints in tasks. |
| * Ada Tasks and Core Files:: Tasking Support when Debugging Core Files |
| * Ravenscar Profile:: Tasking Support when using the Ravenscar |
| Profile |
| * Ada Glitches:: Known peculiarities of Ada mode. |
| |
| |
| File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada |
| |
| 15.4.9.1 Introduction |
| ..................... |
| |
| The Ada mode of GDB supports a fairly large subset of Ada expression |
| syntax, with some extensions. The philosophy behind the design of this |
| subset is |
| |
| * That GDB should provide basic literals and access to operations for |
| arithmetic, dereferencing, field selection, indexing, and |
| subprogram calls, leaving more sophisticated computations to |
| subprograms written into the program (which therefore may be called |
| from GDB). |
| |
| * That type safety and strict adherence to Ada language restrictions |
| are not particularly important to the GDB user. |
| |
| * That brevity is important to the GDB user. |
| |
| Thus, for brevity, the debugger acts as if all names declared in |
| user-written packages are directly visible, even if they are not visible |
| according to Ada rules, thus making it unnecessary to fully qualify most |
| names with their packages, regardless of context. Where this causes |
| ambiguity, GDB asks the user's intent. |
| |
| The debugger will start in Ada mode if it detects an Ada main |
| program. As for other languages, it will enter Ada mode when stopped in |
| a program that was translated from an Ada source file. |
| |
| While in Ada mode, you may use '--' for comments. This is useful |
| mostly for documenting command files. The standard GDB comment ('#') |
| still works at the beginning of a line in Ada mode, but not in the |
| middle (to allow based literals). |
| |
| The debugger supports limited overloading. Given a subprogram call |
| in which the function symbol has multiple definitions, it will use the |
| number of actual parameters and some information about their types to |
| attempt to narrow the set of definitions. It also makes very limited |
| use of context, preferring procedures to functions in the context of the |
| 'call' command, and functions to procedures elsewhere. |
| |
| |
| File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada |
| |
| 15.4.9.2 Omissions from Ada |
| ........................... |
| |
| Here are the notable omissions from the subset: |
| |
| * Only a subset of the attributes are supported: |
| |
| - 'First, 'Last, and 'Length on array objects (not on types and |
| subtypes). |
| |
| - 'Min and 'Max. |
| |
| - 'Pos and 'Val. |
| |
| - 'Tag. |
| |
| - 'Range on array objects (not subtypes), but only as the right |
| operand of the membership ('in') operator. |
| |
| - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT |
| extension). |
| |
| - 'Address. |
| |
| * The names in 'Characters.Latin_1' are not available and |
| concatenation is not implemented. Thus, escape characters in |
| strings are not currently available. |
| |
| * Equality tests ('=' and '/=') on arrays test for bitwise equality |
| of representations. They will generally work correctly for strings |
| and arrays whose elements have integer or enumeration types. They |
| may not work correctly for arrays whose element types have |
| user-defined equality, for arrays of real values (in particular, |
| IEEE-conformant floating point, because of negative zeroes and |
| NaNs), and for arrays whose elements contain unused bits with |
| indeterminate values. |
| |
| * The other component-by-component array operations ('and', 'or', |
| 'xor', 'not', and relational tests other than equality) are not |
| implemented. |
| |
| * There is limited support for array and record aggregates. They are |
| permitted only on the right sides of assignments, as in these |
| examples: |
| |
| (gdb) set An_Array := (1, 2, 3, 4, 5, 6) |
| (gdb) set An_Array := (1, others => 0) |
| (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) |
| (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) |
| (gdb) set A_Record := (1, "Peter", True); |
| (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True) |
| |
| Changing a discriminant's value by assigning an aggregate has an |
| undefined effect if that discriminant is used within the record. |
| However, you can first modify discriminants by directly assigning |
| to them (which normally would not be allowed in Ada), and then |
| performing an aggregate assignment. For example, given a variable |
| 'A_Rec' declared to have a type such as: |
| |
| type Rec (Len : Small_Integer := 0) is record |
| Id : Integer; |
| Vals : IntArray (1 .. Len); |
| end record; |
| |
| you can assign a value with a different size of 'Vals' with two |
| assignments: |
| |
| (gdb) set A_Rec.Len := 4 |
| (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) |
| |
| As this example also illustrates, GDB is very loose about the usual |
| rules concerning aggregates. You may leave out some of the |
| components of an array or record aggregate (such as the 'Len' |
| component in the assignment to 'A_Rec' above); they will retain |
| their original values upon assignment. You may freely use dynamic |
| values as indices in component associations. You may even use |
| overlapping or redundant component associations, although which |
| component values are assigned in such cases is not defined. |
| |
| * Calls to dispatching subprograms are not implemented. |
| |
| * The overloading algorithm is much more limited (i.e., less |
| selective) than that of real Ada. It makes only limited use of the |
| context in which a subexpression appears to resolve its meaning, |
| and it is much looser in its rules for allowing type matches. As a |
| result, some function calls will be ambiguous, and the user will be |
| asked to choose the proper resolution. |
| |
| * The 'new' operator is not implemented. |
| |
| * Entry calls are not implemented. |
| |
| * Aside from printing, arithmetic operations on the native VAX |
| floating-point formats are not supported. |
| |
| * It is not possible to slice a packed array. |
| |
| * The names 'True' and 'False', when not part of a qualified name, |
| are interpreted as if implicitly prefixed by 'Standard', regardless |
| of context. Should your program redefine these names in a package |
| or procedure (at best a dubious practice), you will have to use |
| fully qualified names to access their new definitions. |
| |
| |
| File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada |
| |
| 15.4.9.3 Additions to Ada |
| ......................... |
| |
| As it does for other languages, GDB makes certain generic extensions to |
| Ada (*note Expressions::): |
| |
| * If the expression E is a variable residing in memory (typically a |
| local variable or array element) and N is a positive integer, then |
| 'E@N' displays the values of E and the N-1 adjacent variables |
| following it in memory as an array. In Ada, this operator is |
| generally not necessary, since its prime use is in displaying parts |
| of an array, and slicing will usually do this in Ada. However, |
| there are occasional uses when debugging programs in which certain |
| debugging information has been optimized away. |
| |
| * 'B::VAR' means "the variable named VAR that appears in function or |
| file B." When B is a file name, you must typically surround it in |
| single quotes. |
| |
| * The expression '{TYPE} ADDR' means "the variable of type TYPE that |
| appears at address ADDR." |
| |
| * A name starting with '$' is a convenience variable (*note |
| Convenience Vars::) or a machine register (*note Registers::). |
| |
| In addition, GDB provides a few other shortcuts and outright |
| additions specific to Ada: |
| |
| * The assignment statement is allowed as an expression, returning its |
| right-hand operand as its value. Thus, you may enter |
| |
| (gdb) set x := y + 3 |
| (gdb) print A(tmp := y + 1) |
| |
| * The semicolon is allowed as an "operator," returning as its value |
| the value of its right-hand operand. This allows, for example, |
| complex conditional breaks: |
| |
| (gdb) break f |
| (gdb) condition 1 (report(i); k += 1; A(k) > 100) |
| |
| * Rather than use catenation and symbolic character names to |
| introduce special characters into strings, one may instead use a |
| special bracket notation, which is also used to print strings. A |
| sequence of characters of the form '["XX"]' within a string or |
| character literal denotes the (single) character whose numeric |
| encoding is XX in hexadecimal. The sequence of characters '["""]' |
| also denotes a single quotation mark in strings. For example, |
| "One line.["0a"]Next line.["0a"]" |
| contains an ASCII newline character ('Ada.Characters.Latin_1.LF') |
| after each period. |
| |
| * The subtype used as a prefix for the attributes 'Pos, 'Min, and |
| 'Max is optional (and is ignored in any case). For example, it is |
| valid to write |
| |
| (gdb) print 'max(x, y) |
| |
| * When printing arrays, GDB uses positional notation when the array |
| has a lower bound of 1, and uses a modified named notation |
| otherwise. For example, a one-dimensional array of three integers |
| with a lower bound of 3 might print as |
| |
| (3 => 10, 17, 1) |
| |
| That is, in contrast to valid Ada, only the first component has a |
| '=>' clause. |
| |
| * You may abbreviate attributes in expressions with any unique, |
| multi-character subsequence of their names (an exact match gets |
| preference). For example, you may use a'len, a'gth, or a'lh in |
| place of a'length. |
| |
| * Since Ada is case-insensitive, the debugger normally maps |
| identifiers you type to lower case. The GNAT compiler uses |
| upper-case characters for some of its internal identifiers, which |
| are normally of no interest to users. For the rare occasions when |
| you actually have to look at them, enclose them in angle brackets |
| to avoid the lower-case mapping. For example, |
| (gdb) print <JMPBUF_SAVE>[0] |
| |
| * Printing an object of class-wide type or dereferencing an |
| access-to-class-wide value will display all the components of the |
| object's specific type (as indicated by its run-time tag). |
| Likewise, component selection on such a value will operate on the |
| specific type of the object. |
| |
| |
| File: gdb.info, Node: Stopping Before Main Program, Next: Ada Exceptions, Prev: Additions to Ada, Up: Ada |
| |
| 15.4.9.4 Stopping at the Very Beginning |
| ....................................... |
| |
| It is sometimes necessary to debug the program during elaboration, and |
| before reaching the main procedure. As defined in the Ada Reference |
| Manual, the elaboration code is invoked from a procedure called |
| 'adainit'. To run your program up to the beginning of elaboration, |
| simply use the following two commands: 'tbreak adainit' and 'run'. |
| |
| |
| File: gdb.info, Node: Ada Exceptions, Next: Ada Tasks, Prev: Stopping Before Main Program, Up: Ada |
| |
| 15.4.9.5 Ada Exceptions |
| ....................... |
| |
| A command is provided to list all Ada exceptions: |
| |
| 'info exceptions' |
| 'info exceptions REGEXP' |
| The 'info exceptions' command allows you to list all Ada exceptions |
| defined within the program being debugged, as well as their |
| addresses. With a regular expression, REGEXP, as argument, only |
| those exceptions whose names match REGEXP are listed. |
| |
| Below is a small example, showing how the command can be used, first |
| without argument, and next with a regular expression passed as an |
| argument. |
| |
| (gdb) info exceptions |
| All defined Ada exceptions: |
| constraint_error: 0x613da0 |
| program_error: 0x613d20 |
| storage_error: 0x613ce0 |
| tasking_error: 0x613ca0 |
| const.aint_global_e: 0x613b00 |
| (gdb) info exceptions const.aint |
| All Ada exceptions matching regular expression "const.aint": |
| constraint_error: 0x613da0 |
| const.aint_global_e: 0x613b00 |
| |
| It is also possible to ask GDB to stop your program's execution when |
| an exception is raised. For more details, see *note Set Catchpoints::. |
| |
| |
| File: gdb.info, Node: Ada Tasks, Next: Ada Tasks and Core Files, Prev: Ada Exceptions, Up: Ada |
| |
| 15.4.9.6 Extensions for Ada Tasks |
| ................................. |
| |
| Support for Ada tasks is analogous to that for threads (*note |
| Threads::). GDB provides the following task-related commands: |
| |
| 'info tasks' |
| This command shows a list of current Ada tasks, as in the following |
| example: |
| |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 8088000 0 15 Child Activation Wait main_task |
| 2 80a4000 1 15 Accept Statement b |
| 3 809a800 1 15 Child Activation Wait a |
| * 4 80ae800 3 15 Runnable c |
| |
| |
| In this listing, the asterisk before the last task indicates it to |
| be the task currently being inspected. |
| |
| ID |
| Represents GDB's internal task number. |
| |
| TID |
| The Ada task ID. |
| |
| P-ID |
| The parent's task ID (GDB's internal task number). |
| |
| Pri |
| The base priority of the task. |
| |
| State |
| Current state of the task. |
| |
| 'Unactivated' |
| The task has been created but has not been activated. It |
| cannot be executing. |
| |
| 'Runnable' |
| The task is not blocked for any reason known to Ada. (It |
| may be waiting for a mutex, though.) It is conceptually |
| "executing" in normal mode. |
| |
| 'Terminated' |
| The task is terminated, in the sense of ARM 9.3 (5). Any |
| dependents that were waiting on terminate alternatives |
| have been awakened and have terminated themselves. |
| |
| 'Child Activation Wait' |
| The task is waiting for created tasks to complete |
| activation. |
| |
| 'Accept Statement' |
| The task is waiting on an accept or selective wait |
| statement. |
| |
| 'Waiting on entry call' |
| The task is waiting on an entry call. |
| |
| 'Async Select Wait' |
| The task is waiting to start the abortable part of an |
| asynchronous select statement. |
| |
| 'Delay Sleep' |
| The task is waiting on a select statement with only a |
| delay alternative open. |
| |
| 'Child Termination Wait' |
| The task is sleeping having completed a master within |
| itself, and is waiting for the tasks dependent on that |
| master to become terminated or waiting on a terminate |
| Phase. |
| |
| 'Wait Child in Term Alt' |
| The task is sleeping waiting for tasks on terminate |
| alternatives to finish terminating. |
| |
| 'Accepting RV with TASKNO' |
| The task is accepting a rendez-vous with the task TASKNO. |
| |
| Name |
| Name of the task in the program. |
| |
| 'info task TASKNO' |
| This command shows detailled informations on the specified task, as |
| in the following example: |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 8077880 0 15 Child Activation Wait main_task |
| * 2 807c468 1 15 Runnable task_1 |
| (gdb) info task 2 |
| Ada Task: 0x807c468 |
| Name: task_1 |
| Thread: 0x807f378 |
| Parent: 1 (main_task) |
| Base Priority: 15 |
| State: Runnable |
| |
| 'task' |
| This command prints the ID of the current task. |
| |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 8077870 0 15 Child Activation Wait main_task |
| * 2 807c458 1 15 Runnable t |
| (gdb) task |
| [Current task is 2] |
| |
| 'task TASKNO' |
| This command is like the 'thread THREADNO' command (*note |
| Threads::). It switches the context of debugging from the current |
| task to the given task. |
| |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 8077870 0 15 Child Activation Wait main_task |
| * 2 807c458 1 15 Runnable t |
| (gdb) task 1 |
| [Switching to task 1] |
| #0 0x8067726 in pthread_cond_wait () |
| (gdb) bt |
| #0 0x8067726 in pthread_cond_wait () |
| #1 0x8056714 in system.os_interface.pthread_cond_wait () |
| #2 0x805cb63 in system.task_primitives.operations.sleep () |
| #3 0x806153e in system.tasking.stages.activate_tasks () |
| #4 0x804aacc in un () at un.adb:5 |
| |
| 'break LINESPEC task TASKNO' |
| 'break LINESPEC task TASKNO if ...' |
| These commands are like the 'break ... thread ...' command (*note |
| Thread Stops::). The LINESPEC argument specifies source lines, as |
| described in *note Specify Location::. |
| |
| Use the qualifier 'task TASKNO' with a breakpoint command to |
| specify that you only want GDB to stop the program when a |
| particular Ada task reaches this breakpoint. The TASKNO is one of |
| the numeric task identifiers assigned by GDB, shown in the first |
| column of the 'info tasks' display. |
| |
| If you do not specify 'task TASKNO' when you set a breakpoint, the |
| breakpoint applies to _all_ tasks of your program. |
| |
| You can use the 'task' qualifier on conditional breakpoints as |
| well; in this case, place 'task TASKNO' before the breakpoint |
| condition (before the 'if'). |
| |
| For example, |
| |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 140022020 0 15 Child Activation Wait main_task |
| 2 140045060 1 15 Accept/Select Wait t2 |
| 3 140044840 1 15 Runnable t1 |
| * 4 140056040 1 15 Runnable t3 |
| (gdb) b 15 task 2 |
| Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. |
| (gdb) cont |
| Continuing. |
| task # 1 running |
| task # 2 running |
| |
| Breakpoint 5, test_task_debug () at test_task_debug.adb:15 |
| 15 flush; |
| (gdb) info tasks |
| ID TID P-ID Pri State Name |
| 1 140022020 0 15 Child Activation Wait main_task |
| * 2 140045060 1 15 Runnable t2 |
| 3 140044840 1 15 Runnable t1 |
| 4 140056040 1 15 Delay Sleep t3 |
| |
| |
| File: gdb.info, Node: Ada Tasks and Core Files, Next: Ravenscar Profile, Prev: Ada Tasks, Up: Ada |
| |
| 15.4.9.7 Tasking Support when Debugging Core Files |
| .................................................. |
| |
| When inspecting a core file, as opposed to debugging a live program, |
| tasking support may be limited or even unavailable, depending on the |
| platform being used. For instance, on x86-linux, the list of tasks is |
| available, but task switching is not supported. |
| |
| On certain platforms, the debugger needs to perform some memory |
| writes in order to provide Ada tasking support. When inspecting a core |
| file, this means that the core file must be opened with read-write |
| privileges, using the command '"set write on"' (*note Patching::). |
| Under these circumstances, you should make a backup copy of the core |
| file before inspecting it with GDB. |
| |
| |
| File: gdb.info, Node: Ravenscar Profile, Next: Ada Glitches, Prev: Ada Tasks and Core Files, Up: Ada |
| |
| 15.4.9.8 Tasking Support when using the Ravenscar Profile |
| ......................................................... |
| |
| The "Ravenscar Profile" is a subset of the Ada tasking features, |
| specifically designed for systems with safety-critical real-time |
| requirements. |
| |
| 'set ravenscar task-switching on' |
| Allows task switching when debugging a program that uses the |
| Ravenscar Profile. This is the default. |
| |
| 'set ravenscar task-switching off' |
| Turn off task switching when debugging a program that uses the |
| Ravenscar Profile. This is mostly intended to disable the code |
| that adds support for the Ravenscar Profile, in case a bug in |
| either GDB or in the Ravenscar runtime is preventing GDB from |
| working properly. To be effective, this command should be run |
| before the program is started. |
| |
| 'show ravenscar task-switching' |
| Show whether it is possible to switch from task to task in a |
| program using the Ravenscar Profile. |
| |
| |
| File: gdb.info, Node: Ada Glitches, Prev: Ravenscar Profile, Up: Ada |
| |
| 15.4.9.9 Known Peculiarities of Ada Mode |
| ........................................ |
| |
| Besides the omissions listed previously (*note Omissions from Ada::), we |
| know of several problems with and limitations of Ada mode in GDB, some |
| of which will be fixed with planned future releases of the debugger and |
| the GNU Ada compiler. |
| |
| * Static constants that the compiler chooses not to materialize as |
| objects in storage are invisible to the debugger. |
| |
| * Named parameter associations in function argument lists are ignored |
| (the argument lists are treated as positional). |
| |
| * Many useful library packages are currently invisible to the |
| debugger. |
| |
| * Fixed-point arithmetic, conversions, input, and output is carried |
| out using floating-point arithmetic, and may give results that only |
| approximate those on the host machine. |
| |
| * The GNAT compiler never generates the prefix 'Standard' for any of |
| the standard symbols defined by the Ada language. GDB knows about |
| this: it will strip the prefix from names when you use it, and will |
| never look for a name you have so qualified among local symbols, |
| nor match against symbols in other packages or subprograms. If you |
| have defined entities anywhere in your program other than |
| parameters and local variables whose simple names match names in |
| 'Standard', GNAT's lack of qualification here can cause confusion. |
| When this happens, you can usually resolve the confusion by |
| qualifying the problematic names with package 'Standard' |
| explicitly. |
| |
| Older versions of the compiler sometimes generate erroneous debugging |
| information, resulting in the debugger incorrectly printing the value of |
| affected entities. In some cases, the debugger is able to work around |
| an issue automatically. In other cases, the debugger is able to work |
| around the issue, but the work-around has to be specifically enabled. |
| |
| 'set ada trust-PAD-over-XVS on' |
| Configure GDB to strictly follow the GNAT encoding when computing |
| the value of Ada entities, particularly when 'PAD' and 'PAD___XVS' |
| types are involved (see 'ada/exp_dbug.ads' in the GCC sources for a |
| complete description of the encoding used by the GNAT compiler). |
| This is the default. |
| |
| 'set ada trust-PAD-over-XVS off' |
| This is related to the encoding using by the GNAT compiler. If GDB |
| sometimes prints the wrong value for certain entities, changing |
| 'ada trust-PAD-over-XVS' to 'off' activates a work-around which may |
| fix the issue. It is always safe to set 'ada trust-PAD-over-XVS' |
| to 'off', but this incurs a slight performance penalty, so it is |
| recommended to leave this setting to 'on' unless necessary. |
| |
| Internally, the debugger also relies on the compiler following a |
| number of conventions known as the 'GNAT Encoding', all documented in |
| 'gcc/ada/exp_dbug.ads' in the GCC sources. This encoding describes how |
| the debugging information should be generated for certain types. In |
| particular, this convention makes use of "descriptive types", which are |
| artificial types generated purely to help the debugger. |
| |
| These encodings were defined at a time when the debugging information |
| format used was not powerful enough to describe some of the more complex |
| types available in Ada. Since DWARF allows us to express nearly all Ada |
| features, the long-term goal is to slowly replace these descriptive |
| types by their pure DWARF equivalent. To facilitate that transition, a |
| new maintenance option is available to force the debugger to ignore |
| those descriptive types. It allows the user to quickly evaluate how |
| well GDB works without them. |
| |
| 'maintenance ada set ignore-descriptive-types [on|off]' |
| Control whether the debugger should ignore descriptive types. The |
| default is not to ignore descriptives types ('off'). |
| |
| 'maintenance ada show ignore-descriptive-types' |
| Show if descriptive types are ignored by GDB. |
| |
| |
| File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages |
| |
| 15.5 Unsupported Languages |
| ========================== |
| |
| In addition to the other fully-supported programming languages, GDB also |
| provides a pseudo-language, called 'minimal'. It does not represent a |
| real programming language, but provides a set of capabilities close to |
| what the C or assembly languages provide. This should allow most simple |
| operations to be performed while debugging an application that uses a |
| language currently not supported by GDB. |
| |
| If the language is set to 'auto', GDB will automatically select this |
| language if the current frame corresponds to an unsupported language. |
| |
| |
| File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top |
| |
| 16 Examining the Symbol Table |
| ***************************** |
| |
| The commands described in this chapter allow you to inquire about the |
| symbols (names of variables, functions and types) defined in your |
| program. This information is inherent in the text of your program and |
| does not change as your program executes. GDB finds it in your |
| program's symbol table, in the file indicated when you started GDB |
| (*note Choosing Files: File Options.), or by one of the file-management |
| commands (*note Commands to Specify Files: Files.). |
| |
| Occasionally, you may need to refer to symbols that contain unusual |
| characters, which GDB ordinarily treats as word delimiters. The most |
| frequent case is in referring to static variables in other source files |
| (*note Program Variables: Variables.). File names are recorded in |
| object files as debugging symbols, but GDB would ordinarily parse a |
| typical file name, like 'foo.c', as the three words 'foo' '.' 'c'. To |
| allow GDB to recognize 'foo.c' as a single symbol, enclose it in single |
| quotes; for example, |
| |
| p 'foo.c'::x |
| |
| looks up the value of 'x' in the scope of the file 'foo.c'. |
| |
| 'set case-sensitive on' |
| 'set case-sensitive off' |
| 'set case-sensitive auto' |
| Normally, when GDB looks up symbols, it matches their names with |
| case sensitivity determined by the current source language. |
| Occasionally, you may wish to control that. The command 'set |
| case-sensitive' lets you do that by specifying 'on' for |
| case-sensitive matches or 'off' for case-insensitive ones. If you |
| specify 'auto', case sensitivity is reset to the default suitable |
| for the source language. The default is case-sensitive matches for |
| all languages except for Fortran, for which the default is |
| case-insensitive matches. |
| |
| 'show case-sensitive' |
| This command shows the current setting of case sensitivity for |
| symbols lookups. |
| |
| 'set print type methods' |
| 'set print type methods on' |
| 'set print type methods off' |
| Normally, when GDB prints a class, it displays any methods declared |
| in that class. You can control this behavior either by passing the |
| appropriate flag to 'ptype', or using 'set print type methods'. |
| Specifying 'on' will cause GDB to display the methods; this is the |
| default. Specifying 'off' will cause GDB to omit the methods. |
| |
| 'show print type methods' |
| This command shows the current setting of method display when |
| printing classes. |
| |
| 'set print type typedefs' |
| 'set print type typedefs on' |
| 'set print type typedefs off' |
| |
| Normally, when GDB prints a class, it displays any typedefs defined |
| in that class. You can control this behavior either by passing the |
| appropriate flag to 'ptype', or using 'set print type typedefs'. |
| Specifying 'on' will cause GDB to display the typedef definitions; |
| this is the default. Specifying 'off' will cause GDB to omit the |
| typedef definitions. Note that this controls whether the typedef |
| definition itself is printed, not whether typedef names are |
| substituted when printing other types. |
| |
| 'show print type typedefs' |
| This command shows the current setting of typedef display when |
| printing classes. |
| |
| 'info address SYMBOL' |
| Describe where the data for SYMBOL is stored. For a register |
| variable, this says which register it is kept in. For a |
| non-register local variable, this prints the stack-frame offset at |
| which the variable is always stored. |
| |
| Note the contrast with 'print &SYMBOL', which does not work at all |
| for a register variable, and for a stack local variable prints the |
| exact address of the current instantiation of the variable. |
| |
| 'info symbol ADDR' |
| Print the name of a symbol which is stored at the address ADDR. If |
| no symbol is stored exactly at ADDR, GDB prints the nearest symbol |
| and an offset from it: |
| |
| (gdb) info symbol 0x54320 |
| _initialize_vx + 396 in section .text |
| |
| This is the opposite of the 'info address' command. You can use it |
| to find out the name of a variable or a function given its address. |
| |
| For dynamically linked executables, the name of executable or |
| shared library containing the symbol is also printed: |
| |
| (gdb) info symbol 0x400225 |
| _start + 5 in section .text of /tmp/a.out |
| (gdb) info symbol 0x2aaaac2811cf |
| __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 |
| |
| 'demangle [-l LANGUAGE] [--] NAME' |
| Demangle NAME. If LANGUAGE is provided it is the name of the |
| language to demangle NAME in. Otherwise NAME is demangled in the |
| current language. |
| |
| The '--' option specifies the end of options, and is useful when |
| NAME begins with a dash. |
| |
| The parameter 'demangle-style' specifies how to interpret the kind |
| of mangling used. *Note Print Settings::. |
| |
| 'whatis[/FLAGS] [ARG]' |
| Print the data type of ARG, which can be either an expression or a |
| name of a data type. With no argument, print the data type of '$', |
| the last value in the value history. |
| |
| If ARG is an expression (*note Expressions: Expressions.), it is |
| not actually evaluated, and any side-effecting operations (such as |
| assignments or function calls) inside it do not take place. |
| |
| If ARG is a variable or an expression, 'whatis' prints its literal |
| type as it is used in the source code. If the type was defined |
| using a 'typedef', 'whatis' will _not_ print the data type |
| underlying the 'typedef'. If the type of the variable or the |
| expression is a compound data type, such as 'struct' or 'class', |
| 'whatis' never prints their fields or methods. It just prints the |
| 'struct'/'class' name (a.k.a. its "tag"). If you want to see the |
| members of such a compound data type, use 'ptype'. |
| |
| If ARG is a type name that was defined using 'typedef', 'whatis' |
| "unrolls" only one level of that 'typedef'. Unrolling means that |
| 'whatis' will show the underlying type used in the 'typedef' |
| declaration of ARG. However, if that underlying type is also a |
| 'typedef', 'whatis' will not unroll it. |
| |
| For C code, the type names may also have the form 'class |
| CLASS-NAME', 'struct STRUCT-TAG', 'union UNION-TAG' or 'enum |
| ENUM-TAG'. |
| |
| FLAGS can be used to modify how the type is displayed. Available |
| flags are: |
| |
| 'r' |
| Display in "raw" form. Normally, GDB substitutes template |
| parameters and typedefs defined in a class when printing the |
| class' members. The '/r' flag disables this. |
| |
| 'm' |
| Do not print methods defined in the class. |
| |
| 'M' |
| Print methods defined in the class. This is the default, but |
| the flag exists in case you change the default with 'set print |
| type methods'. |
| |
| 't' |
| Do not print typedefs defined in the class. Note that this |
| controls whether the typedef definition itself is printed, not |
| whether typedef names are substituted when printing other |
| types. |
| |
| 'T' |
| Print typedefs defined in the class. This is the default, but |
| the flag exists in case you change the default with 'set print |
| type typedefs'. |
| |
| 'ptype[/FLAGS] [ARG]' |
| 'ptype' accepts the same arguments as 'whatis', but prints a |
| detailed description of the type, instead of just the name of the |
| type. *Note Expressions: Expressions. |
| |
| Contrary to 'whatis', 'ptype' always unrolls any 'typedef's in its |
| argument declaration, whether the argument is a variable, |
| expression, or a data type. This means that 'ptype' of a variable |
| or an expression will not print literally its type as present in |
| the source code--use 'whatis' for that. 'typedef's at the pointer |
| or reference targets are also unrolled. Only 'typedef's of fields, |
| methods and inner 'class typedef's of 'struct's, 'class'es and |
| 'union's are not unrolled even with 'ptype'. |
| |
| For example, for this variable declaration: |
| |
| typedef double real_t; |
| struct complex { real_t real; double imag; }; |
| typedef struct complex complex_t; |
| complex_t var; |
| real_t *real_pointer_var; |
| |
| the two commands give this output: |
| |
| (gdb) whatis var |
| type = complex_t |
| (gdb) ptype var |
| type = struct complex { |
| real_t real; |
| double imag; |
| } |
| (gdb) whatis complex_t |
| type = struct complex |
| (gdb) whatis struct complex |
| type = struct complex |
| (gdb) ptype struct complex |
| type = struct complex { |
| real_t real; |
| double imag; |
| } |
| (gdb) whatis real_pointer_var |
| type = real_t * |
| (gdb) ptype real_pointer_var |
| type = double * |
| |
| As with 'whatis', using 'ptype' without an argument refers to the |
| type of '$', the last value in the value history. |
| |
| Sometimes, programs use opaque data types or incomplete |
| specifications of complex data structure. If the debug information |
| included in the program does not allow GDB to display a full |
| declaration of the data type, it will say '<incomplete type>'. For |
| example, given these declarations: |
| |
| struct foo; |
| struct foo *fooptr; |
| |
| but no definition for 'struct foo' itself, GDB will say: |
| |
| (gdb) ptype foo |
| $1 = <incomplete type> |
| |
| "Incomplete type" is C terminology for data types that are not |
| completely specified. |
| |
| 'info types REGEXP' |
| 'info types' |
| Print a brief description of all types whose names match the |
| regular expression REGEXP (or all types in your program, if you |
| supply no argument). Each complete typename is matched as though |
| it were a complete line; thus, 'i type value' gives information on |
| all types in your program whose names include the string 'value', |
| but 'i type ^value$' gives information only on types whose complete |
| name is 'value'. |
| |
| This command differs from 'ptype' in two ways: first, like |
| 'whatis', it does not print a detailed description; second, it |
| lists all source files where a type is defined. |
| |
| 'info type-printers' |
| Versions of GDB that ship with Python scripting enabled may have |
| "type printers" available. When using 'ptype' or 'whatis', these |
| printers are consulted when the name of a type is needed. *Note |
| Type Printing API::, for more information on writing type printers. |
| |
| 'info type-printers' displays all the available type printers. |
| |
| 'enable type-printer NAME...' |
| 'disable type-printer NAME...' |
| These commands can be used to enable or disable type printers. |
| |
| 'info scope LOCATION' |
| List all the variables local to a particular scope. This command |
| accepts a LOCATION argument--a function name, a source line, or an |
| address preceded by a '*', and prints all the variables local to |
| the scope defined by that location. (*Note Specify Location::, for |
| details about supported forms of LOCATION.) For example: |
| |
| (gdb) info scope command_line_handler |
| Scope for command_line_handler: |
| Symbol rl is an argument at stack/frame offset 8, length 4. |
| Symbol linebuffer is in static storage at address 0x150a18, length 4. |
| Symbol linelength is in static storage at address 0x150a1c, length 4. |
| Symbol p is a local variable in register $esi, length 4. |
| Symbol p1 is a local variable in register $ebx, length 4. |
| Symbol nline is a local variable in register $edx, length 4. |
| Symbol repeat is a local variable at frame offset -8, length 4. |
| |
| This command is especially useful for determining what data to |
| collect during a "trace experiment", see *note collect: Tracepoint |
| Actions. |
| |
| 'info source' |
| Show information about the current source file--that is, the source |
| file for the function containing the current point of execution: |
| * the name of the source file, and the directory containing it, |
| * the directory it was compiled in, |
| * its length, in lines, |
| * which programming language it is written in, |
| * if the debug information provides it, the program that |
| compiled the file (which may include, e.g., the compiler |
| version and command line arguments), |
| * whether the executable includes debugging information for that |
| file, and if so, what format the information is in (e.g., |
| STABS, Dwarf 2, etc.), and |
| * whether the debugging information includes information about |
| preprocessor macros. |
| |
| 'info sources' |
| Print the names of all source files in your program for which there |
| is debugging information, organized into two lists: files whose |
| symbols have already been read, and files whose symbols will be |
| read when needed. |
| |
| 'info functions' |
| Print the names and data types of all defined functions. |
| |
| 'info functions REGEXP' |
| Print the names and data types of all defined functions whose names |
| contain a match for regular expression REGEXP. Thus, 'info fun |
| step' finds all functions whose names include 'step'; 'info fun |
| ^step' finds those whose names start with 'step'. If a function |
| name contains characters that conflict with the regular expression |
| language (e.g. 'operator*()'), they may be quoted with a backslash. |
| |
| 'info variables' |
| Print the names and data types of all variables that are defined |
| outside of functions (i.e. excluding local variables). |
| |
| 'info variables REGEXP' |
| Print the names and data types of all variables (except for local |
| variables) whose names contain a match for regular expression |
| REGEXP. |
| |
| 'info classes' |
| 'info classes REGEXP' |
| Display all Objective-C classes in your program, or (with the |
| REGEXP argument) all those matching a particular regular |
| expression. |
| |
| 'info selectors' |
| 'info selectors REGEXP' |
| Display all Objective-C selectors in your program, or (with the |
| REGEXP argument) all those matching a particular regular |
| expression. |
| |
| 'set opaque-type-resolution on' |
| Tell GDB to resolve opaque types. An opaque type is a type |
| declared as a pointer to a 'struct', 'class', or 'union'--for |
| example, 'struct MyType *'--that is used in one source file |
| although the full declaration of 'struct MyType' is in another |
| source file. The default is on. |
| |
| A change in the setting of this subcommand will not take effect |
| until the next time symbols for a file are loaded. |
| |
| 'set opaque-type-resolution off' |
| Tell GDB not to resolve opaque types. In this case, the type is |
| printed as follows: |
| {<no data fields>} |
| |
| 'show opaque-type-resolution' |
| Show whether opaque types are resolved or not. |
| |
| 'set print symbol-loading' |
| 'set print symbol-loading full' |
| 'set print symbol-loading brief' |
| 'set print symbol-loading off' |
| The 'set print symbol-loading' command allows you to control the |
| printing of messages when GDB loads symbol information. By default |
| a message is printed for the executable and one for each shared |
| library, and normally this is what you want. However, when |
| debugging apps with large numbers of shared libraries these |
| messages can be annoying. When set to 'brief' a message is printed |
| for each executable, and when GDB loads a collection of shared |
| libraries at once it will only print one message regardless of the |
| number of shared libraries. When set to 'off' no messages are |
| printed. |
| |
| 'show print symbol-loading' |
| Show whether messages will be printed when a GDB command entered |
| from the keyboard causes symbol information to be loaded. |
| |
| 'maint print symbols FILENAME' |
| 'maint print psymbols FILENAME' |
| 'maint print msymbols FILENAME' |
| Write a dump of debugging symbol data into the file FILENAME. |
| These commands are used to debug the GDB symbol-reading code. Only |
| symbols with debugging data are included. If you use 'maint print |
| symbols', GDB includes all the symbols for which it has already |
| collected full details: that is, FILENAME reflects symbols for only |
| those files whose symbols GDB has read. You can use the command |
| 'info sources' to find out which files these are. If you use |
| 'maint print psymbols' instead, the dump shows information about |
| symbols that GDB only knows partially--that is, symbols defined in |
| files that GDB has skimmed, but not yet read completely. Finally, |
| 'maint print msymbols' dumps just the minimal symbol information |
| required for each object file from which GDB has read some symbols. |
| *Note Commands to Specify Files: Files, for a discussion of how GDB |
| reads symbols (in the description of 'symbol-file'). |
| |
| 'maint info symtabs [ REGEXP ]' |
| 'maint info psymtabs [ REGEXP ]' |
| |
| List the 'struct symtab' or 'struct partial_symtab' structures |
| whose names match REGEXP. If REGEXP is not given, list them all. |
| The output includes expressions which you can copy into a GDB |
| debugging this one to examine a particular structure in more |
| detail. For example: |
| |
| (gdb) maint info psymtabs dwarf2read |
| { objfile /home/gnu/build/gdb/gdb |
| ((struct objfile *) 0x82e69d0) |
| { psymtab /home/gnu/src/gdb/dwarf2read.c |
| ((struct partial_symtab *) 0x8474b10) |
| readin no |
| fullname (null) |
| text addresses 0x814d3c8 -- 0x8158074 |
| globals (* (struct partial_symbol **) 0x8507a08 @ 9) |
| statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) |
| dependencies (none) |
| } |
| } |
| (gdb) maint info symtabs |
| (gdb) |
| We see that there is one partial symbol table whose filename |
| contains the string 'dwarf2read', belonging to the 'gdb' |
| executable; and we see that GDB has not read in any symtabs yet at |
| all. If we set a breakpoint on a function, that will cause GDB to |
| read the symtab for the compilation unit containing that function: |
| |
| (gdb) break dwarf2_psymtab_to_symtab |
| Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, |
| line 1574. |
| (gdb) maint info symtabs |
| { objfile /home/gnu/build/gdb/gdb |
| ((struct objfile *) 0x82e69d0) |
| { symtab /home/gnu/src/gdb/dwarf2read.c |
| ((struct symtab *) 0x86c1f38) |
| dirname (null) |
| fullname (null) |
| blockvector ((struct blockvector *) 0x86c1bd0) (primary) |
| linetable ((struct linetable *) 0x8370fa0) |
| debugformat DWARF 2 |
| } |
| } |
| (gdb) |
| |
| 'maint set symbol-cache-size SIZE' |
| Set the size of the symbol cache to SIZE. The default size is |
| intended to be good enough for debugging most applications. This |
| option exists to allow for experimenting with different sizes. |
| |
| 'maint show symbol-cache-size' |
| Show the size of the symbol cache. |
| |
| 'maint print symbol-cache' |
| Print the contents of the symbol cache. This is useful when |
| debugging symbol cache issues. |
| |
| 'maint print symbol-cache-statistics' |
| Print symbol cache usage statistics. This helps determine how well |
| the cache is being utilized. |
| |
| 'maint flush-symbol-cache' |
| Flush the contents of the symbol cache, all entries are removed. |
| This command is useful when debugging the symbol cache. It is also |
| useful when collecting performance data. |
| |
| |
| File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top |
| |
| 17 Altering Execution |
| ********************* |
| |
| Once you think you have found an error in your program, you might want |
| to find out for certain whether correcting the apparent error would lead |
| to correct results in the rest of the run. You can find the answer by |
| experiment, using the GDB features for altering execution of the |
| program. |
| |
| For example, you can store new values into variables or memory |
| locations, give your program a signal, restart it at a different |
| address, or even return prematurely from a function. |
| |
| * Menu: |
| |
| * Assignment:: Assignment to variables |
| * Jumping:: Continuing at a different address |
| * Signaling:: Giving your program a signal |
| * Returning:: Returning from a function |
| * Calling:: Calling your program's functions |
| * Patching:: Patching your program |
| * Compiling and Injecting Code:: Compiling and injecting code in GDB |
| |
| |
| File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering |
| |
| 17.1 Assignment to Variables |
| ============================ |
| |
| To alter the value of a variable, evaluate an assignment expression. |
| *Note Expressions: Expressions. For example, |
| |
| print x=4 |
| |
| stores the value 4 into the variable 'x', and then prints the value of |
| the assignment expression (which is 4). *Note Using GDB with Different |
| Languages: Languages, for more information on operators in supported |
| languages. |
| |
| If you are not interested in seeing the value of the assignment, use |
| the 'set' command instead of the 'print' command. 'set' is really the |
| same as 'print' except that the expression's value is not printed and is |
| not put in the value history (*note Value History: Value History.). The |
| expression is evaluated only for its effects. |
| |
| If the beginning of the argument string of the 'set' command appears |
| identical to a 'set' subcommand, use the 'set variable' command instead |
| of just 'set'. This command is identical to 'set' except for its lack |
| of subcommands. For example, if your program has a variable 'width', |
| you get an error if you try to set a new value with just 'set width=13', |
| because GDB has the command 'set width': |
| |
| (gdb) whatis width |
| type = double |
| (gdb) p width |
| $4 = 13 |
| (gdb) set width=47 |
| Invalid syntax in expression. |
| |
| The invalid expression, of course, is '=47'. In order to actually set |
| the program's variable 'width', use |
| |
| (gdb) set var width=47 |
| |
| Because the 'set' command has many subcommands that can conflict with |
| the names of program variables, it is a good idea to use the 'set |
| variable' command instead of just 'set'. For example, if your program |
| has a variable 'g', you run into problems if you try to set a new value |
| with just 'set g=4', because GDB has the command 'set gnutarget', |
| abbreviated 'set g': |
| |
| (gdb) whatis g |
| type = double |
| (gdb) p g |
| $1 = 1 |
| (gdb) set g=4 |
| (gdb) p g |
| $2 = 1 |
| (gdb) r |
| The program being debugged has been started already. |
| Start it from the beginning? (y or n) y |
| Starting program: /home/smith/cc_progs/a.out |
| "/home/smith/cc_progs/a.out": can't open to read symbols: |
| Invalid bfd target. |
| (gdb) show g |
| The current BFD target is "=4". |
| |
| The program variable 'g' did not change, and you silently set the |
| 'gnutarget' to an invalid value. In order to set the variable 'g', use |
| |
| (gdb) set var g=4 |
| |
| GDB allows more implicit conversions in assignments than C; you can |
| freely store an integer value into a pointer variable or vice versa, and |
| you can convert any structure to any other structure that is the same |
| length or shorter. |
| |
| To store values into arbitrary places in memory, use the '{...}' |
| construct to generate a value of specified type at a specified address |
| (*note Expressions: Expressions.). For example, '{int}0x83040' refers |
| to memory location '0x83040' as an integer (which implies a certain size |
| and representation in memory), and |
| |
| set {int}0x83040 = 4 |
| |
| stores the value 4 into that memory location. |
| |
| |
| File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering |
| |
| 17.2 Continuing at a Different Address |
| ====================================== |
| |
| Ordinarily, when you continue your program, you do so at the place where |
| it stopped, with the 'continue' command. You can instead continue at an |
| address of your own choosing, with the following commands: |
| |
| 'jump LINESPEC' |
| 'j LINESPEC' |
| 'jump LOCATION' |
| 'j LOCATION' |
| Resume execution at line LINESPEC or at address given by LOCATION. |
| Execution stops again immediately if there is a breakpoint there. |
| *Note Specify Location::, for a description of the different forms |
| of LINESPEC and LOCATION. It is common practice to use the |
| 'tbreak' command in conjunction with 'jump'. *Note Setting |
| Breakpoints: Set Breaks. |
| |
| The 'jump' command does not change the current stack frame, or the |
| stack pointer, or the contents of any memory location or any |
| register other than the program counter. If line LINESPEC is in a |
| different function from the one currently executing, the results |
| may be bizarre if the two functions expect different patterns of |
| arguments or of local variables. For this reason, the 'jump' |
| command requests confirmation if the specified line is not in the |
| function currently executing. However, even bizarre results are |
| predictable if you are well acquainted with the machine-language |
| code of your program. |
| |
| On many systems, you can get much the same effect as the 'jump' |
| command by storing a new value into the register '$pc'. The difference |
| is that this does not start your program running; it only changes the |
| address of where it _will_ run when you continue. For example, |
| |
| set $pc = 0x485 |
| |
| makes the next 'continue' command or stepping command execute at address |
| '0x485', rather than at the address where your program stopped. *Note |
| Continuing and Stepping: Continuing and Stepping. |
| |
| The most common occasion to use the 'jump' command is to back |
| up--perhaps with more breakpoints set--over a portion of a program that |
| has already executed, in order to examine its execution in more detail. |
| |