| Red Hat Enterprise Linux 4: Debugging with gdb | ||
|---|---|---|
| Prev | Chapter 14. Using gdb with Different Languages | Next |
gdb supports C, C++, Objective-C, Fortran, Java, 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 (refer to Section 10.1 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.
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 DWARF 2 debugging format; if it doesn't work on your system, try the stabs+ debugging format. You can select those formats explicitly with the g++ command-line options -gdwarf-2 and -gstabs+. .
Operators must be defined on values of specific types. For instance, + is defined on numbers, but not on structures. Operators are often defined on groups of types.
For the purposes of C and C++, the following definitions hold:
Integral types include int with any of its storage-class specifiers; char; enum; and, for C++, bool.
Floating-point types include float, double, and long double (if supported by the target platform).
Pointer types include all types defined as (type *).
Scalar types include all of the above.
The following operators are supported. They are listed here in order of increasing precedence:
The comma or sequencing operator. Expressions in a comma-separated list are evaluated from left to right, with the result of the entire expression being the last expression evaluated.
Assignment. The value of an assignment expression is the value assigned. Defined on scalar types.
Used in an expression of the form a op= b, and translated to a = a op b. op= and = have the same precedence. op is any one of the operators |, ^, &, <<, >>, +, -, *, /, %.
The ternary operator. a ? b : c can be thought of as: if a then b else c. a should be of an integral type.
Logical or. Defined on integral types.
Logical and. Defined on integral types.
Bitwise or. Defined on integral types.
Bitwise exclusive-or. Defined on integral types.
Bitwise and. Defined on integral types.
Equality and inequality. Defined on scalar types. The value of these expressions is 0 for false and non-zero for true.
Less than, greater than, less than or equal, greater than or equal. Defined on scalar types. The value of these expressions is 0 for false and non-zero for true.
left shift, and right shift. Defined on integral types.
The gdb "artificial array" operator (refer to Section 10.1 Expressions).
Addition and subtraction. Defined on integral types, floating-point types and pointer types.
Multiplication, division, and modulus. Multiplication and division are defined on integral and floating-point types. Modulus is defined on integral types.
Increment and decrement. When appearing before a variable, the operation is performed before the variable is used in an expression; when appearing after it, the variable's value is used before the operation takes place.
Pointer dereferencing. Defined on pointer types. Same precedence as ++.
Address operator. Defined on variables. Same precedence as ++.
For debugging C++, gdb implements a use of & beyond what is allowed in the C++ language itself: you can use &(&ref) (or, if you prefer, simply &&ref) to examine the address where a C++ reference variable (declared with &ref) is stored.
Negative. Defined on integral and floating-point types. Same precedence as ++.
Logical negation. Defined on integral types. Same precedence as ++.
Bitwise complement operator. Defined on integral types. Same precedence as ++.
Structure member, and pointer-to-structure member. For convenience, gdb regards the two as equivalent, choosing whether to dereference a pointer based on the stored type information. Defined on struct and union data.
Dereferences of pointers to members.
Array indexing. a[i] is defined as *(a+i). Same precedence as ->.
Function parameter list. Same precedence as ->.
C++ scope resolution operator. Defined on struct, union, and class types.
Doubled colons also represent the gdb scope operator (refer to Section 10.1 Expressions). Same precedence as ::, above.
If an operator is redefined in the user code, gdb usually attempts to invoke the redefined version instead of using the operator's predefined meaning.
gdb allows you to express the constants of C and C++ in the following ways:
Integer constants are a sequence of digits. Octal constants are specified by a leading 0 (that is, zero), and hexadecimal constants by a leading 0x or 0X. Constants may also end with a letter l, specifying that the constant should be treated as a long value.
Floating point constants are a sequence of digits, followed by a decimal point, followed by a sequence of digits, and optionally followed by an exponent. An exponent is of the form: e[[+]|-]nnn, where nnn is another sequence of digits. The + is optional for positive exponents. A floating-point constant may also end with a letter f or F, specifying that the constant should be treated as being of the float (as opposed to the default double) type; or with a letter l or L, which specifies a long double constant.
Enumerated constants consist of enumerated identifiers, or their integral equivalents.
Character constants are a single character surrounded by single quotes ('), or a number--the ordinal value of the corresponding character (usually its ascii value). Within quotes, the single character may be represented by a letter or by escape sequences, which are of the form \nnn, where nnn is the octal representation of the character's ordinal value; or of the form \x, where x is a predefined special character--for example, \n for newline.
String constants are a sequence of character constants surrounded by double quotes ("). Any valid character constant (as described above) may appear. Double quotes within the string must be preceded by a backslash, so for instance "a\"b'c" is a string of five characters.
Pointer constants are an integral value. You can also write pointers to constants using the C operator &.
Array constants are comma-separated lists surrounded by braces { and }; for example, {1,2,3} is a three-element array of integers, {{1,2}, {3,4}, {5,6}} is a three-by-two array, and {&"hi", &"there", &"fred"} is a three-element array of pointers.
gdb expression handling can interpret most C++ expressions.
Warning: gdb can only debug C++ code if you use the proper compiler and the proper debug format. Currently, gdb works best when debugging C++ code that is compiled with gcc 2.95.3 or with gcc 3.1 or newer, using the options -gdwarf-2 or -gstabs+. DWARF 2 is preferred over stabs+. Most configurations of gcc emit either DWARF 2 or stabs+ as their default debug format, so you usually don't need to specify a debug format explicitly. Other compilers and/or debug formats are likely to work badly or not at all when using gdb to debug C++ code.
Member function calls are allowed; you can use expressions like
count = aml->GetOriginal(x, y) |
While a member function is active (in the selected stack frame), your expressions have the same namespace available as the member function; that is, gdb allows implicit references to the class instance pointer this following the same rules as C++.
You can call overloaded functions; gdb resolves the function call to the right definition, with some restrictions. gdb does not perform overload resolution involving user-defined type conversions, calls to constructors, or instantiations of templates that do not exist in the program. It also cannot handle ellipsis argument lists or default arguments.
It does perform integral conversions and promotions, floating-point promotions, arithmetic conversions, pointer conversions, conversions of class objects to base classes, and standard conversions such as those of functions or arrays to pointers; it requires an exact match on the number of function arguments.
Overload resolution is always performed, unless you have specified set overload-resolution off. Refer to Section 14.4.1.7 gdb features for C++.
You must specify set overload-resolution off in order to use an explicit function signature to call an overloaded function, as in
p 'foo(char,int)'('x', 13) |
The gdb command-completion facility can simplify this; (refer to Section 5.2 Command completion.
gdb understands variables declared as C++ references; you can use them in expressions just as you do in C++ source--they are automatically dereferenced.
In the parameter list shown when gdb displays a frame, the values of reference variables are not displayed (unlike other variables); this avoids clutter, since references are often used for large structures. The address of a reference variable is always shown, unless you have specified set print address off.
gdb supports the C++ name resolution operator ::--your expressions can use it just as expressions in your program do. Since one scope may be defined in another, you can use :: repeatedly if necessary, for example in an expression like scope1::scope2::name. gdb also allows resolving name scope by reference to source files, in both C and C++ debugging (refer to Section 10.2 Program variables).
In addition, when used with HP's C++ compiler, gdb supports calling virtual functions correctly, printing out virtual bases of objects, calling functions in a base subobject, casting objects, and invoking user-defined operators.
If you allow gdb to set type and range checking automatically, they both default to off whenever the working language changes to C or C++. This happens regardless of whether you or gdb selects the working language.
If you allow gdb to set the language automatically, it recognizes source files whose names end with .c, .C, or .cc, etc, and when gdb enters code compiled from one of these files, it sets the working language to C or C++. Refer to Section 14.1.3 Having gdb infer the source language, for further details.
By default, when gdb parses C or C++ expressions, type checking is not used. However, if you turn type checking on, gdb considers two variables type equivalent if:
The two variables are structured and have the same structure, union, or enumerated tag.
The two variables have the same type name, or types that have been declared equivalent through typedef.
Range checking, if turned on, is done on mathematical operations. Array indices are not checked, since they are often used to index a pointer that is not itself an array.
The set print union and show print union commands apply to the union type. When set to on, any union that is inside a struct or class is also printed. Otherwise, it appears as {...}.
The @ operator aids in the debugging of dynamic arrays, formed with pointers and a memory allocation function. Refer to Section 10.1 Expressions.
Some gdb commands are particularly useful with C++, and some are designed specifically for use with C++. Here is a summary:
When you want a breakpoint in a function whose name is overloaded, gdb breakpoint menus help you specify which function definition you want. Refer to Section 7.1.8 Breakpoint menus.
Setting breakpoints using regular expressions is helpful for setting breakpoints on overloaded functions that are not members of any special classes. Refer to Section 7.1.1 Setting breakpoints.
Debug C++ exception handling using these commands. Refer to Section 7.1.3 Setting catchpoints.
Print inheritance relationships as well as other information for type typename. Refer to Chapter 15 Examining the Symbol Table.
Control whether C++ symbols display in their source form, both when displaying code as C++ source and when displaying disassemblies. Refer to Section 10.7 Print settings.
Choose whether to print derived (actual) or declared types of objects. Refer to Section 10.7 Print settings.
Control the format for printing virtual function tables. Refer to Section 10.7 Print settings. (The vtbl commands do not work on programs compiled with the HP ANSI C++ compiler (aCC).)
Enable overload resolution for C++ expression evaluation. The default is on. For overloaded functions, gdb evaluates the arguments and searches for a function whose signature matches the argument types, using the standard C++ conversion rules ((refer to Section 14.4.1.3 C++expressions, for details). If it cannot find a match, it emits a message.
Disable overload resolution for C++ expression evaluation. For overloaded functions that are not class member functions, gdb chooses the first function of the specified name that it finds in the symbol table, whether or not its arguments are of the correct type. For overloaded functions that are class member functions, gdb searches for a function whose signature exactly matches the argument types.
You can specify a particular definition of an overloaded symbol, using the same notation that is used to declare such symbols in C++: type symbol(types) rather than just symbol. You can also use the gdb command-line word completion facilities to list the available choices, or to finish the type list for you. Refer to Section 5.2 Command completion, for details on how to do this.
This section provides information about some commands and command options that are useful for debugging Objective-C code.
The following commands have been extended to accept Objective-C method names as line specifications:
clear
break
info line
jump
list
A fully qualified Objective-C method name is specified as
-[Class methodName] |
where the minus sign is used to indicate an instance method and a plus sign (not shown) is used to indicate a class method. The class name Class and method name methoName are enclosed in brackets, similar to the way messages are specified in Objective-C source code. For example, to set a breakpoint at the create instance method of class Fruit in the program currently being debugged, enter:
break -[Fruit create] |
To list ten program lines around the initialize class method, enter:
list +[NSText initialize] |
In the current version of GDB, the plus or minus sign is required. In future versions of GDB, the plus or minus sign will be optional, but you can use it to narrow the search. It is also possible to specify just a method name:
break create |
You must specify the complete method name, including any colons. If your program's source files contain more than one create method, you'll be presented with a numbered list of classes that implement that method. Indicate your choice by number, or type 0 to exit if none apply.
As another example, to clear a breakpoint established at the makeKeyAndOrderFront: method of the NSWindow class, enter:
clear -[NSWindow makeKeyAndOrderFront:] |
The print command has also been extended to accept methods. For example:
print -[object hash] |
will tell gdb to send the -hash message to object and print the result. Also an additional command has been added, print-object or po for short, which is meant to print the description of an object. However, this command may only work with certain Objective-C libraries that have a particular hook function, called _NSPrintForDebugger defined.
The extensions made to gdb to support Modula-2 only support output from the gnu Modula-2 compiler (which is currently being developed). Other Modula-2 compilers are not currently supported, and attempting to debug executables produced by them is most likely to give an error as gdb reads in the executable's symbol table.
Operators must be defined on values of specific types. For instance, + is defined on numbers, but not on structures. Operators are often defined on groups of types. For the purposes of Modula-2, the following definitions hold:
Integral types consist of INTEGER, CARDINAL, and their subranges.
Character types consist of CHAR and its subranges.
Floating-point types consist of REAL.
Pointer types consist of anything declared as POINTER TO type.
Scalar types consist of all of the above.
Set types consist of SET and BITSET types.
Boolean types consist of BOOLEAN.
The following operators are supported, and appear in order of increasing precedence:
Function argument or array index separator.
Assignment. The value of var := value is value.
Less than, greater than on integral, floating-point, or enumerated types.
Less than or equal to, greater than or equal to on integral, floating-point and enumerated types, or set inclusion on set types. Same precedence as <.
Equality and two ways of expressing inequality, valid on scalar types. Same precedence as <. In gdb scripts, only <> is available for inequality, since # conflicts with the script comment character.
Set membership. Defined on set types and the types of their members. Same precedence as <.
Boolean disjunction. Defined on boolean types.
Boolean conjunction. Defined on boolean types.
The gdb "artificial array" operator (refer to Section 10.1 Expressions).
Addition and subtraction on integral and floating-point types, or union and difference on set types.
Multiplication on integral and floating-point types, or set intersection on set types.
Division on floating-point types, or symmetric set difference on set types. Same precedence as *.
Integer division and remainder. Defined on integral types. Same precedence as *.
Negative. Defined on INTEGER and REAL data.
Pointer dereferencing. Defined on pointer types.
Boolean negation. Defined on boolean types. Same precedence as ^.
RECORD field selector. Defined on RECORD data. Same precedence as ^.
Array indexing. Defined on ARRAY data. Same precedence as ^.
Procedure argument list. Defined on PROCEDURE objects. Same precedence as ^.
{No value for ` <listitem>GDBN'} and Modula-2 scope operators.
Warning: Sets and their operations are not yet supported, so gdb treats the use of the operator IN, or the use of operators +, -, *, /, =, , <>, #, <=, and >= on sets as an error.
Modula-2 also makes available several built-in procedures and functions. In describing these, the following metavariables are used:
represents an ARRAY variable.
represents a CHAR constant or variable.
represents a variable or constant of integral type.
represents an identifier that belongs to a set. Generally used in the same function with the metavariable s. The type of s should be SET OF mtype (where mtype is the type of m).
represents a variable or constant of integral or floating-point type.
represents a variable or constant of floating-point type.
represents a type.
represents a variable.
represents a variable or constant of one of many types. See the explanation of the function for details.
All Modula-2 built-in procedures also return a result, described below.
Returns the absolute value of n.
If c is a lower case letter, it returns its upper case equivalent, otherwise it returns its argument.
Returns the character whose ordinal value is i.
Decrements the value in the variable v by one. Returns the new value.
Decrements the value in the variable v by i. Returns the new value.
Removes the element m from the set s. Returns the new set.
Returns the floating point equivalent of the integer i.
Returns the index of the last member of a.
Increments the value in the variable v by one. Returns the new value.
Increments the value in the variable v by i. Returns the new value.
Adds the element m to the set s if it is not already there. Returns the new set.
Returns the maximum value of the type t.
Returns the minimum value of the type t.
Returns boolean TRUE if i is an odd number.
Returns the ordinal value of its argument. For example, the ordinal value of a character is its ascii value (on machines supporting the ascii character set). x must be of an ordered type, which include integral, character and enumerated types.
Returns the size of its argument. x can be a variable or a type.
Returns the integral part of r.
Returns the member of the type t whose ordinal value is i.
Warning: Sets and their operations are not yet supported, so gdb treats the use of procedures INCL and EXCL as an error.
gdb allows you to express the constants of Modula-2 in the following ways:
Integer constants are simply a sequence of digits. When used in an expression, a constant is interpreted to be type-compatible with the rest of the expression. Hexadecimal integers are specified by a trailing H, and octal integers by a trailing B.
Floating point constants appear as a sequence of digits, followed by a decimal point and another sequence of digits. An optional exponent can then be specified, in the form E[+|-]nnn, where [+|-]nnn is the desired exponent. All of the digits of the floating point constant must be valid decimal (base 10) digits.
Character constants consist of a single character enclosed by a pair of like quotes, either single (') or double ("). They may also be expressed by their ordinal value (their ascii value, usually) followed by a C.
String constants consist of a sequence of characters enclosed by a pair of like quotes, either single (') or double ("). Escape sequences in the style of C are also allowed. Refer to Section 14.4.1.2 C and C++constants, for a brief explanation of escape sequences.
Enumerated constants consist of an enumerated identifier.
Boolean constants consist of the identifiers TRUE and FALSE.
Pointer constants consist of integral values only.
Set constants are not yet supported.
If type and range checking are set automatically by gdb, they both default to on whenever the working language changes to Modula-2. This happens regardless of whether you or gdb selected the working language.
If you allow gdb to set the language automatically, then entering code compiled from a file whose name ends with .mod sets the working language to Modula-2. Refer to Section 14.1.3 Having gdb infer the source language, for further details.
A few changes have been made to make Modula-2 programs easier to debug. This is done primarily via loosening its type strictness:
Unlike in standard Modula-2, pointer constants can be formed by integers. This allows you to modify pointer variables during debugging. (In standard Modula-2, the actual address contained in a pointer variable is hidden from you; it can only be modified through direct assignment to another pointer variable or expression that returned a pointer.)
C escape sequences can be used in strings and characters to represent non-printable characters. gdb prints out strings with these escape sequences embedded. Single non-printable characters are printed using the CHR(nnn) format.
The assignment operator (:=) returns the value of its right-hand argument.
All built-in procedures both modify and return their argument.
Warning: in this release, gdb does not yet perform type or range checking.
gdb considers two Modula-2 variables type equivalent if:
They are of types that have been declared equivalent via a TYPE t1 = t2 statement
They have been declared on the same line. (Note: This is true of the gnu Modula-2 compiler, but it may not be true of other compilers.)
As long as type checking is enabled, any attempt to combine variables whose types are not equivalent is an error.
Range checking is done on all mathematical operations, assignment, array index bounds, and all built-in functions and procedures.
There are a few subtle differences between the Modula-2 scope operator (.) and the gdb scope operator (::). The two have similar syntax:
module . id scope :: id |
where scope is the name of a module or a procedure, module the name of a module, and id is any declared identifier within your program, except another module.
Using the :: operator makes gdb search the scope specified by scope for the identifier id. If it is not found in the specified scope, then gdb searches all scopes enclosing the one specified by scope.
Using the . operator makes gdb search the current scope for the identifier specified by id that was imported from the definition module specified by module. With this operator, it is an error if the identifier id was not imported from definition module module, or if id is not an identifier in module.
Some gdb commands have little use when debugging Modula-2 programs. Five subcommands of set print and show print apply specifically to C and C++: vtbl, demangle, asm-demangle, object, and union. The first four apply to C++, and the last to the C union type, which has no direct analogue in Modula-2.
The @ operator (refer to Section 10.1 Expressions), while available with any language, is not useful with Modula-2. Its intent is to aid the debugging of dynamic arrays, which cannot be created in Modula-2 as they can in C or C++. However, because an address can be specified by an integral constant, the construct {type}adrexp is still useful.
In gdb scripts, the Modula-2 inequality operator # is interpreted as the beginning of a comment. Use <> instead.