Debugging with GDB: Languages

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 15. Using GDB with Different Languages

Although programming languages generally have common aspects, they are rarely expressed in the same manner. For instance, in ANSI C, dereferencing a pointer `p` is accomplished by `*p`, but in Modula-2, it is accomplished by `p^`. Values can also be represented (and displayed) differently. Hex numbers in C appear as ``0x1ae'`, while in Modula-2 they appear as ``1AEH'`.

Language-specific information is built into GDB for some languages, allowing you to express operations like the above in your program's native language, and allowing GDB to output values in a manner consistent with the syntax of your program's native language. The language you use to build expressions is called the working language.

> 15.1 Switching Between Source Languages |  | Switching between source languages
> 15.2 Displaying the Language |  | Displaying the language
> 15.3 Type and Range Checking |  | Type and range checks
> 15.4 Supported Languages |  | Supported languages
> 15.5 Unsupported Languages |  | Unsupported languages

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.1 Switching Between Source Languages

There are two ways to control the working language--either have GDB set it automatically, or select it manually yourself. You can use the `set language` command for either purpose. On startup, GDB defaults to setting the language automatically. The working language is used to determine how expressions you type are interpreted, how values are printed, etc.

In addition to the working language, every source file that GDB knows about has its own working language. For some object file formats, the compiler might indicate which language a particular source file is in. However, most of the time GDB infers the language from the name of the file. The language of a source file controls whether C`++` names are demangled--this way `backtrace` can show each frame appropriately for its own language. There is no way to set the language of a source file from within GDB, but you can set the language associated with a filename extension. See section Displaying the Language.

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.

> 15.1.1 List of Filename Extensions and Languages |  | Filename extensions and languages.
> 15.1.2 Setting the Working Language |  | Setting the working language manually
> 15.1.3 Having GDB Infer the Source Language |  | Having GDB infer the source language

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.1.1 List of Filename Extensions and Languages

If a source file name ends in one of the following extensions, then GDB infers that its language is the one indicated.

``.ada'`
``.ads'`
``.adb'`
``.a'`
  Ada source file.

``.c'`
  C source file

``.C'`
``.cc'`
``.cp'`
``.cpp'`
``.cxx'`
``.c++'`
  C`++` source file

``.d'`
  D source file

``.m'`
  Objective-C source file

``.f'`
``.F'`
  Fortran source file

``.mod'`
  Modula-2 source file

``.s'`
``.S'`
  Assembler source file. This actually behaves almost like C, but GDB does not skip over function prologues when stepping.

In addition, you may set the language associated with a filename extension. See section Displaying the Language.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.1.2 Setting the Working Language

If you allow GDB to set the language automatically, expressions are interpreted the same way in your debugging session and your program.

If you wish, you may set the language manually. To do this, issue the command ``set language lang'`, where lang is the name of a language, such as `c` or `modula-2`. For a list of the supported languages, type ``set language'`.

Setting the language manually prevents GDB from updating the working language automatically. This can lead to confusion if you try to debug a program when the working language is not the same as the source language, when an expression is acceptable to both languages--but means different things. For instance, if the current source file were written in C, and GDB was parsing Modula-2, a command such as:

    print a = b + c

might not have the effect you intended. In C, this means to add `b` and `c` and place the result in `a`. The result printed would be the value of `a`. In Modula-2, this means to compare `a` to the result of `b+c`, yielding a `BOOLEAN` value.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.1.3 Having GDB Infer the Source Language

To have GDB set the working language automatically, use ``set language local'` or ``set language auto'`. GDB then infers the working language. That is, when your program stops in a frame (usually by encountering a breakpoint), GDB sets the working language to the language recorded for the function in that frame. If the language for a frame is unknown (that is, if the function or block corresponding to the frame was defined in a source file that does not have a recognized extension), the current working language is not changed, and GDB issues a warning.

This may not seem necessary for most programs, which are written entirely in one source language. However, program modules and libraries written in one source language can be used by a main program written in a different source language. Using ``set language auto'` in this case frees you from having to set the working language manually.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.2 Displaying the Language

The following commands help you find out which language is the working language, and also what language source files were written in.

`show language`
  Display the current working language. This is the language you can use with commands such as `print` to build and compute expressions that may involve variables in your program.

`info frame`
  Display the source language for this frame. This language becomes the working language if you use an identifier from this frame. See section Information about a Frame, to identify the other information listed here.

`info source`
  Display the source language of this source file. See section Examining the Symbol Table, to identify the other information listed here.

In unusual circumstances, you may have source files with extensions not in the standard list. You can then set the extension associated with a language explicitly:

`set extension-language ext language`
  Tell GDB that source files with extension ext are to be assumed as written in the source language language.

`info extensions`
  List all the filename extensions and the associated languages.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.3 Type and Range Checking

Some languages are designed to guard you against making seemingly common errors through a series of compile- and run-time checks. These include checking the type of arguments to functions and operators and making sure mathematical overflows are caught at run time. Checks such as these help to ensure a program's correctness once it has been compiled by eliminating type mismatches and providing active checks for range errors when your program is running.

By default GDB checks for these errors according to the rules of the current source language. Although GDB does not check the statements in your program, it can check expressions entered directly into GDB for evaluation via the `print` command, for example.

> 15.3.1 An Overview of Type Checking |  | An overview of type checking
> 15.3.2 An Overview of Range Checking |  | An overview of range checking

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.3.1 An Overview of Type Checking

Some languages, such as C and C`++`, are strongly typed, meaning that the arguments to operators and functions have to be of the correct type, otherwise an error occurs. These checks prevent type mismatch errors from ever causing any run-time problems. For example,

    int klass::my_method(char *b) { return  b ? 1 : 2; }

    (gdb) print obj.my_method (0)
    $1 = 2
    but
    (gdb) print obj.my_method (0x1234)
    Cannot resolve method klass::my_method to any overloaded instance

The second example fails because in C`++` the integer constant ``0x1234'` is not type-compatible with the pointer parameter type.

For the expressions you use in GDB commands, you can tell GDB to not enforce strict type checking or to treat any mismatches as errors and abandon the expression; When type checking is disabled, GDB successfully evaluates expressions like the second example above.

Even if type checking is off, there may be other reasons related to type that prevent GDB from evaluating an expression. For instance, GDB does not know how to add an `int` and a `struct foo`. These particular type errors have nothing to do with the language in use and usually arise from expressions which make little sense to evaluate anyway.

GDB provides some additional commands for controlling type checking:

`set check type on`
`set check type off`
  Set strict type checking on or off. If any type mismatches occur in evaluating an expression while type checking is on, GDB prints a message and aborts evaluation of the expression.

`show check type`
  Show the current setting of type checking and whether GDB is enforcing strict type checking rules.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.3.2 An Overview of Range Checking

In some languages (such as Modula-2), it is an error to exceed the bounds of a type; this is enforced with run-time checks. Such range checking is meant to ensure program correctness by making sure computations do not overflow, or indices on an array element access do not exceed the bounds of the array.

For expressions you use in GDB commands, you can tell GDB to treat range errors in one of three ways: ignore them, always treat them as errors and abandon the expression, or issue warnings but evaluate the expression anyway.

A range error can result from numerical overflow, from exceeding an array index bound, or when you type a constant that is not a member of any type. Some languages, however, do not treat overflows as an error. In many implementations of C, mathematical overflow causes the result to "wrap around" to lower values--for example, if m is the largest integer value, and s is the smallest, then

    m + 1 => s

This, too, is specific to individual languages, and in some cases specific to individual compilers or machines. See section Supported Languages, for further details on specific languages.

GDB provides some additional commands for controlling the range checker:

`set check range auto`
  Set range checking on or off based on the current working language. See section Supported Languages, for the default settings for each language.

