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 . 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 ...  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 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 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 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 *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 . 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 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 . 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++