| This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo. |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| END-INFO-DIR-ENTRY |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
| 2010 2011, 2012 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." |
| |
| 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.5. |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
| 2010 2011, 2012 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: 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' |
| 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 0, which tells GDB to always |
| print the symbolic form of an address if any symbol precedes it. |
| |
| `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 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 zero means that the printing 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 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' |
| 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 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. |
| |
| `gnu' |
| Decode based on the GNU C++ compiler (`g++') encoding |
| algorithm. This is the default. |
| |
| `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: Registers, 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. 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' |
| The variable `$_exitcode' is automatically set to the exit code |
| when the program being debugged terminates. |
| |
| `$_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. |
| |
| 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. |
| |
| `help function' |
| Print a list of all convenience functions. |
| |
| |
| File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data |
| |
| 10.12 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. 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'). |
| |
| However, GDB must deduce where registers are saved, from the machine |
| code generated by your compiler. If some registers are not saved, or if |
| GDB is unable to locate the saved registers, the selected stack frame |
| makes no difference. |
| |
| ---------- 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.13 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.14 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.15 Operating System Auxiliary Information |
| ============================================ |
| |
| GDB provides interfaces to useful OS facilities that can help you debug |
| your program. |
| |
| When GDB runs on a "Posix system" (such as GNU or Unix machines), it |
| interfaces with the inferior via the `ptrace' system call. The |
| operating system creates a special sata structure, called `struct |
| user', for this interface. You can use the command `info udot' to |
| display the contents of this data structure. |
| |
| `info udot' |
| Display the contents of the `struct user' maintained by the OS |
| kernel for the program being debugged. GDB displays the contents |
| of `struct user' as a list of hex numbers, similar to the |
| `examine' command. |
| |
| 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: |
| |
| `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. |
| |
| `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. |
| |
| `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. |
| |
| `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. |
| |
| `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. |
| |
| `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. |
| |
| `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. |
| |
| `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. |
| |
| `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.16 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.16.1 Attributes |
| ------------------ |
| |
| 10.16.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.16.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.16.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.16.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.17 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, or Tektronix Hex format; however, GDB can only |
| append to binary 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. |
| |
| 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.18 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, Unixware, and S390). |
| |
| |
| File: gdb.info, Node: Character Sets, Next: Caching Remote Data, Prev: Core File Generation, Up: Data |
| |
| 10.19 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 Remote Data, Next: Searching Memory, Prev: Character Sets, Up: Data |
| |
| 10.20 Caching Data of Remote Targets |
| ==================================== |
| |
| GDB caches data exchanged between the debugger and a remote target |
| (*note Remote Debugging::). Such caching generally improves |
| performance, 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). |
| Other regions of memory can be explicitly marked as cacheable; see |
| *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. |
| |
| `info dcache [line]' |
| Print the information about the data cache performance. 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. See also *Note info |
| dcache: Caching Remote Data. |
| |
| `show dcache line-size' |
| Show default size of dcache lines. See also *Note info dcache: |
| Caching Remote Data. |
| |
| |
| ---------- 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 Remote Data, Up: Data |
| |
| 10.21 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. |
| 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 |
| |
| (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 |
| (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-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' |
| 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.) |
| |
| `target tfile FILENAME' |
| Use the file named FILENAME 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. FILENAME must |
| be on a filesystem accessible to the host. |
| |
| |
| |
| 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 Overlay Description: (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 Overlay |
| Description: (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 |
| ============================ |
| |
| _Warning:_ In this release, the GDB commands for type and range |
| checking are included, but they do not yet have any effect. This |
| section documents the intended facilities. |
| |
| 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. |
| |
| GDB can check for conditions like the above if you wish. 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. As with the working language, GDB can also |
| decide whether or not to check automatically based on your program's |
| source language. *Note Supported Languages: Supported Languages, for |
| the default settings of supported languages. |
| |
| * 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 Modula-2, 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, |
| |
| 1 + 2 => 3 |
| but |
| error--> 1 + 2.3 |
| |
| The second example fails because the `CARDINAL' 1 is not |
| type-compatible with the `REAL' 2.3. |
| |
| For the expressions you use in GDB commands, you can tell the GDB |
| type checker to skip checking; to treat any mismatches as errors and |
| abandon the expression; or to only issue warnings when type mismatches |
| occur, but evaluate the expression anyway. When you choose the last of |
| these, GDB evaluates expressions like the second example above, but |
| also issues a warning. |
| |
| Even if you turn type checking 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, such as the one described |
| above, which make little sense to evaluate anyway. |
| |
| Each language defines to what degree it is strict about type. For |
| instance, both Modula-2 and C require the arguments to arithmetical |
| operators to be numbers. In C, enumerated types and pointers can be |
| represented as numbers, so that they are valid arguments to mathematical |
| operators. *Note Supported Languages: Supported Languages, for further |
| details on specific languages. |
| |
| GDB provides some additional commands for controlling the type |
| checker: |
| |
| `set check type auto' |
| Set type checking on or off based on the current working language. |
| *Note Supported Languages: Supported Languages, for the default |
| settings for each language. |
| |
| `set check type on' |
| `set check type off' |
| Set type checking on or off, overriding the default setting for the |
| current working language. Issue a warning if the setting does not |
| match the language default. If any type mismatches occur in |
| evaluating an expression while type checking is on, GDB prints a |
| message and aborts evaluation of the expression. |
| |
| `set check type warn' |
| Cause the type checker to issue warnings, but to always attempt to |
| evaluate the expression. Evaluating the expression may still be |
| impossible for other reasons. For example, GDB cannot add numbers |
| and structures. |
| |
| `show type' |
| Show the current setting of the type checker, and whether or not |
| GDB is setting it automatically. |
| |
| |
| 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. OP is any |
| one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*', |
| `/', `%'. |
| |
| `?:' |
| The ternary operator. `A ? B : C' can be thought of as: if A |
| then B else C. 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 type and range checking automatically, they |
| both default 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, type checking is not |
| used. However, if you turn type checking on, GDB considers two |
| variables type equivalent if: |
| |
| * The two variables are structured and have the same structure, |
| union, or enumerated tag. |
| |
| * The two variables have the same type name, or types that have been |
| declared equivalent through `typedef'. |
| |
| |
| 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 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. |
| |
| `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. 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). X must be of an ordered |
| type, which include integral, character and enumerated types. |
| |
| `SIZE(X)' |
| Returns the size of its 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. 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 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 Tasks, 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 Tasks, Next: Ada Tasks and Core Files, Prev: Stopping Before Main Program, Up: Ada |
| |
| 15.4.9.5 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::). LINESPEC 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. 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.6 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 Tru64, however, |
| task switching will work as usual. |
| |
| On certain platforms, including Tru64, 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.7 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.8 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. |
| |
| |
| |
| 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. |
| |
| `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 |
| |
| `whatis [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'. |
| |
| `ptype [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 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, |
| |
| * 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. |
| |
| `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) |
| |
| |
| 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 |
| |
| |
| 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' |
| `jump 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. |
| |
| |
| File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering |
| |
| 17.3 Giving your Program a Signal |
| ================================= |
| |
| `signal SIGNAL' |
| Resume execution where your program stopped, but immediately give |
| it the signal SIGNAL. SIGNAL can be the name or the number of a |
| signal. For example, on many systems `signal 2' and `signal |
| SIGINT' are both ways of sending an interrupt signal. |
| |
| Alternatively, if SIGNAL is zero, continue execution without |
| giving a signal. This is useful when your program stopped on |
| account of a signal and would ordinary see the signal when resumed |
| with the `continue' command; `signal 0' causes it to resume |
| without a signal. |
| |
| `signal' does not repeat when you press <RET> a second time after |
| executing the command. |
| |
| Invoking the `signal' command is not the same as invoking the `kill' |
| utility from the shell. Sending a signal with `kill' causes GDB to |
| decide what to do with the signal depending on the signal handling |
| tables (*note Signals::). The `signal' command passes the signal |
| directly to your program. |
| |
| |
| File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering |
| |
| 17.4 Returning from a Function |
| ============================== |
| |
| `return' |
| `return EXPRESSION' |
| You can cancel execution of a function call with the `return' |
| command. If you give an EXPRESSION argument, its value is used as |
| the function's return value. |
| |
| When you use `return', GDB discards the selected stack frame (and |
| all frames within it). You can think of this as making the discarded |
| frame return prematurely. If you wish to specify a value to be |
| returned, give that value as the argument to `return'. |
| |
| This pops the selected stack frame (*note Selecting a Frame: |
| Selection.), and any other frames inside of it, leaving its caller as |
| the innermost remaining frame. That frame becomes selected. The |
| specified value is stored in the registers used for returning values of |
| functions. |
| |
| The `return' command does not resume execution; it leaves the |
| program stopped in the state that would exist if the function had just |
| returned. In contrast, the `finish' command (*note Continuing and |
| Stepping: Continuing and Stepping.) resumes execution until the |
| selected stack frame returns naturally. |
| |
| GDB needs to know how the EXPRESSION argument should be set for the |
| inferior. The concrete registers assignment depends on the OS ABI and |
| the type being returned by the selected stack frame. For example it is |
| common for OS ABI to return floating point values in FPU registers |
| while integer values in CPU registers. Still some ABIs return even |
| floating point values in CPU registers. Larger integer widths (such as |
| `long long int') also have specific placement rules. GDB already knows |
| the OS ABI from its current target so it needs to find out also the |
| type being returned to make the assignment into the right register(s). |
| |
| Normally, the selected stack frame has debug info. GDB will always |
| use the debug info instead of the implicit type of EXPRESSION when the |
| debug info is available. For example, if you type `return -1', and the |
| function in the current stack frame is declared to return a `long long |
| int', GDB transparently converts the implicit `int' value of -1 into a |
| `long long int': |
| |
| Breakpoint 1, func () at gdb.base/return-nodebug.c:29 |
| 29 return 31; |
| (gdb) return -1 |
| Make func return now? (y or n) y |
| #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 |
| 43 printf ("result=%lld\n", func ()); |
| (gdb) |
| |
| However, if the selected stack frame does not have a debug info, |
| e.g., if the function was compiled without debug info, GDB has to find |
| out the type to return from user. Specifying a different type by |
| mistake may set the value in different inferior registers than the |
| caller code expects. For example, typing `return -1' with its implicit |
| type `int' would set only a part of a `long long int' result for a |
| debug info less function (on 32-bit architectures). Therefore the user |
| is required to specify the return type by an appropriate cast |
| explicitly: |
| |
| Breakpoint 2, 0x0040050b in func () |
| (gdb) return -1 |
| Return value type not available for selected stack frame. |
| Please use an explicit cast of the value to return. |
| (gdb) return (long long int) -1 |
| Make selected stack frame return now? (y or n) y |
| #0 0x00400526 in main () |
| (gdb) |
| |
| |
| File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering |
| |
| 17.5 Calling Program Functions |
| ============================== |
| |
| `print EXPR' |
| Evaluate the expression EXPR and display the resulting value. |
| EXPR may include calls to functions in the program being debugged. |
| |
| `call EXPR' |
| Evaluate the expression EXPR without displaying `void' returned |
| values. |
| |
| You can use this variant of the `print' command if you want to |
| execute a function from your program that does not return anything |
| (a.k.a. "a void function"), but without cluttering the output with |
| `void' returned values that GDB will otherwise print. If the |
| result is not void, it is printed and saved in the value history. |
| |
| It is possible for the function you call via the `print' or `call' |
| command to generate a signal (e.g., if there's a bug in the function, |
| or if you passed it incorrect arguments). What happens in that case is |
| controlled by the `set unwindonsignal' command. |
| |
| Similarly, with a C++ program it is possible for the function you |
| call via the `print' or `call' command to generate an exception that is |
| not handled due to the constraints of the dummy frame. In this case, |
| any exception that is raised in the frame, but has an out-of-frame |
| exception handler will not be found. GDB builds a dummy-frame for the |
| inferior function call, and the unwinder cannot seek for exception |
| handlers outside of this dummy-frame. What happens in that case is |
| controlled by the `set unwind-on-terminating-exception' command. |
| |
| `set unwindonsignal' |
| Set unwinding of the stack if a signal is received while in a |
| function that GDB called in the program being debugged. If set to |
| on, GDB unwinds the stack it created for the call and restores the |
| context to what it was before the call. If set to off (the |
| default), GDB stops in the frame where the signal was received. |
| |
| `show unwindonsignal' |
| Show the current setting of stack unwinding in the functions |
| called by GDB. |
| |
| `set unwind-on-terminating-exception' |
| Set unwinding of the stack if a C++ exception is raised, but left |
| unhandled while in a function that GDB called in the program being |
| debugged. If set to on (the default), GDB unwinds the stack it |
| created for the call and restores the context to what it was before |
| the call. If set to off, GDB the exception is delivered to the |
| default C++ exception handler and the inferior terminated. |
| |
| `show unwind-on-terminating-exception' |
| Show the current setting of stack unwinding in the functions |
| called by GDB. |
| |
| |
| Sometimes, a function you wish to call is actually a "weak alias" |
| for another function. In such case, GDB might not pick up the type |
| information, including the types of the function arguments, which |
| causes GDB to call the inferior function incorrectly. As a result, the |
| called function will function erroneously and may even crash. A |
| solution to that is to use the name of the aliased function instead. |
| |
| |
| File: gdb.info, Node: Patching, Prev: Calling, Up: Altering |
| |
| 17.6 Patching Programs |
| ====================== |
| |
| By default, GDB opens the file containing your program's executable |
| code (or the corefile) read-only. This prevents accidental alterations |
| to machine code; but it also prevents you from intentionally patching |
| your program's binary. |
| |
| If you'd like to be able to patch the binary, you can specify that |
| explicitly with the `set write' command. For example, you might want |
| to turn on internal debugging flags, or even to make emergency repairs. |
| |
| `set write on' |
| `set write off' |
| If you specify `set write on', GDB opens executable and core files |
| for both reading and writing; if you specify `set write off' (the |
| default), GDB opens them read-only. |
| |
| If you have already loaded a file, you must load it again (using |
| the `exec-file' or `core-file' command) after changing `set |
| write', for your new setting to take effect. |
| |
| `show write' |
| Display whether executable files and core files are opened for |
| writing as well as reading. |
| |
| |
| File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top |
| |
| 18 GDB Files |
| ************ |
| |
| GDB needs to know the file name of the program to be debugged, both in |
| order to read its symbol table and in order to start your program. To |
| debug a core dump of a previous run, you must also tell GDB the name of |
| the core dump file. |
| |
| * Menu: |
| |
| * Files:: Commands to specify files |
| * Separate Debug Files:: Debugging information in separate files |
| * Index Files:: Index files speed up GDB |
| * Symbol Errors:: Errors reading symbol files |
| * Data Files:: GDB data files |
| |
| |
| File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files |
| |
| 18.1 Commands to Specify Files |
| ============================== |
| |
| You may want to specify executable and core dump file names. The usual |
| way to do this is at start-up time, using the arguments to GDB's |
| start-up commands (*note Getting In and Out of GDB: Invocation.). |
| |
| Occasionally it is necessary to change to a different file during a |
| GDB session. Or you may run GDB and forget to specify a file you want |
| to use. Or you are debugging a remote target via `gdbserver' (*note |
| file: Server.). In these situations the GDB commands to specify new |
| files are useful. |
| |
| `file FILENAME' |
| Use FILENAME as the program to be debugged. It is read for its |
| symbols and for the contents of pure memory. It is also the |
| program executed when you use the `run' command. If you do not |
| specify a directory and the file is not found in the GDB working |
| directory, GDB uses the environment variable `PATH' as a list of |
| directories to search, just as the shell does when looking for a |
| program to run. You can change the value of this variable, for |
| both GDB and your program, using the `path' command. |
| |
| You can load unlinked object `.o' files into GDB using the `file' |
| command. You will not be able to "run" an object file, but you |
| can disassemble functions and inspect variables. Also, if the |
| underlying BFD functionality supports it, you could use `gdb |
| -write' to patch object files using this technique. Note that GDB |
| can neither interpret nor modify relocations in this case, so |
| branches and some initialized variables will appear to go to the |
| wrong place. But this feature is still handy from time to time. |
| |
| `file' |
| `file' with no argument makes GDB discard any information it has |
| on both executable file and the symbol table. |
| |
| `exec-file [ FILENAME ]' |
| Specify that the program to be run (but not the symbol table) is |
| found in FILENAME. GDB searches the environment variable `PATH' |
| if necessary to locate your program. Omitting FILENAME means to |
| discard information on the executable file. |
| |
| `symbol-file [ FILENAME ]' |
| Read symbol table information from file FILENAME. `PATH' is |
| searched when necessary. Use the `file' command to get both symbol |
| table and program to run from the same file. |
| |
| `symbol-file' with no argument clears out GDB information on your |
| program's symbol table. |
| |
| The `symbol-file' command causes GDB to forget the contents of |
| some breakpoints and auto-display expressions. This is because |
| they may contain pointers to the internal data recording symbols |
| and data types, which are part of the old symbol table data being |
| discarded inside GDB. |
| |
| `symbol-file' does not repeat if you press <RET> again after |
| executing it once. |
| |
| When GDB is configured for a particular environment, it |
| understands debugging information in whatever format is the |
| standard generated for that environment; you may use either a GNU |
| compiler, or other compilers that adhere to the local conventions. |
| Best results are usually obtained from GNU compilers; for example, |
| using `GCC' you can generate debugging information for optimized |
| code. |
| |
| For most kinds of object files, with the exception of old SVR3 |
| systems using COFF, the `symbol-file' command does not normally |
| read the symbol table in full right away. Instead, it scans the |
| symbol table quickly to find which source files and which symbols |
| are present. The details are read later, one source file at a |
| time, as they are needed. |
| |
| The purpose of this two-stage reading strategy is to make GDB |
| start up faster. For the most part, it is invisible except for |
| occasional pauses while the symbol table details for a particular |
| source file are being read. (The `set verbose' command can turn |
| these pauses into messages if desired. *Note Optional Warnings |
| and Messages: Messages/Warnings.) |
| |
| We have not implemented the two-stage strategy for COFF yet. When |
| the symbol table is stored in COFF format, `symbol-file' reads the |
| symbol table data in full right away. Note that "stabs-in-COFF" |
| still does the two-stage strategy, since the debug info is actually |
| in stabs format. |
| |
| `symbol-file [ -readnow ] FILENAME' |
| `file [ -readnow ] FILENAME' |
| You can override the GDB two-stage strategy for reading symbol |
| tables by using the `-readnow' option with any of the commands that |
| load symbol table information, if you want to be sure GDB has the |
| entire symbol table available. |
| |
| `core-file [FILENAME]' |
| `core' |
| Specify the whereabouts of a core dump file to be used as the |
| "contents of memory". Traditionally, core files contain only some |
| parts of the address space of the process that generated them; GDB |
| can access the executable file itself for other parts. |
| |
| `core-file' with no argument specifies that no core file is to be |
| used. |
| |
| Note that the core file is ignored when your program is actually |
| running under GDB. So, if you have been running your program and |
| you wish to debug a core file instead, you must kill the |
| subprocess in which the program is running. To do this, use the |
| `kill' command (*note Killing the Child Process: Kill Process.). |
| |
| `add-symbol-file FILENAME ADDRESS' |
| `add-symbol-file FILENAME ADDRESS [ -readnow ]' |
| `add-symbol-file FILENAME ADDRESS -s SECTION ADDRESS ...' |
| The `add-symbol-file' command reads additional symbol table |
| information from the file FILENAME. You would use this command |
| when FILENAME has been dynamically loaded (by some other means) |
| into the program that is running. ADDRESS should be the memory |
| address at which the file has been loaded; GDB cannot figure this |
| out for itself. You can additionally specify an arbitrary number |
| of `-s SECTION ADDRESS' pairs, to give an explicit section name |
| and base address for that section. You can specify any ADDRESS as |
| an expression. |
| |
| The symbol table of the file FILENAME is added to the symbol table |
| originally read with the `symbol-file' command. You can use the |
| `add-symbol-file' command any number of times; the new symbol data |
| thus read keeps adding to the old. To discard all old symbol data |
| instead, use the `symbol-file' command without any arguments. |
| |
| Although FILENAME is typically a shared library file, an |
| executable file, or some other object file which has been fully |
| relocated for loading into a process, you can also load symbolic |
| information from relocatable `.o' files, as long as: |
| |
| * the file's symbolic information refers only to linker symbols |
| defined in that file, not to symbols defined by other object |
| files, |
| |
| * every section the file's symbolic information refers to has |
| actually been loaded into the inferior, as it appears in the |
| file, and |
| |
| * you can determine the address at which every section was |
| loaded, and provide these to the `add-symbol-file' command. |
| |
| Some embedded operating systems, like Sun Chorus and VxWorks, can |
| load relocatable files into an already running program; such |
| systems typically make the requirements above easy to meet. |
| However, it's important to recognize that many native systems use |
| complex link procedures (`.linkonce' section factoring and C++ |
| constructor table assembly, for example) that make the |
| requirements difficult to meet. In general, one cannot assume |
| that using `add-symbol-file' to read a relocatable object file's |
| symbolic information will have the same effect as linking the |
| relocatable object file into the program in the normal way. |
| |
| `add-symbol-file' does not repeat if you press <RET> after using |
| it. |
| |
| `add-symbol-file-from-memory ADDRESS' |
| Load symbols from the given ADDRESS in a dynamically loaded object |
| file whose image is mapped directly into the inferior's memory. |
| For example, the Linux kernel maps a `syscall DSO' into each |
| process's address space; this DSO provides kernel-specific code for |
| some system calls. The argument can be any expression whose |
| evaluation yields the address of the file's shared object file |
| header. For this command to work, you must have used |
| `symbol-file' or `exec-file' commands in advance. |
| |
| `add-shared-symbol-files LIBRARY-FILE' |
| `assf LIBRARY-FILE' |
| The `add-shared-symbol-files' command can currently be used only |
| in the Cygwin build of GDB on MS-Windows OS, where it is an alias |
| for the `dll-symbols' command (*note Cygwin Native::). GDB |
| automatically looks for shared libraries, however if GDB does not |
| find yours, you can invoke `add-shared-symbol-files'. It takes |
| one argument: the shared library's file name. `assf' is a |
| shorthand alias for `add-shared-symbol-files'. |
| |
| `section SECTION ADDR' |
| The `section' command changes the base address of the named |
| SECTION of the exec file to ADDR. This can be used if the exec |
| file does not contain section addresses, (such as in the `a.out' |
| format), or when the addresses specified in the file itself are |
| wrong. Each section must be changed separately. The `info files' |
| command, described below, lists all the sections and their |
| addresses. |
| |
| `info files' |
| `info target' |
| `info files' and `info target' are synonymous; both print the |
| current target (*note Specifying a Debugging Target: Targets.), |
| including the names of the executable and core dump files |
| currently in use by GDB, and the files from which symbols were |
| loaded. The command `help target' lists all possible targets |
| rather than current ones. |
| |
| `maint info sections' |
| Another command that can give you extra information about program |
| sections is `maint info sections'. In addition to the section |
| information displayed by `info files', this command displays the |
| flags and file offset of each section in the executable and core |
| dump files. In addition, `maint info sections' provides the |
| following command options (which may be arbitrarily combined): |
| |
| `ALLOBJ' |
| Display sections for all loaded object files, including |
| shared libraries. |
| |
| `SECTIONS' |
| Display info only for named SECTIONS. |
| |
| `SECTION-FLAGS' |
| Display info only for sections for which SECTION-FLAGS are |
| true. The section flags that GDB currently knows about are: |
| `ALLOC' |
| Section will have space allocated in the process when |
| loaded. Set for all sections except those containing |
| debug information. |
| |
| `LOAD' |
| Section will be loaded from the file into the child |
| process memory. Set for pre-initialized code and data, |
| clear for `.bss' sections. |
| |
| `RELOC' |
| Section needs to be relocated before loading. |
| |
| `READONLY' |
| Section cannot be modified by the child process. |
| |
| `CODE' |
| Section contains executable code only. |
| |
| `DATA' |
| Section contains data only (no executable code). |
| |
| `ROM' |
| Section will reside in ROM. |
| |
| `CONSTRUCTOR' |
| Section contains data for constructor/destructor lists. |
| |
| `HAS_CONTENTS' |
| Section is not empty. |
| |
| `NEVER_LOAD' |
| An instruction to the linker to not output the section. |
| |
| `COFF_SHARED_LIBRARY' |
| A notification to the linker that the section contains |
| COFF shared library information. |
| |
| `IS_COMMON' |
| Section contains common symbols. |
| |
| `set trust-readonly-sections on' |
| Tell GDB that readonly sections in your object file really are |
| read-only (i.e. that their contents will not change). In that |
| case, GDB can fetch values from these sections out of the object |
| file, rather than from the target program. For some targets |
| (notably embedded ones), this can be a significant enhancement to |
| debugging performance. |
| |
| The default is off. |
| |
| `set trust-readonly-sections off' |
| Tell GDB not to trust readonly sections. This means that the |
| contents of the section might change while the program is running, |
| and must therefore be fetched from the target when needed. |
| |
| `show trust-readonly-sections' |
| Show the current setting of trusting readonly sections. |
| |
| All file-specifying commands allow both absolute and relative file |
| names as arguments. GDB always converts the file name to an absolute |
| file name and remembers it that way. |
| |
| GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and |
| IBM RS/6000 AIX shared libraries. |
| |
| On MS-Windows GDB must be linked with the Expat library to support |
| shared libraries. *Note Expat::. |
| |
| GDB automatically loads symbol definitions from shared libraries |
| when you use the `run' command, or when you examine a core file. |
| (Before you issue the `run' command, GDB does not understand references |
| to a function in a shared library, however--unless you are debugging a |
| core file). |
| |
| On HP-UX, if the program loads a library explicitly, GDB |
| automatically loads the symbols at the time of the `shl_load' call. |
| |
| There are times, however, when you may wish to not automatically load |
| symbol definitions from shared libraries, such as when they are |
| particularly large or there are many of them. |
| |
| To control the automatic loading of shared library symbols, use the |
| commands: |
| |
| `set auto-solib-add MODE' |
| If MODE is `on', symbols from all shared object libraries will be |
| loaded automatically when the inferior begins execution, you |
| attach to an independently started inferior, or when the dynamic |
| linker informs GDB that a new library has been loaded. If MODE is |
| `off', symbols must be loaded manually, using the `sharedlibrary' |
| command. The default value is `on'. |
| |
| If your program uses lots of shared libraries with debug info that |
| takes large amounts of memory, you can decrease the GDB memory |
| footprint by preventing it from automatically loading the symbols |
| from shared libraries. To that end, type `set auto-solib-add off' |
| before running the inferior, then load each library whose debug |
| symbols you do need with `sharedlibrary REGEXP', where REGEXP is a |
| regular expression that matches the libraries whose symbols you |
| want to be loaded. |
| |
| `show auto-solib-add' |
| Display the current autoloading mode. |
| |
| To explicitly load shared library symbols, use the `sharedlibrary' |
| command: |
| |
| `info share REGEX' |
| `info sharedlibrary REGEX' |
| Print the names of the shared libraries which are currently loaded |
| that match REGEX. If REGEX is omitted then print all shared |
| libraries that are loaded. |
| |
| `sharedlibrary REGEX' |
| `share REGEX' |
| Load shared object library symbols for files matching a Unix |
| regular expression. As with files loaded automatically, it only |
| loads shared libraries required by your program for a core file or |
| after typing `run'. If REGEX is omitted all shared libraries |
| required by your program are loaded. |
| |
| `nosharedlibrary' |
| Unload all shared object library symbols. This discards all |
| symbols that have been loaded from all shared libraries. Symbols |
| from shared libraries that were loaded by explicit user requests |
| are not discarded. |
| |
| Sometimes you may wish that GDB stops and gives you control when any |
| of shared library events happen. The best way to do this is to use |
| `catch load' and `catch unload' (*note Set Catchpoints::). |
| |
| GDB also supports the the `set stop-on-solib-events' command for |
| this. This command exists for historical reasons. It is less useful |
| than setting a catchpoint, because it does not allow for conditions or |
| commands as a catchpoint does. |
| |
| `set stop-on-solib-events' |
| This command controls whether GDB should give you control when the |
| dynamic linker notifies it about some shared library event. The |
| most common event of interest is loading or unloading of a new |
| shared library. |
| |
| `show stop-on-solib-events' |
| Show whether GDB stops and gives you control when shared library |
| events happen. |
| |
| Shared libraries are also supported in many cross or remote debugging |
| configurations. GDB needs to have access to the target's libraries; |
| this can be accomplished either by providing copies of the libraries on |
| the host system, or by asking GDB to automatically retrieve the |
| libraries from the target. If copies of the target libraries are |
| provided, they need to be the same as the target libraries, although the |
| copies on the target can be stripped as long as the copies on the host |
| are not. |
| |
| For remote debugging, you need to tell GDB where the target |
| libraries are, so that it can load the correct copies--otherwise, it |
| may try to load the host's libraries. GDB has two variables to specify |
| the search directories for target libraries. |
| |
| `set sysroot PATH' |
| Use PATH as the system root for the program being debugged. Any |
| absolute shared library paths will be prefixed with PATH; many |
| runtime loaders store the absolute paths to the shared library in |
| the target program's memory. If you use `set sysroot' to find |
| shared libraries, they need to be laid out in the same way that |
| they are on the target, with e.g. a `/lib' and `/usr/lib' hierarchy |
| under PATH. |
| |
| If PATH starts with the sequence `remote:', GDB will retrieve the |
| target libraries from the remote system. This is only supported |
| when using a remote target that supports the `remote get' command |
| (*note Sending files to a remote system: File Transfer.). The |
| part of PATH following the initial `remote:' (if present) is used |
| as system root prefix on the remote file system. (1) |
| |
| For targets with an MS-DOS based filesystem, such as MS-Windows and |
| SymbianOS, GDB tries prefixing a few variants of the target |
| absolute file name with PATH. But first, on Unix hosts, GDB |
| converts all backslash directory separators into forward slashes, |
| because the backslash is not a directory separator on Unix: |
| |
| c:\foo\bar.dll => c:/foo/bar.dll |
| |
| Then, GDB attempts prefixing the target file name with PATH, and |
| looks for the resulting file name in the host file system: |
| |
| c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll |
| |
| If that does not find the shared library, GDB tries removing the |
| `:' character from the drive spec, both for convenience, and, for |
| the case of the host file system not supporting file names with |
| colons: |
| |
| c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll |
| |
| This makes it possible to have a system root that mirrors a target |
| with more than one drive. E.g., you may want to setup your local |
| copies of the target system shared libraries like so (note `c' vs |
| `z'): |
| |
| `/path/to/sysroot/c/sys/bin/foo.dll' |
| `/path/to/sysroot/c/sys/bin/bar.dll' |
| `/path/to/sysroot/z/sys/bin/bar.dll' |
| |
| and point the system root at `/path/to/sysroot', so that GDB can |
| find the correct copies of both `c:\sys\bin\foo.dll', and |
| `z:\sys\bin\bar.dll'. |
| |
| If that still does not find the shared library, GDB tries removing |
| the whole drive spec from the target file name: |
| |
| c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll |
| |
| This last lookup makes it possible to not care about the drive |
| name, if you don't want or need to. |
| |
| The `set solib-absolute-prefix' command is an alias for `set |
| sysroot'. |
| |
| You can set the default system root by using the configure-time |
| `--with-sysroot' option. If the system root is inside GDB's |
| configured binary prefix (set with `--prefix' or `--exec-prefix'), |
| then the default system root will be updated automatically if the |
| installed GDB is moved to a new location. |
| |
| `show sysroot' |
| Display the current shared library prefix. |
| |
| `set solib-search-path PATH' |
| If this variable is set, PATH is a colon-separated list of |
| directories to search for shared libraries. `solib-search-path' |
| is used after `sysroot' fails to locate the library, or if the |
| path to the library is relative instead of absolute. If you want |
| to use `solib-search-path' instead of `sysroot', be sure to set |
| `sysroot' to a nonexistent directory to prevent GDB from finding |
| your host's libraries. `sysroot' is preferred; setting it to a |
| nonexistent directory may interfere with automatic loading of |
| shared library symbols. |
| |
| `show solib-search-path' |
| Display the current shared library search path. |
| |
| `set target-file-system-kind KIND' |
| Set assumed file system kind for target reported file names. |
| |
| Shared library file names as reported by the target system may not |
| make sense as is on the system GDB is running on. For example, |
| when remote debugging a target that has MS-DOS based file system |
| semantics, from a Unix host, the target may be reporting to GDB a |
| list of loaded shared libraries with file names such as |
| `c:\Windows\kernel32.dll'. On Unix hosts, there's no concept of |
| drive letters, so the `c:\' prefix is not normally understood as |
| indicating an absolute file name, and neither is the backslash |
| normally considered a directory separator character. In that case, |
| the native file system would interpret this whole absolute file |
| name as a relative file name with no directory components. This |
| would make it impossible to point GDB at a copy of the remote |
| target's shared libraries on the host using `set sysroot', and |
| impractical with `set solib-search-path'. Setting |
| `target-file-system-kind' to `dos-based' tells GDB to interpret |
| such file names similarly to how the target would, and to map them |
| to file names valid on GDB's native file system semantics. The |
| value of KIND can be `"auto"', in addition to one of the supported |
| file system kinds. In that case, GDB tries to determine the |
| appropriate file system variant based on the current target's |
| operating system (*note Configuring the Current ABI: ABI.). The |
| supported file system settings are: |
| |
| `unix' |
| Instruct GDB to assume the target file system is of Unix |
| kind. Only file names starting the forward slash (`/') |
| character are considered absolute, and the directory |
| separator character is also the forward slash. |
| |
| `dos-based' |
| Instruct GDB to assume the target file system is DOS based. |
| File names starting with either a forward slash, or a drive |
| letter followed by a colon (e.g., `c:'), are considered |
| absolute, and both the slash (`/') and the backslash (`\\') |
| characters are considered directory separators. |
| |
| `auto' |
| Instruct GDB to use the file system kind associated with the |
| target operating system (*note Configuring the Current ABI: |
| ABI.). This is the default. |
| |
| When processing file names provided by the user, GDB frequently |
| needs to compare them to the file names recorded in the program's debug |
| info. Normally, GDB compares just the "base names" of the files as |
| strings, which is reasonably fast even for very large programs. (The |
| base name of a file is the last portion of its name, after stripping |
| all the leading directories.) This shortcut in comparison is based |
| upon the assumption that files cannot have more than one base name. |
| This is usually true, but references to files that use symlinks or |
| similar filesystem facilities violate that assumption. If your program |
| records files using such facilities, or if you provide file names to |
| GDB using symlinks etc., you can set `basenames-may-differ' to `true' |
| to instruct GDB to completely canonicalize each pair of file names it |
| needs to compare. This will make file-name comparisons accurate, but |
| at a price of a significant slowdown. |
| |
| `set basenames-may-differ' |
| Set whether a source file may have multiple base names. |
| |
| `show basenames-may-differ' |
| Show whether a source file may have multiple base names. |
| |
| ---------- Footnotes ---------- |
| |
| (1) If you want to specify a local system root using a directory |
| that happens to be named `remote:', you need to use some equivalent |
| variant of the name like `./remote:'. |
| |
| |
| File: gdb.info, Node: Separate Debug Files, Next: Index Files, Prev: Files, Up: GDB Files |
| |
| 18.2 Debugging Information in Separate Files |
| ============================================ |
| |
| GDB allows you to put a program's debugging information in a file |
| separate from the executable itself, in a way that allows GDB to find |
| and load the debugging information automatically. Since debugging |
| information can be very large--sometimes larger than the executable |
| code itself--some systems distribute debugging information for their |
| executables in separate files, which users can install only when they |
| need to debug a problem. |
| |
| GDB supports two ways of specifying the separate debug info file: |
| |
| * The executable contains a "debug link" that specifies the name of |
| the separate debug info file. The separate debug file's name is |
| usually `EXECUTABLE.debug', where EXECUTABLE is the name of the |
| corresponding executable file without leading directories (e.g., |
| `ls.debug' for `/usr/bin/ls'). In addition, the debug link |
| specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for |
| the debug file, which GDB uses to validate that the executable and |
| the debug file came from the same build. |
| |
| * The executable contains a "build ID", a unique bit string that is |
| also present in the corresponding debug info file. (This is |
| supported only on some operating systems, notably those which use |
| the ELF format for binary files and the GNU Binutils.) For more |
| details about this feature, see the description of the `--build-id' |
| command-line option in *Note Command Line Options: |
| (ld.info)Options. The debug info file's name is not specified |
| explicitly by the build ID, but can be computed from the build ID, |
| see below. |
| |
| Depending on the way the debug info file is specified, GDB uses two |
| different methods of looking for the debug file: |
| |
| * For the "debug link" method, GDB looks up the named file in the |
| directory of the executable file, then in a subdirectory of that |
| directory named `.debug', and finally under each one of the global |
| debug directories, in a subdirectory whose name is identical to |
| the leading directories of the executable's absolute file name. |
| |
| * For the "build ID" method, GDB looks in the `.build-id' |
| subdirectory of each one of the global debug directories for a |
| file named `NN/NNNNNNNN.debug', where NN are the first 2 hex |
| characters of the build ID bit string, and NNNNNNNN are the rest |
| of the bit string. (Real build ID strings are 32 or more hex |
| characters, not 10.) |
| |
| So, for example, suppose you ask GDB to debug `/usr/bin/ls', which |
| has a debug link that specifies the file `ls.debug', and a build ID |
| whose value in hex is `abcdef1234'. If the list of the global debug |
| directories includes `/usr/lib/debug', then GDB will look for the |
| following debug information files, in the indicated order: |
| |
| - `/usr/lib/debug/.build-id/ab/cdef1234.debug' |
| |
| - `/usr/bin/ls.debug' |
| |
| - `/usr/bin/.debug/ls.debug' |
| |
| - `/usr/lib/debug/usr/bin/ls.debug'. |
| |
| Global debugging info directories default to what is set by GDB |
| configure option `--with-separate-debug-dir'. During GDB run you can |
| also set the global debugging info directories, and view the list GDB |
| is currently using. |
| |
| `set debug-file-directory DIRECTORIES' |
| Set the directories which GDB searches for separate debugging |
| information files to DIRECTORY. Multiple path components can be |
| set concatenating them by a path separator. |
| |
| `show debug-file-directory' |
| Show the directories GDB searches for separate debugging |
| information files. |
| |
| |
| A debug link is a special section of the executable file named |
| `.gnu_debuglink'. The section must contain: |
| |
| * A filename, with any leading directory components removed, |
| followed by a zero byte, |
| |
| * zero to three bytes of padding, as needed to reach the next |
| four-byte boundary within the section, and |
| |
| * a four-byte CRC checksum, stored in the same endianness used for |
| the executable file itself. The checksum is computed on the |
| debugging information file's full contents by the function given |
| below, passing zero as the CRC argument. |
| |
| Any executable file format can carry a debug link, as long as it can |
| contain a section named `.gnu_debuglink' with the contents described |
| above. |
| |
| The build ID is a special section in the executable file (and in |
| other ELF binary files that GDB may consider). This section is often |
| named `.note.gnu.build-id', but that name is not mandatory. It |
| contains unique identification for the built files--the ID remains the |
| same across multiple builds of the same build tree. The default |
| algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the |
| content for the build ID string. The same section with an identical |
| value is present in the original built binary with symbols, in its |
| stripped variant, and in the separate debugging information file. |
| |
| The debugging information file itself should be an ordinary |
| executable, containing a full set of linker symbols, sections, and |
| debugging information. The sections of the debugging information file |
| should have the same names, addresses, and sizes as the original file, |
| but they need not contain any data--much like a `.bss' section in an |
| ordinary executable. |
| |
| The GNU binary utilities (Binutils) package includes the `objcopy' |
| utility that can produce the separated executable / debugging |
| information file pairs using the following commands: |
| |
| objcopy --only-keep-debug foo foo.debug |
| strip -g foo |
| |
| These commands remove the debugging information from the executable |
| file `foo' and place it in the file `foo.debug'. You can use the |
| first, second or both methods to link the two files: |
| |
| * The debug link method needs the following additional command to |
| also leave behind a debug link in `foo': |
| |
| objcopy --add-gnu-debuglink=foo.debug foo |
| |
| Ulrich Drepper's `elfutils' package, starting with version 0.53, |
| contains a version of the `strip' command such that the command |
| `strip foo -f foo.debug' has the same functionality as the two |
| `objcopy' commands and the `ln -s' command above, together. |
| |
| * Build ID gets embedded into the main executable using `ld |
| --build-id' or the GCC counterpart `gcc -Wl,--build-id'. Build ID |
| support plus compatibility fixes for debug files separation are |
| present in GNU binary utilities (Binutils) package since version |
| 2.18. |
| |
| The CRC used in `.gnu_debuglink' is the CRC-32 defined in IEEE 802.3 |
| using the polynomial: |
| |
| x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 |
| + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1 |
| |
| The function is computed byte at a time, taking the least |
| significant bit of each byte first. The initial pattern `0xffffffff' |
| is used, to ensure leading zeros affect the CRC and the final result is |
| inverted to ensure trailing zeros also affect the CRC. |
| |
| _Note:_ This is the same CRC polynomial as used in handling the |
| "Remote Serial Protocol" `qCRC' packet (*note GDB Remote Serial |
| Protocol: Remote Protocol.). However in the case of the Remote Serial |
| Protocol, the CRC is computed _most_ significant bit first, and the |
| result is not inverted, so trailing zeros have no effect on the CRC |
| value. |
| |
| To complete the description, we show below the code of the function |
| which produces the CRC used in `.gnu_debuglink'. Inverting the |
| initially supplied `crc' argument means that an initial call to this |
| function passing in zero will start computing the CRC using |
| `0xffffffff'. |
| |
| unsigned long |
| gnu_debuglink_crc32 (unsigned long crc, |
| unsigned char *buf, size_t len) |
| { |
| static const unsigned long crc32_table[256] = |
| { |
| 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, |
| 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, |
| 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, |
| 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, |
| 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, |
| 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, |
| 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, |
| 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, |
| 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, |
| 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, |
| 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, |
| 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, |
| 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, |
| 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, |
| 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, |
| 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, |
| 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, |
| 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, |
| 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, |
| 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, |
| 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, |
| 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, |
| 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, |
| 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, |
| 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, |
| 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, |
| 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, |
| 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, |
| 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, |
| 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, |
| 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, |
| 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, |
| 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, |
| 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, |
| 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, |
| 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, |
| 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, |
| 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, |
| 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, |
| 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, |
| 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, |
| 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, |
| 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, |
| 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, |
| 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, |
| 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, |
| 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, |
| 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, |
| 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, |
| 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, |
| 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, |
| 0x2d02ef8d |
| }; |
| unsigned char *end; |
| |
| crc = ~crc & 0xffffffff; |
| for (end = buf + len; buf < end; ++buf) |
| crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); |
| return ~crc & 0xffffffff; |
| } |
| |
| This computation does not apply to the "build ID" method. |
| |
| |
| File: gdb.info, Node: Index Files, Next: Symbol Errors, Prev: Separate Debug Files, Up: GDB Files |
| |
| 18.3 Index Files Speed Up GDB |
| ============================= |
| |
| When GDB finds a symbol file, it scans the symbols in the file in order |
| to construct an internal symbol table. This lets most GDB operations |
| work quickly--at the cost of a delay early on. For large programs, |
| this delay can be quite lengthy, so GDB provides a way to build an |
| index, which speeds up startup. |
| |
| The index is stored as a section in the symbol file. GDB can write |
| the index to a file, then you can put it into the symbol file using |
| `objcopy'. |
| |
| To create an index file, use the `save gdb-index' command: |
| |
| `save gdb-index DIRECTORY' |
| Create an index file for each symbol file currently known by GDB. |
| Each file is named after its corresponding symbol file, with |
| `.gdb-index' appended, and is written into the given DIRECTORY. |
| |
| Once you have created an index file you can merge it into your symbol |
| file, here named `symfile', using `objcopy': |
| |
| $ objcopy --add-section .gdb_index=symfile.gdb-index \ |
| --set-section-flags .gdb_index=readonly symfile symfile |
| |
| GDB will normally ignore older versions of `.gdb_index' sections |
| that have been deprecated. Usually they are deprecated because they |
| are missing a new feature or have performance issues. To tell GDB to |
| use a deprecated index section anyway specify `set |
| use-deprecated-index-sections on'. The default is `off'. This can |
| speed up startup, but may result in some functionality being lost. |
| *Note Index Section Format::. |
| |
| _Warning:_ Setting `use-deprecated-index-sections' to `on' must be |
| done before gdb reads the file. The following will not work: |
| |
| $ gdb -ex "set use-deprecated-index-sections on" <program> |
| |
| Instead you must do, for example, |
| |
| $ gdb -iex "set use-deprecated-index-sections on" <program> |
| |
| There are currently some limitation on indices. They only work when |
| for DWARF debugging information, not stabs. And, they do not currently |
| work for programs using Ada. |
| |