`set check range on`
`set check range off`
  Set range checking on or off, overriding the default setting for the current working language. A warning is issued if the setting does not match the language default. If a range error occurs and range checking is on, then a message is printed and evaluation of the expression is aborted.

`set check range warn`
  Output messages when the GDB range checker detects a range error, but attempt to evaluate the expression anyway. Evaluating the expression may still be impossible for other reasons, such as accessing memory that the process does not own (a typical example from many Unix systems).

`show range`
  Show the current setting of the range checker, and whether or not it is being set automatically by GDB.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.4 Supported Languages

GDB supports C, C`++`, D, Go, Objective-C, Fortran, Java, OpenCL C, Pascal, assembly, Modula-2, and Ada. Some GDB features may be used in expressions regardless of the language you use: the GDB `@` and `::` operators, and the ``{type}addr'` construct (see section 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.

> 15.4.1 C and C`++` |  |
> 15.4.2 D |  |
> 15.4.3 Go |  |
> 15.4.4 Objective-C |  |
> 15.4.5 OpenCL C |  |
> 15.4.6 Fortran |  |
> 15.4.7 Pascal |  |
> 15.4.8 Modula-2 |  |
> 15.4.9 Ada |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.4.1 C and C`++`

Since C and C`++` are so closely related, many features of GDB apply to both languages. Whenever this is the case, we discuss those languages together.

The C`++` debugging facilities are jointly implemented by the C`++` compiler and GDB. Therefore, to debug your C`++` code effectively, you must compile your C`++` programs with a supported C`++` compiler, such as GNU `g++`, or the HP ANSI C`++` compiler (`aCC`).

> 15.4.1.1 C and C`++` Operators |  | C and C`++` operators
> 15.4.1.2 C and C`++` Constants |  | C and C`++` constants
> 15.4.1.3 C`++` Expressions |  | C`++` expressions
> 15.4.1.4 C and C`++` Defaults |  | Default settings for C and C`++`
> 15.4.1.5 C and C`++` Type and Range Checks |  | C and C`++` type and range checks
> 15.4.1.6 GDB and C |  |
> 15.4.1.7 GDB Features for C`++` |  | GDB features for C`++`
> 15.4.1.8 Decimal Floating Point format |  | Numbers in Decimal Floating Point format

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.1.1 C and C`++` Operators

Operators must be defined on values of specific types. For instance, `+` is defined on numbers, but not on structures. Operators are often defined on groups of types.

For the purposes of C and C`++`, the following definitions hold:

- Integral types include `int` with any of its storage-class specifiers; `char`; `enum`; and, for C`++`, `bool`.

- Floating-point types include `float`, `double`, and `long double` (if supported by the target platform).

- Pointer types include all types defined as `(type *)`.

- Scalar types include all of the above.

The following operators are supported. They are listed here in order of increasing precedence:

`,`
  The comma or sequencing operator. Expressions in a comma-separated list are evaluated from left to right, with the result of the entire expression being the last expression evaluated.

`=`
  Assignment. The value of an assignment expression is the value assigned. Defined on scalar types.

`op=`
  Used in an expression of the form `a op= b`, and translated to `a = a op b`. `op=` and `=` have the same precedence. op is any one of the operators `|`, `^`, `&`, `<<`, `>>`, `+`, `-`, `*`, `/`, `%`.

`?:`
  The ternary operator. `a ? b : c` can be thought of as: if a then b else c. a should be of an integral type.

`||`
  Logical OR. Defined on integral types.

`&&`
  Logical AND. Defined on integral types.

`|`
  Bitwise OR. Defined on integral types.

`^`
  Bitwise exclusive-OR. Defined on integral types.

`&`
  Bitwise AND. Defined on integral types.

`==, !=`
  Equality and inequality. Defined on scalar types. The value of these expressions is 0 for false and non-zero for true.

`<, >, <=, >=`
  Less than, greater than, less than or equal, greater than or equal. Defined on scalar types. The value of these expressions is 0 for false and non-zero for true.

`<<, >>`
  left shift, and right shift. Defined on integral types.

`@`
  The GDB "artificial array" operator (see section Expressions).

`+, -`
  Addition and subtraction. Defined on integral types, floating-point types and pointer types.

`*, /, %`
  Multiplication, division, and modulus. Multiplication and division are defined on integral and floating-point types. Modulus is defined on integral types.

`++, --`
  Increment and decrement. When appearing before a variable, the operation is performed before the variable is used in an expression; when appearing after it, the variable's value is used before the operation takes place.

`*`
  Pointer dereferencing. Defined on pointer types. Same precedence as `++`.

`&`
  Address operator. Defined on variables. Same precedence as `++`.

  For debugging C`++`, GDB implements a use of ``&'` beyond what is allowed in the C`++` language itself: you can use ``&(&ref)'` to examine the address where a C`++` reference variable (declared with ``&ref'`) is stored.

`-`
  Negative. Defined on integral and floating-point types. Same precedence as `++`.

`!`
  Logical negation. Defined on integral types. Same precedence as `++`.

`~`
  Bitwise complement operator. Defined on integral types. Same precedence as `++`.

`., ->`
  Structure member, and pointer-to-structure member. For convenience, GDB regards the two as equivalent, choosing whether to dereference a pointer based on the stored type information. Defined on `struct` and `union` data.

`.*, ->*`
  Dereferences of pointers to members.

`[]`
  Array indexing. `a[i]` is defined as `*(a+i)`. Same precedence as `->`.

`()`
  Function parameter list. Same precedence as `->`.

`::`
  C`++` scope resolution operator. Defined on `struct`, `union`, and `class` types.

