diff options
Diffstat (limited to 'gdb/doc/gdb.info-4')
| -rw-r--r-- | gdb/doc/gdb.info-4 | 1279 |
1 files changed, 1279 insertions, 0 deletions
diff --git a/gdb/doc/gdb.info-4 b/gdb/doc/gdb.info-4 new file mode 100644 index 00000000000..b20956c4d64 --- /dev/null +++ b/gdb/doc/gdb.info-4 @@ -0,0 +1,1279 @@ +This is Info file ./gdb.info, produced by Makeinfo version 1.68 from +the input file gdb.texinfo. + +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +END-INFO-DIR-ENTRY + This file documents the GNU debugger GDB. + + This is the Seventh Edition, February 1999, of `Debugging with GDB: +the GNU Source-Level Debugger' for GDB Version 4.18. + + Copyright (C) 1988-1999 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the entire resulting derived work is distributed under the terms +of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions. + + +File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data + +Artificial arrays +================= + + It is often useful to print out several successive objects of the +same type in memory; a section of an array, or an array of dynamically +determined size for which only a pointer exists in the program. + + You can do this by referring to a contiguous span of memory as an +"artificial array", using the binary operator `@'. The left operand of +`@' should be the first element of the desired array and be an +individual object. The right operand should be the desired length of +the array. The result is an array value whose elements are all of the +type of the left argument. The first element is actually the left +argument; the second element comes from bytes of memory immediately +following those that hold the first element, and so on. Here is an +example. If a program says + + int *array = (int *) malloc (len * sizeof (int)); + +you can print the contents of `array' with + + p *array@len + + The left operand of `@' must reside in memory. Array values made +with `@' in this way behave just like other arrays in terms of +subscripting, and are coerced to pointers when used in expressions. +Artificial arrays most often appear in expressions via the value history +(*note Value history: Value History.), after printing one out. + + Another way to create an artificial array is to use a cast. This +re-interprets a value as if it were an array. The value need not be in +memory: + (gdb) p/x (short[2])0x12345678 + $1 = {0x1234, 0x5678} + + As a convenience, if you leave the array length out (as in +`(TYPE)[])VALUE') gdb calculates the size to fill the value (as +`sizeof(VALUE)/sizeof(TYPE)': + (gdb) p/x (short[])0x12345678 + $2 = {0x1234, 0x5678} + + Sometimes the artificial array mechanism is not quite enough; in +moderately complex data structures, the elements of interest may not +actually be adjacent--for example, if you are interested in the values +of pointers in an array. One useful work-around in this situation is +to use a convenience variable (*note Convenience variables: Convenience +Vars.) as a counter in an expression that prints the first interesting +value, and then repeat that expression via <RET>. For instance, +suppose you have an array `dtab' of pointers to structures, and you are +interested in the values of a field `fv' in each structure. Here is an +example of what you might type: + + set $i = 0 + p dtab[$i++]->fv + <RET> + <RET> + ... + + +File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data + +Output formats +============== + + By default, GDB prints a value according to its data type. Sometimes +this is not what you want. For example, you might want to print a +number in hex, or a pointer in decimal. Or you might want to view data +in memory at a certain address as a character string or as an +instruction. To do these things, specify an "output format" when you +print a value. + + The simplest use of output formats is to say how to print a value +already computed. This is done by starting the arguments of the +`print' command with a slash and a format letter. The format letters +supported are: + +`x' + Regard the bits of the value as an integer, and print the integer + in hexadecimal. + +`d' + Print as integer in signed decimal. + +`u' + Print as integer in unsigned decimal. + +`o' + Print as integer in octal. + +`t' + Print as integer in binary. The letter `t' stands for "two". (1) + +`a' + Print as an address, both absolute in hexadecimal and as an offset + from the nearest preceding symbol. You can use this format used + to discover where (in what function) an unknown address is located: + + (gdb) p/a 0x54320 + $3 = 0x54320 <_initialize_vx+396> + +`c' + Regard as an integer and print it as a character constant. + +`f' + Regard the bits of the value as a floating point number and print + using typical floating point syntax. + + For example, to print the program counter in hex (*note +Registers::.), type + + p/x $pc + +Note that no space is required before the slash; this is because command +names in GDB cannot contain a slash. + + To reprint the last value in the value history with a different +format, you can use the `print' command with just a format and no +expression. For example, `p/x' reprints the last value in hex. + + ---------- Footnotes ---------- + + (1) `b' cannot be used because these format letters are also used +with the `x' command, where `b' stands for "byte"; *note Examining +memory: Memory.. + + +File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data + +Examining memory +================ + + You can use the command `x' (for "examine") to examine memory in any +of several formats, independently of your program's data types. + +`x/NFU ADDR' +`x ADDR' +`x' + Use the `x' command to examine memory. + + N, F, and U are all optional parameters that specify how much memory +to display and how to format it; ADDR is an expression giving the +address where you want to start displaying memory. If you use defaults +for NFU, you need not type the slash `/'. Several commands set +convenient defaults for ADDR. + +N, the repeat count + The repeat count is a decimal integer; the default is 1. It + specifies how much memory (counting by units U) to display. + +F, the display format + The display format is one of the formats used by `print', `s' + (null-terminated string), or `i' (machine instruction). The + default is `x' (hexadecimal) initially. The default changes each + time you use either `x' or `print'. + +U, the unit size + The unit size is any of + + `b' + Bytes. + + `h' + Halfwords (two bytes). + + `w' + Words (four bytes). This is the initial default. + + `g' + Giant words (eight bytes). + + Each time you specify a unit size with `x', that size becomes the + default unit the next time you use `x'. (For the `s' and `i' + formats, the unit size is ignored and is normally not written.) + +ADDR, starting display address + ADDR is the address where you want GDB to begin displaying memory. + The expression need not have a pointer value (though it may); it + is always interpreted as an integer address of a byte of memory. + *Note Expressions: Expressions, for more information on + expressions. The default for ADDR is usually just after the last + address examined--but several other commands also set the default + address: `info breakpoints' (to the address of the last breakpoint + listed), `info line' (to the starting address of a line), and + `print' (if you use it to display a value from memory). + + For example, `x/3uh 0x54320' is a request to display three halfwords +(`h') of memory, formatted as unsigned decimal integers (`u'), starting +at address `0x54320'. `x/4xw $sp' prints the four words (`w') of +memory above the stack pointer (here, `$sp'; *note Registers::.) in +hexadecimal (`x'). + + Since the letters indicating unit sizes are all distinct from the +letters specifying output formats, you do not have to remember whether +unit size or format comes first; either order works. The output +specifications `4xw' and `4wx' mean exactly the same thing. (However, +the count N must come first; `wx4' does not work.) + + Even though the unit size U is ignored for the formats `s' and `i', +you might still want to use a count N; for example, `3i' specifies that +you want to see three machine instructions, including any operands. +The command `disassemble' gives an alternative way of inspecting +machine instructions; *note Source and machine code: Machine Code.. + + All the defaults for the arguments to `x' are designed to make it +easy to continue scanning memory with minimal specifications each time +you use `x'. For example, after you have inspected three machine +instructions with `x/3i ADDR', you can inspect the next seven with just +`x/7'. If you use <RET> to repeat the `x' command, the repeat count N +is used again; the other arguments default as for successive uses of +`x'. + + The addresses and contents printed by the `x' command are not saved +in the value history because there is often too much of them and they +would get in the way. Instead, GDB makes these values available for +subsequent use in expressions as values of the convenience variables +`$_' and `$__'. After an `x' command, the last address examined is +available for use in expressions in the convenience variable `$_'. The +contents of that address, as examined, are available in the convenience +variable `$__'. + + If the `x' command has a repeat count, the address and contents saved +are from the last memory unit printed; this is not the same as the last +address printed if several units were printed on the last line of +output. + + +File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data + +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 on how elaborate your format +specification is--it uses `x' if you specify a unit size, or one of the +two formats (`i' and `s') that are only supported by `x'; otherwise it +uses `print'. + +`display EXP' + Add the expression EXP 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 EXP' + For FMT specifying only a display format and not a size or count, + add the expression EXP 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::.). + +`undisplay DNUMS...' +`delete display DNUMS...' + Remove item numbers DNUMS from the list of expressions to display. + + `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. + +`enable display DNUMS...' + Enable display of item numbers DNUMS. It becomes effective once + again in auto display of its expression, until you specify + otherwise. + +`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: Value History, Prev: Auto Display, Up: Data + +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. + + 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 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. + 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 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. + +`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. This + is the default setting. + +`set print union off' + Tell GDB not to print unions which are contained in structures. + +`show print union' + Ask GDB whether or not it will print unions which are contained in + structures. + + 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 = {...}} + +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. + +`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 vtbl' +`set print vtbl on' + Pretty print C++ virtual function tables. The default is off. + +`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: Value History, Next: Convenience Vars, Prev: Print Settings, Up: Data + +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 + +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::.). +(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 con'. + + 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. + + +File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data + +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 + registers (in the selected stack frame). + +`info all-registers' + Print the names and values of all registers, including + floating-point registers. + +`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'. + + 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. + + 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. + +`set rstack_high_address ADDRESS' + On AMD 29000 family processors, registers are saved in a separate + "register stack". There is no way for GDB to determine the extent + of this stack. Normally, GDB just assumes that the stack is "large + enough". This may result in GDB referencing memory locations that + do not exist. If necessary, you can get around this problem by + specifying the ending address of the register stack with the `set + rstack_high_address' command. The argument should be an address, + which you probably want to precede with `0x' to specify in + hexadecimal. + +`show rstack_high_address' + Display the current limit of the register stack, on AMD 29000 + family processors. + + ---------- 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'; *note +Returning from a function: Returning.. + + +File: gdb.info, Node: Floating Point Hardware, Prev: Registers, Up: Data + +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: Languages, Next: Symbols, Prev: Data, Up: Top + +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 + +* Support:: Supported languages + + +File: gdb.info, Node: Setting, Next: Show, Prev: Languages, Up: Languages + +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. + + 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, Prev: Setting, Up: Setting + +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. + +`.c' + C source file + +`.C' +`.cc' +`.cp' +`.cpp' +`.cxx' +`.c++' + C++ source file + +`.f' +`.F' + Fortran source file + +`.ch' +`.c186' +`.c286' + CHILL 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 + +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 + +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 + +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' + Set source files with extension .EXT to be assumed to be in the + source language LANGUAGE. + +`info extensions' + List all the filename extensions and the associated languages. + + +File: gdb.info, Node: Checks, Next: Support, Prev: Show, Up: Languages + +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: Support, 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, Prev: Checks, Up: Checks + +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: Support, 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: Support, 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 typechecking 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 + +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: Support, 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: Support, 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, + 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: Support, Prev: Checks, Up: Languages + +Supported languages +=================== + + GDB supports C, C++, Fortran, Chill, assembly, and Modula-2. 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++ +* Modula-2:: Modula-2 + + +File: gdb.info, Node: C, Next: Modula-2, Up: Support + +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'). + + For best results when using GNU C++, use the stabs debugging format. +You can select that format explicitly with the `g++' command-line +options `-gstabs' or `-gstabs+'. See *Note Options for Debugging Your +Program or GNU CC: (gcc.info)Debugging Options, for more information. + +* Menu: + +* C Operators:: C and C++ operators +* C Constants:: C and C++ constants +* Cplus 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++ + |