`::`
  Doubled colons also represent the GDB scope operator (see section 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.1.2 C and C`++` Constants

GDB allows you to express the constants of C and C`++` in the following ways:

- Integer constants are a sequence of digits. Octal constants are specified by a leading ``0'` (i.e. zero), and hexadecimal constants by a leading ``0x'` or ``0X'`. Constants may also end with a letter ``l'`, specifying that the constant should be treated as a `long` value.

- Floating point constants are a sequence of digits, followed by a decimal point, followed by a sequence of digits, and optionally followed by an exponent. An exponent is of the form: ``e[[+]|-]nnn'`, where nnn is another sequence of digits. The ``+'` is optional for positive exponents. A floating-point constant may also end with a letter ``f'` or ``F'`, specifying that the constant should be treated as being of the `float` (as opposed to the default `double`) type; or with a letter ``l'` or ``L'`, which specifies a `long double` constant.

- Enumerated constants consist of enumerated identifiers, or their integral equivalents.

- Character constants are a single character surrounded by single quotes (`'`), or a number--the ordinal value of the corresponding character (usually its ASCII value). Within quotes, the single character may be represented by a letter or by escape sequences, which are of the form ``\nnn'`, where nnn is the octal representation of the character's ordinal value; or of the form ``\x'`, where ``x'` is a predefined special character--for example, ``\n'` for newline.

  Wide character constants can be written by prefixing a character constant with ``L'`, as in C. For example, ``L'x''` is the wide form of ``x'`. The target wide character set is used when computing the value of this constant (see section 10.20 Character Sets).

- String constants are a sequence of character constants surrounded by double quotes (`"`). Any valid character constant (as described above) may appear. Double quotes within the string must be preceded by a backslash, so for instance ``"a\"b'c"'` is a string of five characters.

  Wide string constants can be written by prefixing a string constant with ``L'`, as in C. The target wide character set is used when computing the value of this constant (see section 10.20 Character Sets).

- Pointer constants are an integral value. You can also write pointers to constants using the C operator ``&'`.

- Array constants are comma-separated lists surrounded by braces ``{'` and ``}'`; for example, ``{1,2,3}'` is a three-element array of integers, ``{{1,2}, {3,4}, {5,6}}'` is a three-by-two array, and ``{&"hi", &"there", &"fred"}'` is a three-element array of pointers.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.1.3 C`++` Expressions

GDB expression handling can interpret most C`++` expressions.

> Warning: GDB can only debug C`++` code if you use the proper compiler and the proper debug format. Currently, GDB works best when debugging C`++` code that is compiled with the most recent version of GCC possible. The DWARF debugging format is preferred; GCC defaults to this on most popular platforms. Other compilers and/or debug formats are likely to work badly or not at all when using GDB to debug C`++` code. See section 4.1 Compiling for Debugging.

1. Member function calls are allowed; you can use expressions like

       count = aml->GetOriginal(x, y)

2. While a member function is active (in the selected stack frame), your expressions have the same namespace available as the member function; that is, GDB allows implicit references to the class instance pointer `this` following the same rules as C`++`. `using` declarations in the current scope are also respected by GDB.

3. You can call overloaded functions; GDB resolves the function call to the right definition, with some restrictions. GDB does not perform overload resolution involving user-defined type conversions, calls to constructors, or instantiations of templates that do not exist in the program. It also cannot handle ellipsis argument lists or default arguments.

   It does perform integral conversions and promotions, floating-point promotions, arithmetic conversions, pointer conversions, conversions of class objects to base classes, and standard conversions such as those of functions or arrays to pointers; it requires an exact match on the number of function arguments.

   Overload resolution is always performed, unless you have specified `set overload-resolution off`. See section 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; see Command Completion.

4. GDB understands variables declared as C`++` references; you can use them in expressions just as you do in C`++` source--they are automatically dereferenced.

   In the parameter list shown when GDB displays a frame, the values of reference variables are not displayed (unlike other variables); this avoids clutter, since references are often used for large structures. The address of a reference variable is always shown, unless you have specified ``set print address off'`.

5. GDB supports the C`++` name resolution operator `::`---your expressions can use it just as expressions in your program do. Since one scope may be defined in another, you can use `::` repeatedly if necessary, for example in an expression like ``scope1::scope2::name'`. GDB also allows resolving name scope by reference to source files, in both C and C`++` debugging (see section Program Variables).

6. GDB performs argument-dependent lookup, following the C`++` specification.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.1.4 C and C`++` Defaults

If you allow GDB to set range checking automatically, it defaults to `off` whenever the working language changes to C or C`++`. This happens regardless of whether you or GDB selects the working language.

If you allow GDB to set the language automatically, it recognizes source files whose names end with ``.c'`, ``.C'`, or ``.cc'`, etc, and when GDB enters code compiled from one of these files, it sets the working language to C or C`++`. See section Having GDB Infer the Source Language, for further details.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.1.5 C and C`++` Type and Range Checks

By default, when GDB parses C or C`++` expressions, strict type checking is used. However, if you turn type checking off, GDB will allow certain non-standard conversions, such as promoting integer constants to pointers.

Range checking, if turned on, is done on mathematical operations. Array indices are not checked, since they are often used to index a pointer that is not itself an array.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.1.6 GDB and C

The `set print union` and `show print union` commands apply to the `union` type. When set to ``on'`, any `union` that is inside a `struct` or `class` is also printed. Otherwise, it appears as ``{...}'`.

The `@` operator aids in the debugging of dynamic arrays, formed with pointers and a memory allocation function. See section Expressions.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.1.7 GDB Features for C`++`

Some GDB commands are particularly useful with C`++`, and some are designed specifically for use with C`++`. Here is a summary:

`breakpoint menus`
  When you want a breakpoint in a function whose name is overloaded, GDB has the capability to display a menu of possible breakpoint locations to help you specify which function definition you want. See section Ambiguous Expressions.

`rbreak regex`
  Setting breakpoints using regular expressions is helpful for setting breakpoints on overloaded functions that are not members of any special classes. See section Setting Breakpoints.

`catch throw`
`catch rethrow`
`catch catch`
  Debug C`++` exception handling using these commands. See section Setting Catchpoints.

`ptype typename`
  Print inheritance relationships as well as other information for type typename. See section Examining the Symbol Table.

`info vtbl expression.`
  The `info vtbl` command can be used to display the virtual method tables of the object computed by expression. This shows one entry per virtual table; there may be multiple virtual tables when multiple inheritance is in use.

`set print demangle`
`show print demangle`
`set print asm-demangle`
`show print asm-demangle`
  Control whether C`++` symbols display in their source form, both when displaying code as C`++` source and when displaying disassemblies. See section Print Settings.

`set print object`
`show print object`
  Choose whether to print derived (actual) or declared types of objects. See section Print Settings.

`set print vtbl`
`show print vtbl`
  Control the format for printing virtual function tables. See section Print Settings. (The `vtbl` commands do not work on programs compiled with the HP ANSI C`++` compiler (`aCC`).)

`set overload-resolution on`
  Enable overload resolution for C`++` expression evaluation. The default is on. For overloaded functions, GDB evaluates the arguments and searches for a function whose signature matches the argument types, using the standard C`++` conversion rules (see C`++` Expressions, for details). If it cannot find a match, it emits a message.

`set overload-resolution off`
  Disable overload resolution for C`++` expression evaluation. For overloaded functions that are not class member functions, GDB chooses the first function of the specified name that it finds in the symbol table, whether or not its arguments are of the correct type. For overloaded functions that are class member functions, GDB searches for a function whose signature exactly matches the argument types.

`show overload-resolution`
  Show the current setting of overload resolution.

`Overloaded symbol names`
  You can specify a particular definition of an overloaded symbol, using the same notation that is used to declare such symbols in C`++`: type `symbol(types)` rather than just symbol. You can also use the GDB command-line word completion facilities to list the available choices, or to finish the type list for you. See section Command Completion, for details on how to do this.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.1.8 Decimal Floating Point format

GDB can examine, set and perform computations with numbers in decimal floating point format, which in the C language correspond to the `_Decimal32`, `_Decimal64` and `_Decimal128` types as specified by the extension to support decimal floating-point arithmetic.

There are two encodings in use, depending on the architecture: BID (Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for PowerPC and S/390. GDB will use the appropriate encoding for the configured target.

Because of a limitation in ``libdecnumber'`, the library used by GDB to manipulate decimal floating point numbers, it is not possible to convert (using a cast, for example) integers wider than 32-bit to decimal float.

In addition, in order to imitate GDB's behaviour with binary floating point computations, error checking in decimal float operations ignores underflow, overflow and divide by zero exceptions.

In the PowerPC architecture, GDB provides a set of pseudo-registers to inspect `_Decimal128` values stored in floating point registers. See PowerPC for more details.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.4.2 D

GDB can be used to debug programs written in D and compiled with GDC, LDC or DMD compilers. Currently GDB supports only one D specific feature -- dynamic arrays.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.4.3 Go

GDB can be used to debug programs written in Go and compiled with ``gccgo'` or ``6g'` compilers.

Here is a summary of the Go-specific features and restrictions:

`The current Go package`
  The name of the current package does not need to be specified when specifying global variables and functions.

  For example, given the program:

      package main
      var myglob = "Shall we?"
      func main () {
        // ...
      }

  When stopped inside `main` either of these work:

      (gdb) p myglob
      (gdb) p main.myglob

`Builtin Go types`
  The `string` type is recognized by GDB and is printed as a string.

`Builtin Go functions`
  The GDB expression parser recognizes the `unsafe.Sizeof` function and handles it internally.

`Restrictions on Go expressions`
  All Go operators are supported except `&^`. The Go `_` "blank identifier" is not supported. Automatic dereferencing of pointers is not supported.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.4.4 Objective-C

This section provides information about some commands and command options that are useful for debugging Objective-C code. See also info classes, and info selectors, for a few more commands specific to Objective-C support.

> 15.4.4.1 Method Names in Commands |  |
> 15.4.4.2 The Print Command With Objective-C |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.4.1 Method Names in Commands

The following commands have been extended to accept Objective-C method names as line specifications:

- `clear`
- `break`
- `info line`
- `jump`
- `list`

A fully qualified Objective-C method name is specified as

    -[Class methodName]

where the minus sign is used to indicate an instance method and a plus sign (not shown) is used to indicate a class method. The class name Class and method name methodName are enclosed in brackets, similar to the way messages are specified in Objective-C source code. For example, to set a breakpoint at the `create` instance method of class `Fruit` in the program currently being debugged, enter:

    break -[Fruit create]

To list ten program lines around the `initialize` class method, enter:

    list +[NSText initialize]

In the current version of GDB, the plus or minus sign is required. In future versions of GDB, the plus or minus sign will be optional, but you can use it to narrow the search. It is also possible to specify just a method name:

    break create

You must specify the complete method name, including any colons. If your program's source files contain more than one `create` method, you'll be presented with a numbered list of classes that implement that method. Indicate your choice by number, or type ``0'` to exit if none apply.

As another example, to clear a breakpoint established at the `makeKeyAndOrderFront:` method of the `NSWindow` class, enter:

    clear -[NSWindow makeKeyAndOrderFront:]

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.4.2 The Print Command With Objective-C

The print command has also been extended to accept methods. For example:

    print -[object hash]

will tell GDB to send the `hash` message to object and print the result. Also, an additional command has been added, `print-object` or `po` for short, which is meant to print the description of an object. However, this command may only work with certain Objective-C libraries that have a particular hook function, `_NSPrintForDebugger`, defined.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.4.5 OpenCL C

This section provides information about GDBs OpenCL C support.

> 15.4.5.1 OpenCL C Datatypes |  |
> 15.4.5.2 OpenCL C Expressions |  |
> 15.4.5.3 OpenCL C Operators |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.5.1 OpenCL C Datatypes

GDB supports the builtin scalar and vector datatypes specified by OpenCL 1.1. In addition the half- and double-precision floating point data types of the `cl_khr_fp16` and `cl_khr_fp64` OpenCL extensions are also known to GDB.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.5.2 OpenCL C Expressions

GDB supports accesses to vector components including the access as lvalue where possible. Since OpenCL C is based on C99 most C expressions supported by GDB can be used as well.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.5.3 OpenCL C Operators

GDB supports the operators specified by OpenCL 1.1 for scalar and vector data types.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.4.6 Fortran

GDB can be used to debug programs written in Fortran, but it currently supports only the features of Fortran 77 language.

Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers among them) append an underscore to the names of variables and functions. When you debug programs compiled by those compilers, you will need to refer to variables and functions with a trailing underscore.

> 15.4.6.1 Fortran Operators and Expressions |  | Fortran operators and expressions
> 15.4.6.2 Fortran Defaults |  | Default settings for Fortran
> 15.4.6.3 Special Fortran Commands |  | Special GDB commands for Fortran

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.6.1 Fortran Operators and Expressions

Operators must be defined on values of specific types. For instance, `+` is defined on numbers, but not on characters or other non- arithmetic types. Operators are often defined on groups of types.

`**`
  The exponentiation operator. It raises the first operand to the power of the second one.

`:`
  The range operator. Normally used in the form of array(low:high) to represent a section of array.

`%`
  The access component operator. Normally used to access elements in derived types. Also suitable for unions. As unions aren't part of regular Fortran, this can only happen when accessing a register that uses a gdbarch-defined union type.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.6.2 Fortran Defaults

Fortran symbols are usually case-insensitive, so GDB by default uses case-insensitive matches for Fortran symbols. You can change that with the ``set case-insensitive'` command, see 16. Examining the Symbol Table, for the details.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.6.3 Special Fortran Commands

GDB has some commands to support Fortran-specific features, such as displaying common blocks.

`info common [common-name]`
  This command prints the values contained in the Fortran `COMMON` block whose name is common-name. With no argument, the names of all `COMMON` blocks visible at the current program location are printed.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.4.7 Pascal

Debugging Pascal programs which use sets, subranges, file variables, or nested functions does not currently work. GDB does not support entering expressions, printing values, or similar features using Pascal syntax.

The Pascal-specific command `set print pascal_static-members` controls whether static members of Pascal objects are displayed. See section pascal_static-members.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.4.8 Modula-2

The extensions made to GDB to support Modula-2 only support output from the GNU Modula-2 compiler (which is currently being developed). Other Modula-2 compilers are not currently supported, and attempting to debug executables produced by them is most likely to give an error as GDB reads in the executable's symbol table.

> 15.4.8.1 Operators |  | Built-in operators
> 15.4.8.2 Built-in Functions and Procedures |  | Built-in functions and procedures
> 15.4.8.3 Constants |  | Modula-2 constants
> 15.4.8.4 Modula-2 Types |  | Modula-2 types
> 15.4.8.5 Modula-2 Defaults |  | Default settings for Modula-2
> 15.4.8.6 Deviations from Standard Modula-2 |  | Deviations from standard Modula-2
> 15.4.8.7 Modula-2 Type and Range Checks |  | Modula-2 type and range checks
> 15.4.8.8 The Scope Operators `::` and `.` |  | The scope operators `::` and `.`
> 15.4.8.9 GDB and Modula-2 |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.8.1 Operators

Operators must be defined on values of specific types. For instance, `+` is defined on numbers, but not on structures. Operators are often defined on groups of types. For the purposes of Modula-2, the following definitions hold:

- Integral types consist of `INTEGER`, `CARDINAL`, and their subranges.

- Character types consist of `CHAR` and its subranges.

- Floating-point types consist of `REAL`.

- Pointer types consist of anything declared as `POINTER TO type`.

- Scalar types consist of all of the above.

- Set types consist of `SET` and `BITSET` types.

- Boolean types consist of `BOOLEAN`.

The following operators are supported, and appear in order of increasing precedence:

`,`
  Function argument or array index separator.

`:=`
  Assignment. The value of var `:=` value is value.

`<, >`
  Less than, greater than on integral, floating-point, or enumerated types.

`<=, >=`
  Less than or equal to, greater than or equal to on integral, floating-point and enumerated types, or set inclusion on set types. Same precedence as `<`.

`=, <>, #`
  Equality and two ways of expressing inequality, valid on scalar types. Same precedence as `<`. In GDB scripts, only `<>` is available for inequality, since `#` conflicts with the script comment character.

`IN`
  Set membership. Defined on set types and the types of their members. Same precedence as `<`.

`OR`
  Boolean disjunction. Defined on boolean types.

`AND, &`
  Boolean conjunction. Defined on boolean types.

`@`
  The GDB "artificial array" operator (see section Expressions).

`+, -`
  Addition and subtraction on integral and floating-point types, or union and difference on set types.

`*`
  Multiplication on integral and floating-point types, or set intersection on set types.

`/`
  Division on floating-point types, or symmetric set difference on set types. Same precedence as `*`.

`DIV, MOD`
  Integer division and remainder. Defined on integral types. Same precedence as `*`.

`-`
  Negative. Defined on `INTEGER` and `REAL` data.

`^`
  Pointer dereferencing. Defined on pointer types.

`NOT`
  Boolean negation. Defined on boolean types. Same precedence as `^`.

`.`
  `RECORD` field selector. Defined on `RECORD` data. Same precedence as `^`.

`[]`
  Array indexing. Defined on `ARRAY` data. Same precedence as `^`.

`()`
  Procedure argument list. Defined on `PROCEDURE` objects. Same precedence as `^`.

`::, .`
  GDB and Modula-2 scope operators.

> Warning: Set expressions and their operations are not yet supported, so GDB treats the use of the operator `IN`, or the use of operators `+`, `-`, `*`, `/`, `=`, , `<>`, `#`, `<=`, and `>=` on sets as an error.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.8.2 Built-in Functions and Procedures

Modula-2 also makes available several built-in procedures and functions. In describing these, the following metavariables are used:

a
  represents an `ARRAY` variable.

c
  represents a `CHAR` constant or variable.

i
  represents a variable or constant of integral type.

m
  represents an identifier that belongs to a set. Generally used in the same function with the metavariable s. The type of s should be `SET OF mtype` (where mtype is the type of m).

n
  represents a variable or constant of integral or floating-point type.

r
  represents a variable or constant of floating-point type.

t
  represents a type.

v
  represents a variable.

x
  represents a variable or constant of one of many types. See the explanation of the function for details.

All Modula-2 built-in procedures also return a result, described below.

`ABS(n)`
  Returns the absolute value of n.

`CAP(c)`
  If c is a lower case letter, it returns its upper case equivalent, otherwise it returns its argument.

`CHR(i)`
  Returns the character whose ordinal value is i.

`DEC(v)`
  Decrements the value in the variable v by one. Returns the new value.

`DEC(v,i)`
  Decrements the value in the variable v by i. Returns the new value.

`EXCL(m,s)`
  Removes the element m from the set s. Returns the new set.

`FLOAT(i)`
  Returns the floating point equivalent of the integer i.

`HIGH(a)`
  Returns the index of the last member of a.

`INC(v)`
  Increments the value in the variable v by one. Returns the new value.

`INC(v,i)`
  Increments the value in the variable v by i. Returns the new value.

`INCL(m,s)`
  Adds the element m to the set s if it is not already there. Returns the new set.

`MAX(t)`
  Returns the maximum value of the type t.

`MIN(t)`
  Returns the minimum value of the type t.

`ODD(i)`
  Returns boolean TRUE if i is an odd number.

`ORD(x)`
  Returns the ordinal value of its argument. For example, the ordinal value of a character is its ASCII value (on machines supporting the ASCII character set). x must be of an ordered type, which include integral, character and enumerated types.

`SIZE(x)`
  Returns the size of its argument. x can be a variable or a type.

`TRUNC(r)`
  Returns the integral part of r.

`TSIZE(x)`
  Returns the size of its argument. x can be a variable or a type.

`VAL(t,i)`
  Returns the member of the type t whose ordinal value is i.

> Warning: Sets and their operations are not yet supported, so GDB treats the use of procedures `INCL` and `EXCL` as an error.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.8.3 Constants

GDB allows you to express the constants of Modula-2 in the following ways:

- Integer constants are simply a sequence of digits. When used in an expression, a constant is interpreted to be type-compatible with the rest of the expression. Hexadecimal integers are specified by a trailing ``H'`, and octal integers by a trailing ``B'`.

- Floating point constants appear as a sequence of digits, followed by a decimal point and another sequence of digits. An optional exponent can then be specified, in the form ``E[+|-]nnn'`, where ``[+|-]nnn'` is the desired exponent. All of the digits of the floating point constant must be valid decimal (base 10) digits.

- Character constants consist of a single character enclosed by a pair of like quotes, either single (`'`) or double (`"`). They may also be expressed by their ordinal value (their ASCII value, usually) followed by a ``C'`.

- String constants consist of a sequence of characters enclosed by a pair of like quotes, either single (`'`) or double (`"`). Escape sequences in the style of C are also allowed. See section 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.8.4 Modula-2 Types

Currently GDB can print the following data types in Modula-2 syntax: array types, record types, set types, pointer types, procedure types, enumerated types, subrange types and base types. You can also print the contents of variables declared using these type. This section gives a number of simple source code examples together with sample GDB sessions.

The first example contains the following section of code:

    VAR
       s: SET OF CHAR ;
       r: [20..40] ;

and you can request GDB to interrogate the type and value of `r` and `s`.

    (gdb) print s
    {'A'..'C', 'Z'}
    (gdb) ptype s
    SET OF CHAR
    (gdb) print r
    21
    (gdb) ptype r
    [20..40]

Likewise if your source code declares `s` as:

    VAR
       s: SET ['A'..'Z'] ;

then you may query the type of `s` by:

    (gdb) ptype s
    type = SET ['A'..'Z']

Note that at present you cannot interactively manipulate set expressions using the debugger.

The following example shows how you might declare an array in Modula-2 and how you can interact with GDB to print its type and contents:

    VAR
       s: ARRAY [-10..10] OF CHAR ;

    (gdb) ptype s
    ARRAY [-10..10] OF CHAR

Note that the array handling is not yet complete and although the type is printed correctly, expression handling still assumes that all arrays have a lower bound of zero and not `-10` as in the example above.

Here are some more type related Modula-2 examples:

    TYPE
       colour = (blue, red, yellow, green) ;
       t = [blue..yellow] ;
    VAR
       s: t ;
    BEGIN
       s := blue ;

The GDB interaction shows how you can query the data type and value of a variable.

    (gdb) print s
    $1 = blue
    (gdb) ptype t
    type = [blue..yellow]

In this example a Modula-2 array is declared and its contents displayed. Observe that the contents are written in the same way as their `C` counterparts.

    VAR
       s: ARRAY [1..5] OF CARDINAL ;
    BEGIN
       s[1] := 1 ;

    (gdb) print s
    $1 = {1, 0, 0, 0, 0}
    (gdb) ptype s
    type = ARRAY [1..5] OF CARDINAL

The Modula-2 language interface to GDB also understands pointer types as shown in this example:

    VAR
       s: POINTER TO ARRAY [1..5] OF CARDINAL ;
    BEGIN
       NEW(s) ;
       s^[1] := 1 ;

and you can request that GDB describes the type of `s`.

    (gdb) ptype s
    type = POINTER TO ARRAY [1..5] OF CARDINAL

GDB handles compound types as we can see in this example. Here we combine array types, record types, pointer types and subrange types:

    TYPE
       foo = RECORD
                f1: CARDINAL ;
                f2: CHAR ;
                f3: myarray ;
             END ;

       myarray = ARRAY myrange OF CARDINAL ;
       myrange = [-2..2] ;
    VAR
       s: POINTER TO ARRAY myrange OF foo ;

and you can ask GDB to describe the type of `s` as shown below.

    (gdb) ptype s
    type = POINTER TO ARRAY [-2..2] OF foo = RECORD
        f1 : CARDINAL;
        f2 : CHAR;
        f3 : ARRAY [-2..2] OF CARDINAL;
    END

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.8.5 Modula-2 Defaults

If type and range checking are set automatically by GDB, they both default to `on` whenever the working language changes to Modula-2. This happens regardless of whether you or GDB selected the working language.

If you allow GDB to set the language automatically, then entering code compiled from a file whose name ends with ``.mod'` sets the working language to Modula-2. See section Having GDB Infer the Source Language, for further details.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.8.6 Deviations from Standard Modula-2

A few changes have been made to make Modula-2 programs easier to debug. This is done primarily via loosening its type strictness:

- Unlike in standard Modula-2, pointer constants can be formed by integers. This allows you to modify pointer variables during debugging. (In standard Modula-2, the actual address contained in a pointer variable is hidden from you; it can only be modified through direct assignment to another pointer variable or expression that returned a pointer.)

- C escape sequences can be used in strings and characters to represent non-printable characters. GDB prints out strings with these escape sequences embedded. Single non-printable characters are printed using the ``CHR(nnn)'` format.

- The assignment operator (`:=`) returns the value of its right-hand argument.

- All built-in procedures both modify and return their argument.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.8.7 Modula-2 Type and Range Checks

> Warning: in this release, GDB does not yet perform type or range checking.

GDB considers two Modula-2 variables type equivalent if:

- They are of types that have been declared equivalent via a `TYPE t1 = t2` statement

- They have been declared on the same line. (Note: This is true of the GNU Modula-2 compiler, but it may not be true of other compilers.)

As long as type checking is enabled, any attempt to combine variables whose types are not equivalent is an error.

Range checking is done on all mathematical operations, assignment, array index bounds, and all built-in functions and procedures.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.8.8 The Scope Operators `::` and `.`

There are a few subtle differences between the Modula-2 scope operator (`.`) and the GDB scope operator (`::`). The two have similar syntax:

    module . id
    scope :: id

where scope is the name of a module or a procedure, module the name of a module, and id is any declared identifier within your program, except another module.

Using the `::` operator makes GDB search the scope specified by scope for the identifier id. If it is not found in the specified scope, then GDB searches all scopes enclosing the one specified by scope.

Using the `.` operator makes GDB search the current scope for the identifier specified by id that was imported from the definition module specified by module. With this operator, it is an error if the identifier id was not imported from definition module module, or if id is not an identifier in module.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.8.9 GDB and Modula-2

Some GDB commands have little use when debugging Modula-2 programs. Five subcommands of `set print` and `show print` apply specifically to C and C`++`: ``vtbl'`, ``demangle'`, ``asm-demangle'`, ``object'`, and ``union'`. The first four apply to C`++`, and the last to the C `union` type, which has no direct analogue in Modula-2.

The `@` operator (see section 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.4.9 Ada

The extensions made to GDB for Ada only support output from the GNU Ada (GNAT) compiler. Other Ada compilers are not currently supported, and attempting to debug executables produced by them is most likely to be difficult.

> 15.4.9.1 Introduction |  | General remarks on the Ada syntax and semantics supported by Ada mode in GDB.
> 15.4.9.2 Omissions from Ada |  | Restrictions on the Ada expression syntax.
> 15.4.9.3 Additions to Ada |  | Extensions of the Ada expression syntax.
> 15.4.9.4 Stopping at the Very Beginning |  | Debugging the program during elaboration.
> 15.4.9.5 Ada Exceptions |  |
> 15.4.9.6 Extensions for Ada Tasks |  | Listing and setting breakpoints in tasks.
> 15.4.9.7 Tasking Support when Debugging Core Files |  |
> 15.4.9.8 Tasking Support when using the Ravenscar Profile |  |
> 15.4.9.9 Debugging Generic Units |  | Dealing with generic instantiations.
> 15.4.9.10 Set commands for Ada |  | New settable GDB parameters for Ada.
> 15.4.9.11 Known Peculiarities of Ada Mode |  | Known peculiarities of Ada mode.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.1 Introduction

The Ada mode of GDB supports a fairly large subset of Ada expression syntax, with some extensions. The philosophy behind the design of this subset is

- That GDB should provide basic literals and access to operations for arithmetic, dereferencing, field selection, indexing, and subprogram calls, leaving more sophisticated computations to subprograms written into the program (which therefore may be called from GDB).

- That type safety and strict adherence to Ada language restrictions are not particularly important to the GDB user.

- That brevity is important to the GDB user.

Thus, for brevity, the debugger acts as if all names declared in user-written packages are directly visible, even if they are not visible according to Ada rules, thus making it unnecessary to fully qualify most names with their packages, regardless of context. Where this causes ambiguity, GDB asks the user's intent.

The debugger will start in Ada mode if it detects an Ada main program. As for other languages, it will enter Ada mode when stopped in a program that was translated from an Ada source file.

While in Ada mode, you may use ``--`' for comments. This is useful mostly for documenting command files. The standard GDB comment (``#'`) still works at the beginning of a line in Ada mode, but not in the middle (to allow based literals).

The debugger supports limited overloading. Given a subprogram call in which the function symbol has multiple definitions, it will use the number of actual parameters and some information about their types to attempt to narrow the set of definitions. It also makes very limited use of context, preferring procedures to functions in the context of the `call` command, and functions to procedures elsewhere.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.2 Omissions from Ada

Here are the notable omissions from the subset:

- Only a subset of the attributes are supported:

  - `'First`, `'Last`, and `'Length` on array objects (not on types and subtypes).

  - `'Min` and `'Max`.

  - `'Pos` and `'Val`.

  - `'Tag`.

  - `'Range` on array objects (not subtypes), but only as the right operand of the membership (`in`) operator.

  - `'Access`, `'Unchecked_Access`, and `'Unrestricted_Access` (a GNAT extension).

  - `'Address`.

- The names in `Characters.Latin_1` are not available and concatenation is not implemented. Thus, escape characters in strings are not currently available.

- Equality tests (``='` and ``/='`) on arrays test for bitwise equality of representations. They will generally work correctly for strings and arrays whose elements have integer or enumeration types. They may not work correctly for arrays whose element types have user-defined equality, for arrays of real values (in particular, IEEE-conformant floating point, because of negative zeroes and NaNs), and for arrays whose elements contain unused bits with indeterminate values.

- The other component-by-component array operations (`and`, `or`, `xor`, `not`, and relational tests other than equality) are not implemented.

- There is limited support for array and record aggregates. They are permitted only on the right sides of assignments, as in these examples:

      (gdb) set An_Array := (1, 2, 3, 4, 5, 6)
      (gdb) set An_Array := (1, others => 0)
      (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
      (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
      (gdb) set A_Record := (1, "Peter", True);
      (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True)

  Changing a discriminant's value by assigning an aggregate has an undefined effect if that discriminant is used within the record. However, you can first modify discriminants by directly assigning to them (which normally would not be allowed in Ada), and then performing an aggregate assignment. For example, given a variable `A_Rec` declared to have a type such as:

      type Rec (Len : Small_Integer := 0) is record
          Id : Integer;
          Vals : IntArray (1 .. Len);
      end record;

  you can assign a value with a different size of `Vals` with two assignments:

      (gdb) set A_Rec.Len := 4
      (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))

  As this example also illustrates, GDB is very loose about the usual rules concerning aggregates. You may leave out some of the components of an array or record aggregate (such as the `Len` component in the assignment to `A_Rec` above); they will retain their original values upon assignment. You may freely use dynamic values as indices in component associations. You may even use overlapping or redundant component associations, although which component values are assigned in such cases is not defined.

- Calls to dispatching subprograms are not implemented.

- The overloading algorithm is much more limited (i.e., less selective) than that of real Ada. It makes only limited use of the context in which a subexpression appears to resolve its meaning, and it is much looser in its rules for allowing type matches. As a result, some function calls will be ambiguous, and the user will be asked to choose the proper resolution.

- The `new` operator is not implemented.

- Entry calls are not implemented.

- Aside from printing, arithmetic operations on the native VAX floating-point formats are not supported.

- It is not possible to slice a packed array.

- The names `True` and `False`, when not part of a qualified name, are interpreted as if implicitly prefixed by `Standard`, regardless of context. Should your program redefine these names in a package or procedure (at best a dubious practice), you will have to use fully qualified names to access their new definitions.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.3 Additions to Ada

As it does for other languages, GDB makes certain generic extensions to Ada (see section 10.1 Expressions):

- If the expression E is a variable residing in memory (typically a local variable or array element) and N is a positive integer, then `E@N` displays the values of E and the N-1 adjacent variables following it in memory as an array. In Ada, this operator is generally not necessary, since its prime use is in displaying parts of an array, and slicing will usually do this in Ada. However, there are occasional uses when debugging programs in which certain debugging information has been optimized away.

- `B::var` means "the variable named var that appears in function or file B." When B is a file name, you must typically surround it in single quotes.

- The expression `{type} addr` means "the variable of type type that appears at address addr."

- A name starting with ``$'` is a convenience variable (see section 10.11 Convenience Variables) or a machine register (see section 10.13 Registers).

In addition, GDB provides a few other shortcuts and outright additions specific to Ada:

- The assignment statement is allowed as an expression, returning its right-hand operand as its value. Thus, you may enter

      (gdb) set x := y + 3
      (gdb) print A(tmp := y + 1)

- The semicolon is allowed as an "operator," returning as its value the value of its right-hand operand. This allows, for example, complex conditional breaks:

      (gdb) break f
      (gdb) condition 1 (report(i); k += 1; A(k) > 100)

- Rather than use catenation and symbolic character names to introduce special characters into strings, one may instead use a special bracket notation, which is also used to print strings. A sequence of characters of the form ``["XX"]'` within a string or character literal denotes the (single) character whose numeric encoding is XX in hexadecimal. The sequence of characters ``["""]'` also denotes a single quotation mark in strings. For example,

         "One line.["0a"]Next line.["0a"]"

  contains an ASCII newline character (`Ada.Characters.Latin_1.LF`) after each period.

- The subtype used as a prefix for the attributes `'Pos`, `'Min`, and `'Max` is optional (and is ignored in any case). For example, it is valid to write

      (gdb) print 'max(x, y)

- When printing arrays, GDB uses positional notation when the array has a lower bound of 1, and uses a modified named notation otherwise. For example, a one-dimensional array of three integers with a lower bound of 3 might print as

      (3 => 10, 17, 1)

  That is, in contrast to valid Ada, only the first component has a `=>` clause.

- You may abbreviate attributes in expressions with any unique, multi-character subsequence of their names (an exact match gets preference). For example, you may use `a'len`, `a'gth`, or `a'lh` in place of `a'length`.

- Since Ada is case-insensitive, the debugger normally maps identifiers you type to lower case. The GNAT compiler uses upper-case characters for some of its internal identifiers, which are normally of no interest to users. For the rare occasions when you actually have to look at them, enclose them in angle brackets to avoid the lower-case mapping. For example,

      (gdb) print <JMPBUF_SAVE>[0]

- Printing an object of class-wide type or dereferencing an access-to-class-wide value will display all the components of the object's specific type (as indicated by its run-time tag). Likewise, component selection on such a value will operate on the specific type of the object.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.4 Stopping at the Very Beginning

It is sometimes necessary to debug the program during elaboration, and before reaching the main procedure. As defined in the Ada Reference Manual, the elaboration code is invoked from a procedure called `adainit`. To run your program up to the beginning of elaboration, simply use the following two commands: `tbreak adainit` and `run`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.5 Ada Exceptions

A command is provided to list all Ada exceptions:

`info exceptions`
`info exceptions regexp`
  The `info exceptions` command allows you to list all Ada exceptions defined within the program being debugged, as well as their addresses. With a regular expression, regexp, as argument, only those exceptions whose names match regexp are listed.

Below is a small example, showing how the command can be used, first without argument, and next with a regular expression passed as an argument.

    (gdb) info exceptions
    All defined Ada exceptions:
    constraint_error: 0x613da0
    program_error: 0x613d20
    storage_error: 0x613ce0
    tasking_error: 0x613ca0
    const.aint_global_e: 0x613b00
    (gdb) info exceptions const.aint
    All Ada exceptions matching regular expression "const.aint":
    constraint_error: 0x613da0
    const.aint_global_e: 0x613b00

It is also possible to ask GDB to stop your program's execution when an exception is raised. For more details, see 5.1.3 Setting Catchpoints.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.6 Extensions for Ada Tasks

Support for Ada tasks is analogous to that for threads (see section 4.10 Debugging Programs with Multiple Threads). GDB provides the following task-related commands:

`info tasks`
  This command shows a list of current Ada tasks, as in the following example:

      (gdb) info tasks
        ID       TID P-ID Pri State                 Name
         1   8088000   0   15 Child Activation Wait main_task
         2   80a4000   1   15 Accept Statement      b
         3   809a800   1   15 Child Activation Wait a
      *  4   80ae800   3   15 Runnable              c

  In this listing, the asterisk before the last task indicates it to be the task currently being inspected.

  ID
    Represents GDB's internal task number.

  TID
    The Ada task ID.

  P-ID
    The parent's task ID (GDB's internal task number).

  Pri
    The base priority of the task.

  State
    Current state of the task.

    `Unactivated`
      The task has been created but has not been activated. It cannot be executing.

    `Runnable`
      The task is not blocked for any reason known to Ada. (It may be waiting for a mutex, though.) It is conceptually "executing" in normal mode.

    `Terminated`
      The task is terminated, in the sense of ARM 9.3 (5). Any dependents that were waiting on terminate alternatives have been awakened and have terminated themselves.

    `Child Activation Wait`
      The task is waiting for created tasks to complete activation.

    `Accept Statement`
      The task is waiting on an accept or selective wait statement.

    `Waiting on entry call`
      The task is waiting on an entry call.

    `Async Select Wait`
      The task is waiting to start the abortable part of an asynchronous select statement.

    `Delay Sleep`
      The task is waiting on a select statement with only a delay alternative open.

    `Child Termination Wait`
      The task is sleeping having completed a master within itself, and is waiting for the tasks dependent on that master to become terminated or waiting on a terminate Phase.

    `Wait Child in Term Alt`
      The task is sleeping waiting for tasks on terminate alternatives to finish terminating.

    `Accepting RV with taskno`
      The task is accepting a rendez-vous with the task taskno.

  Name
    Name of the task in the program.

`info task taskno`
  This command shows detailled informations on the specified task, as in the following example:

      (gdb) info tasks
        ID       TID P-ID Pri State                  Name
         1   8077880    0  15 Child Activation Wait  main_task
      *  2   807c468    1  15 Runnable               task_1
      (gdb) info task 2
      Ada Task: 0x807c468
      Name: task_1
      Thread: 0x807f378
      Parent: 1 (main_task)
      Base Priority: 15
      State: Runnable

`task`
  This command prints the ID of the current task.

      (gdb) info tasks
        ID       TID P-ID Pri State                  Name
         1   8077870    0  15 Child Activation Wait  main_task
      *  2   807c458    1  15 Runnable               t
      (gdb) task
      [Current task is 2]

`task taskno`
  This command is like the `thread threadno` command (see section 4.10 Debugging Programs with Multiple Threads). It switches the context of debugging from the current task to the given task.

      (gdb) info tasks
        ID       TID P-ID Pri State                  Name
         1   8077870    0  15 Child Activation Wait  main_task
      *  2   807c458    1  15 Runnable               t
      (gdb) task 1
      [Switching to task 1]
      #0  0x8067726 in pthread_cond_wait ()
      (gdb) bt
      #0  0x8067726 in pthread_cond_wait ()
      #1  0x8056714 in system.os_interface.pthread_cond_wait ()
      #2  0x805cb63 in system.task_primitives.operations.sleep ()
      #3  0x806153e in system.tasking.stages.activate_tasks ()
      #4  0x804aacc in un () at un.adb:5

`break linespec task taskno`
`break linespec task taskno if ...`
  These commands are like the `break ... thread ...` command (see section 5.5 Stopping and Starting Multi-thread Programs). linespec specifies source lines, as described in 9.2 Specifying a Location.

  Use the qualifier ``task taskno'` with a breakpoint command to specify that you only want GDB to stop the program when a particular Ada task reaches this breakpoint. taskno is one of the numeric task identifiers assigned by GDB, shown in the first column of the ``info tasks'` display.

  If you do not specify ``task taskno'` when you set a breakpoint, the breakpoint applies to all tasks of your program.

  You can use the `task` qualifier on conditional breakpoints as well; in this case, place ``task taskno'` before the breakpoint condition (before the `if`).

  For example,

      (gdb) info tasks
        ID       TID P-ID Pri State                 Name
         1 140022020   0   15 Child Activation Wait main_task
         2 140045060   1   15 Accept/Select Wait    t2
         3 140044840   1   15 Runnable              t1
      *  4 140056040   1   15 Runnable              t3
      (gdb) b 15 task 2
      Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
      (gdb) cont
      Continuing.
      task # 1 running
      task # 2 running

      Breakpoint 5, test_task_debug () at test_task_debug.adb:15
      15               flush;
      (gdb) info tasks
        ID       TID P-ID Pri State                 Name
         1 140022020   0   15 Child Activation Wait main_task
      *  2 140045060   1   15 Runnable              t2
         3 140044840   1   15 Runnable              t1
         4 140056040   1   15 Delay Sleep           t3

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.7 Tasking Support when Debugging Core Files

When inspecting a core file, as opposed to debugging a live program, tasking support may be limited or even unavailable, depending on the platform being used. For instance, on x86-linux, the list of tasks is available, but task switching is not supported. On Tru64, however, task switching will work as usual.

On certain platforms, including Tru64, the debugger needs to perform some memory writes in order to provide Ada tasking support. When inspecting a core file, this means that the core file must be opened with read-write privileges, using the command ``"set write on"'` (see section 17.6 Patching Programs). Under these circumstances, you should make a backup copy of the core file before inspecting it with GDB.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.8 Tasking Support when using the Ravenscar Profile

The Ravenscar Profile is a subset of the Ada tasking features, specifically designed for systems with safety-critical real-time requirements.

`set ravenscar task-switching on`
  Allows task switching when debugging a program that uses the Ravenscar Profile. This is the default.

`set ravenscar task-switching off`
  Turn off task switching when debugging a program that uses the Ravenscar Profile. This is mostly intended to disable the code that adds support for the Ravenscar Profile, in case a bug in either GDB or in the Ravenscar runtime is preventing GDB from working properly. To be effective, this command should be run before the program is started.

`show ravenscar task-switching`
  Show whether it is possible to switch from task to task in a program using the Ravenscar Profile.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.9 Debugging Generic Units

GNAT always uses code expansion for generic instantiation. This means that each time an instantiation occurs, a complete copy of the original code is made with appropriate substitutions.

It is not possible to refer to the original generic entities themselves in GDB (there is no code to refer to), but it is certainly possible to debug a particular instance of a generic, simply by using the appropriate expanded names. For example, suppose that `Gen` is a generic package:

    -- In file gen.ads:
    generic package Gen is
       function F (v1 : Integer) return Integer;
    end Gen;

    -- In file gen.adb:
    package body Gen is
       function F (v1 : Integer) return Integer is
       begin
          return v1+1;         -- Line 5
       end F;
    end Gen;

and we have the following expansions

    with Gen;
    procedure G is
       package Gen1 is new Gen;
       package Gen2 is new Gen;

       I : Integer := 0;
    begin
       I := Gen1.F (I);
       I := Gen2.F (I);
       I := Gen1.F (I);
       I := Gen2.F (I);
    end;

Then to break on a call to procedure `F` in the `Gen2` instance, simply use the command:

    (gdb) break G.Gen2.F

To break at a particular line in a particular generic instance, say the return statement in `G.Gen2`, append the line specification to the file and function name:

    (gdb) break gen.adb:G.Gen2.F:5

To break on this line line in all instances of `Gen`, use ``*'` as the function name:

    (gdb) break gen.adb:*:5

This will set individual breakpoints at all instances; they are independent of each other and you may remove, conditionalize, or otherwise modify them individually.

When a breakpoint occurs, you can step through the code of the generic instance in the normal manner. You can also examine values of data in the normal manner, providing the appropriate generic package qualification to refer to non-local entities.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.10 Set commands for Ada

Ada introduces new `set` commands.

`set varsize-limit size`
  Limit the size of the types of objects to size bytes when those sizes are computed from run-time quantities. When this limit is set to 0, there is no limit. By default, it is about 65K. The purpose of having such a limit is to prevent GDB from trying to grab enormous chunks of virtual memory when asked to evaluate a quantity whose bounds have been corrupted or have not yet been fully initialized. The limit applies to the results of some subexpressions as well as to complete expressions. For example, an expression denoting a simple integer component, such as `x.y.z`, may fail if the size of x.y is dynamic and exceeds size. On the other hand, GDB is sometimes clever; the expression `A(i)`, where A is an array variable with non-constant size, will generally succeed regardless of the bounds on A, as long as the component size is less than size.

`show varsize-limit`
  Show the limit on types whose size is determined by run-time quantities.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 15.4.9.11 Known Peculiarities of Ada Mode

Besides the omissions listed previously (see section 15.4.9.2 Omissions from Ada), we know of several problems with and limitations of Ada mode in GDB, some of which will be fixed with planned future releases of the debugger and the GNU Ada compiler.

- Static constants that the compiler chooses not to materialize as objects in storage are invisible to the debugger.

- Named parameter associations in function argument lists are ignored (the argument lists are treated as positional).

- Many useful library packages are currently invisible to the debugger.

- Fixed-point arithmetic, conversions, input, and output is carried out using floating-point arithmetic, and may give results that only approximate those on the host machine.

- When stopped in a particular subprogram, you can access variables defined in other, lexically enclosing subprograms by their simple names. At the moment, however, this may not always work; it depends on whether the compiler happens to have made the necessary information (the "static link") available at execution time, which it can sometimes avoid. Of course, even in those cases where the compiler does not provide the information, you can still look at such variables by issuing the appropriate number of `up` commands to get to frame containing the variable you wish to see. Access to non-local variables does not, at the moment, work in the test expressions for conditional breakpoints (see section Break conditions) unless you happen to specify these while stopped in the subprogram in which they are to be applied.

- The GNAT compiler never generates the prefix `Standard` for any of the standard symbols defined by the Ada language. GDB knows about this: it will strip the prefix from names when you use it, and will never look for a name you have so qualified among local symbols, nor match against symbols in other packages or subprograms. If you have defined entities anywhere in your program other than parameters and local variables whose simple names match names in `Standard`, GNAT's lack of qualification here can cause confusion. When this happens, you can usually resolve the confusion by qualifying the problematic names with package `Standard` explicitly.

Older versions of the compiler sometimes generate erroneous debugging information, resulting in the debugger incorrectly printing the value of affected entities. In some cases, the debugger is able to work around an issue automatically. In other cases, the debugger is able to work around the issue, but the work-around has to be specifically enabled.

`set ada trust-PAD-over-XVS on`
  Configure GDB to strictly follow the GNAT encoding when computing the value of Ada entities, particularly when `PAD` and `PAD___XVS` types are involved (see `ada/exp_dbug.ads` in the GCC sources for a complete description of the encoding used by the GNAT compiler). This is the default.

`set ada trust-PAD-over-XVS off`
  This is related to the encoding using by the GNAT compiler. If GDB sometimes prints the wrong value for certain entities, changing `ada trust-PAD-over-XVS` to `off` activates a work-around which may fix the issue. It is always safe to set `ada trust-PAD-over-XVS` to `off`, but this incurs a slight performance penalty, so it is recommended to leave this setting to `on` unless necessary.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.5 Unsupported Languages

In addition to the other fully-supported programming languages, GDB also provides a pseudo-language, called `minimal`. It does not represent a real programming language, but provides a set of capabilities close to what the C or assembly languages provide. This should allow most simple operations to be performed while debugging an application that uses a language currently not supported by GDB.

If the language is set to `auto`, GDB will automatically select this language if the current frame corresponds to an unsupported language.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html