diff options
Diffstat (limited to 'gnu/usr.bin/gdb/doc/gdb.info-4')
| -rw-r--r-- | gnu/usr.bin/gdb/doc/gdb.info-4 | 1349 |
1 files changed, 1349 insertions, 0 deletions
diff --git a/gnu/usr.bin/gdb/doc/gdb.info-4 b/gnu/usr.bin/gdb/doc/gdb.info-4 new file mode 100644 index 0000000..b0758fa --- /dev/null +++ b/gnu/usr.bin/gdb/doc/gdb.info-4 @@ -0,0 +1,1349 @@ +This is Info file ./gdb.info, produced by Makeinfo-1.52 from the input +file gdb.texinfo. + +START-INFO-DIR-ENTRY +* Gdb:: The GNU debugger. +END-INFO-DIR-ENTRY + This file documents the GNU debugger GDB. + + This is Edition 4.09, August 1993, of `Debugging with GDB: the GNU +Source-Level Debugger' for GDB Version 4.11. + + Copyright (C) 1988, '89, '90, '91, '92, '93 Free Software +Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the entire resulting derived work is distributed under the terms +of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions. + + +File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data + +Registers +========= + + You can refer to machine register contents, in expressions, as +variables with names starting with `$'. The names of registers are +different for each machine; use `info registers' to see the names used +on your machine. + +`info registers' + Print the names and values of all registers except floating-point + registers (in the selected stack frame). + +`info all-registers' + Print the names and values of all registers, including + floating-point registers. + +`info registers REGNAME ...' + Print the relativized value of each specified register REGNAME. + rEGNAME may be any register name valid on the machine you are + using, with or without the initial `$'. + + GDB has four "standard" register names that are available (in +expressions) on most machines--whenever they do not conflict with an +architecture's canonical mnemonics for registers. The register names +`$pc' and `$sp' are used for the program counter register and the stack +pointer. `$fp' is used for a register that contains a pointer to the +current stack frame, and `$ps' is used for a register that contains the +processor status. For example, you could print the program counter in +hex with + + p/x $pc + +or print the instruction to be executed next with + + x/i $pc + +or add four to the stack pointer(1) with + + set $sp += 4 + + Whenever possible, these four standard register names are available +on your machine even though the machine has different canonical +mnemonics, so long as there is no conflict. The `info registers' +command shows the canonical names. For example, on the SPARC, `info +registers' displays the processor status register as `$psr' but you can +also refer to it as `$ps'. + + GDB always considers the contents of an ordinary register as an +integer when the register is examined in this way. Some machines have +special registers which can hold nothing but floating point; these +registers are considered to have floating point values. There is no way +to refer to the contents of an ordinary register as floating point value +(although you can *print* it as a floating point value with `print/f +$REGNAME'). + + Some registers have distinct "raw" and "virtual" data formats. This +means that the data format in which the register contents are saved by +the operating system is not the same one that your program normally +sees. For example, the registers of the 68881 floating point +coprocessor are always saved in "extended" (raw) format, but all C +programs expect to work with "double" (virtual) format. In such cases, +GDB normally works with the virtual format only (the format that makes +sense for your program), but the `info registers' command prints the +data in both formats. + + Normally, register values are relative to the selected stack frame +(*note Selecting a frame: Selection.). This means that you get the +value that the register would contain if all stack frames farther in +were exited and their saved registers restored. In order to see the +true contents of hardware registers, you must select the innermost +frame (with `frame 0'). + + However, GDB must deduce where registers are saved, from the machine +code generated by your compiler. If some registers are not saved, or if +GDB is unable to locate the saved registers, the selected stack frame +will make no difference. + +`set rstack_high_address ADDRESS' + On AMD 29000 family processors, registers are saved in a separate + "register stack". There is no way for GDB to determine the extent + of this stack. Normally, GDB just assumes that the stack is "large + enough". This may result in GDB referencing memory locations that + do not exist. If necessary, you can get around this problem by + specifying the ending address of the register stack with the `set + rstack_high_address' command. The argument should be an address, + which you will probably want to precede with `0x' to specify in + hexadecimal. + +`show rstack_high_address' + Display the current limit of the register stack, on AMD 29000 + family processors. + + ---------- Footnotes ---------- + + (1) This is a way of removing one word from the stack, on machines +where stacks grow downward in memory (most machines, nowadays). This +assumes that the innermost stack frame is selected; setting `$sp' is +not allowed when other stack frames are selected. To pop entire frames +off the stack, regardless of machine architecture, use `return'; *note +Returning from a function: Returning.. + + +File: gdb.info, Node: Floating Point Hardware, Prev: Registers, Up: Data + +Floating point hardware +======================= + + Depending on the host machine architecture, GDB may be able to give +you more information about the status of the floating point hardware. + +`info float' + Display hardware-dependent information about the floating point + unit. The exact contents and layout vary depending on the + floating point chip; on some platforms, `info float' is not + available at all. + + +File: gdb.info, Node: Languages, Next: Symbols, Prev: Data, Up: Top + +Using GDB with Different Languages +********************************** + + Although programming languages generally have common aspects, they +are rarely expressed in the same manner. For instance, in ANSI C, +dereferencing a pointer `p' is accomplished by `*p', but in Modula-2, +it is accomplished by `p^'. Values can also be represented (and +displayed) differently. Hex numbers in C are written like `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, called the "working language", +can be selected manually, or GDB can set it automatically. + +* Menu: + +* Setting:: Switching between source languages +* Show:: Displaying the language + +* Checks:: Type and range checks + +* Support:: Supported languages + + +File: gdb.info, Node: Setting, Next: Show, Up: Languages + +Switching between source languages +================================== + + There are two ways to control the working language--either have GDB +set it automatically, or select it manually yourself. You can use the +`set language' command for either purpose. On startup, GDB defaults to +setting the language automatically. + +* Menu: + +* Manually:: Setting the working language manually +* Automatically:: Having GDB infer the source language + + +File: gdb.info, Node: Manually, Next: Automatically, Up: Setting + +Setting the working language +---------------------------- + + If you allow GDB to set the language automatically, expressions are +interpreted the same way in your debugging session and your program. + + If you wish, you may set the language manually. To do this, issue +the command `set language LANG', where LANG is the name of a language, +such as `c' or `modula-2'. For a list of the supported languages, type +`set language'. + + Setting the language manually prevents GDB from updating the working +language automatically. This can lead to confusion if you try to debug +a program when the working language is not the same as the source +language, when an expression is acceptable to both languages--but means +different things. For instance, if the current source file were +written in C, and GDB was parsing Modula-2, a command such as: + + print a = b + c + +might not have the effect you intended. In C, this means to add `b' +and `c' and place the result in `a'. The result printed would be the +value of `a'. In Modula-2, this means to compare `a' to the result of +`b+c', yielding a `BOOLEAN' value. + + +File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting + +Having GDB infer the source language +------------------------------------ + + To have GDB set the working language automatically, use `set +language local' or `set language auto'. GDB then infers the language +that a program was written in by looking at the name of its source +files, and examining their extensions: + +`*.mod' + Modula-2 source file + +`*.c' + C source file + +`*.C' +`*.cc' + C++ source file + + This information is recorded for each function or procedure in a +source file. When your program stops in a frame (usually by +encountering a breakpoint), GDB sets the working language to the +language recorded for the function in that frame. If the language for +a frame is unknown (that is, if the function or block corresponding to +the frame was defined in a source file that does not have a recognized +extension), the current working language is not changed, and GDB issues +a warning. + + This may not seem necessary for most programs, which are written +entirely in one source language. However, program modules and libraries +written in one source language can be used by a main program written in +a different source language. Using `set language auto' in this case +frees you from having to set the working language manually. + + +File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages + +Displaying the language +======================= + + The following commands will 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' + Among the other information listed here (*note Information about a + frame: Frame Info.) is the source language for this frame. This + is the language that will become the working language if you ever + use an identifier that is in this frame. + +`info source' + Among the other information listed here (*note Examining the + Symbol Table: Symbols.) is the source language of this source file. + + +File: gdb.info, Node: Checks, Next: Support, Prev: Show, Up: Languages + +Type and range checking +======================= + + *Warning:* In this release, the GDB commands for type and range + checking are included, but they do not yet have any effect. This + section documents the intended facilities. + + Some languages are designed to guard you against making seemingly +common errors through a series of compile- and run-time checks. These +include checking the type of arguments to functions and operators, and +making sure mathematical overflows are caught at run time. Checks such +as these help to ensure a program's correctness once it has been +compiled by eliminating type mismatches, and providing active checks +for range errors when your program is running. + + GDB can check for conditions like the above if you wish. Although +GDB will not check the statements in your program, it can check +expressions entered directly into GDB for evaluation via the `print' +command, for example. As with the working language, GDB can also +decide whether or not to check automatically based on your program's +source language. *Note Supported languages: Support, for the default +settings of supported languages. + +* Menu: + +* Type Checking:: An overview of type checking +* Range Checking:: An overview of range checking + + +File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks + +An overview of type checking +---------------------------- + + Some languages, such as Modula-2, are strongly typed, meaning that +the arguments to operators and functions have to be of the correct type, +otherwise an error occurs. These checks prevent type mismatch errors +from ever causing any run-time problems. For example, + + 1 + 2 => 3 +but + error--> 1 + 2.3 + + The second example fails because the `CARDINAL' 1 is not +type-compatible with the `REAL' 2.3. + + For expressions you use in GDB commands, you can tell the GDB type +checker to skip checking; to treat any mismatches as errors and abandon +the expression; or only issue warnings when type mismatches occur, but +evaluate the expression anyway. When you choose the last of these, GDB +evaluates expressions like the second example above, but also issues a +warning. + + Even though you may turn type checking off, other type-based reasons +may prevent GDB from evaluating an expression. For instance, GDB does +not know how to add an `int' and a `struct foo'. These particular type +errors have nothing to do with the language in use, and usually arise +from expressions, such as the one described above, which make little +sense to evaluate anyway. + + Each language defines to what degree it is strict about type. For +instance, both Modula-2 and C require the arguments to arithmetical +operators to be numbers. In C, enumerated types and pointers can be +represented as numbers, so that they are valid arguments to mathematical +operators. *Note Supported languages: Support, for further details on +specific languages. + + GDB provides some additional commands for controlling the type +checker: + +`set check type auto' + Set type checking on or off based on the current working language. + *Note Supported languages: Support, for the default settings for + each language. + +`set check type on' +`set check type off' + Set type checking on or off, overriding the default setting for the + current working language. Issue a warning if the setting does not + match the language default. If any type mismatches occur in + evaluating an expression while typechecking is on, GDB prints a + message and aborts evaluation of the expression. + +`set check type warn' + Cause the type checker to issue warnings, but to always attempt to + evaluate the expression. Evaluating the expression may still be + impossible for other reasons. For example, GDB cannot add numbers + and structures. + +`show type' + Show the current setting of the type checker, and whether or not + GDB is setting it automatically. + + +File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks + +An overview of range checking +----------------------------- + + In some languages (such as Modula-2), it is an error to exceed the +bounds of a type; this is enforced with run-time checks. Such range +checking is meant to ensure program correctness by making sure +computations do not overflow, or indices on an array element access do +not exceed the bounds of the array. + + For expressions you use in GDB commands, you can tell GDB to treat +range errors in one of three ways: ignore them, always treat them as +errors and abandon the expression, or issue warnings but evaluate the +expression anyway. + + A range error can result from numerical overflow, from exceeding an +array index bound, or when you type a constant that is not a member of +any type. Some languages, however, do not treat overflows as an error. +In many implementations of C, mathematical overflow causes the result +to "wrap around" to lower values--for example, if M is the largest +integer value, and S is the smallest, then + + M + 1 => S + + This, too, is specific to individual languages, and in some cases +specific to individual compilers or machines. *Note Supported +languages: Support, for further details on specific languages. + + GDB provides some additional commands for controlling the range +checker: + +`set check range auto' + Set range checking on or off based on the current working language. + *Note Supported languages: Support, for the default settings for + each language. + +`set check range on' +`set check range off' + Set range checking on or off, overriding the default setting for + the current working language. A warning is issued if the setting + does not match the language default. If a range error occurs, + then a message is printed and evaluation of the expression is + aborted. + +`set check range warn' + Output messages when the GDB range checker detects a range error, + but attempt to evaluate the expression anyway. Evaluating the + expression may still be impossible for other reasons, such as + accessing memory that the process does not own (a typical example + from many Unix systems). + +`show range' + Show the current setting of the range checker, and whether or not + it is being set automatically by GDB. + + +File: gdb.info, Node: Support, Prev: Checks, Up: Languages + +Supported languages +=================== + + GDB 4 supports C, C++, and Modula-2. Some GDB features may be used +in expressions regardless of the language you use: the GDB `@' and `::' +operators, and the `{type}addr' construct (*note Expressions: +Expressions.) can be used with the constructs of any supported language. + + The following sections detail to what degree each source language is +supported by GDB. These sections are not meant to be language +tutorials or references, but serve only as a reference guide to what the +GDB expression parser will accept, and what input and output formats +should look like for different languages. There are many good books +written on each of these languages; please look to these for a language +reference or tutorial. + +* Menu: + +* C:: C and C++ +* Modula-2:: Modula-2 + + +File: gdb.info, Node: C, Next: Modula-2, Up: Support + +C and C++ +--------- + + Since C and C++ are so closely related, many features of GDB apply +to both languages. Whenever this is the case, we discuss both languages +together. + + The C++ debugging facilities are jointly implemented by the GNU C++ +compiler and GDB. Therefore, to debug your C++ code effectively, you +must compile your C++ programs with the GNU C++ compiler, `g++'. + +* Menu: + +* C Operators:: C and C++ operators +* C Constants:: C and C++ constants +* Cplus expressions:: C++ expressions +* C Defaults:: Default settings for C and C++ + +* C Checks:: C and C++ type and range checks + +* Debugging C:: GDB and C +* Debugging C plus plus:: Special features for C++ + + +File: gdb.info, Node: C Operators, Next: C Constants, Up: C + +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'; and `enum'. + + * *Floating-point types* include `float' and `double'. + + * *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 precendence. OP is any + one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*', + `/', `%'. + +`?:' + The ternary operator. `A ? B : C' can be thought of as: if A + then B else C. A should be of an integral type. + +`||' + Logical OR. Defined on integral types. + +`&&' + Logical AND. Defined on integral types. + +`|' + Bitwise OR. Defined on integral types. + +`^' + Bitwise exclusive-OR. Defined on integral types. + +`&' + Bitwise AND. Defined on integral types. + +`==, !=' + Equality and inequality. Defined on scalar types. The value of + these expressions is 0 for false and non-zero for true. + +`<, >, <=, >=' + Less than, greater than, less than or equal, greater than or equal. + Defined on scalar types. The value of these expressions is 0 for + false and non-zero for true. + +`<<, >>' + left shift, and right shift. Defined on integral types. + +`@' + The GDB "artificial array" operator (*note Expressions: + Expressions.). + +`+, -' + Addition and subtraction. Defined on integral types, + floating-point types and pointer types. + +`*, /, %' + Multiplication, division, and modulus. Multiplication and + division are defined on integral and floating-point types. + Modulus is defined on integral types. + +`++, --' + Increment and decrement. When appearing before a variable, the + operation is performed before the variable is used in an + expression; when appearing after it, the variable's value is used + before the operation takes place. + +`*' + Pointer dereferencing. Defined on pointer types. Same precedence + as `++'. + +`&' + Address operator. Defined on variables. Same precedence as `++'. + + For debugging C++, GDB implements a use of `&' beyond what is + allowed in the C++ language itself: you can use `&(&REF)' (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. + +`[]' + Array indexing. `A[I]' is defined as `*(A+I)'. Same precedence + as `->'. + +`()' + Function parameter list. Same precedence as `->'. + +`::' + C++ scope resolution operator. Defined on `struct', `union', and + `class' types. + +`::' + Doubled colons also represent the GDB scope operator (*note + Expressions: Expressions.). Same precedence as `::', above. + + +File: gdb.info, Node: C Constants, Next: Cplus expressions, Prev: C Operators, Up: C + +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' (ie. 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. + + * 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 (`"'). + + * Pointer constants are an integral value. You can also write + pointers to constants using the C operator `&'. + + * Array constants are comma-separated lists surrounded by braces `{' + and `}'; for example, `{1,2,3}' is a three-element array of + integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and + `{&"hi", &"there", &"fred"}' is a three-element array of pointers. + + +File: gdb.info, Node: Cplus expressions, Next: C Defaults, Prev: C Constants, Up: C + +C++ expressions +--------------- + + GDB expression handling has a number of extensions to interpret a +significant subset of C++ expressions. + + *Warning:* Most of these extensions depend on the use of additional + debugging information in the symbol table, and thus require a rich, + extendable object code format. In particular, if your system uses + a.out, MIPS ECOFF, RS/6000 XCOFF, or Sun ELF with stabs extensions + to the symbol table, these facilities are all available. Where + the object code format is standard COFF, on the other hand, most + of the C++ support in GDB will *not* work, nor can it. For the + standard SVr4 debugging format, DWARF in ELF, the standard is + still evolving, so the C++ support in GDB is still fragile; when + this debugging format stabilizes, however, C++ support will also + be available on systems that use it. + + 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++. + + 3. You can call overloaded functions; GDB will resolve the function + call to the right definition, with one restriction--you must use + arguments of the type required by the function that you want to + call. GDB will not perform conversions requiring constructors or + user-defined type operators. + + 4. GDB understands variables declared as C++ references; you can use + them in expressions just as you do in C++ source--they are + automatically dereferenced. + + In the parameter list shown when GDB displays a frame, the values + of reference variables are not displayed (unlike other variables); + this avoids clutter, since references are often used for large + structures. The *address* of a reference variable is always + shown, unless you have specified `set print address off'. + + 5. GDB supports the C++ name resolution operator `::'--your + expressions can use it just as expressions in your program do. + Since one scope may be defined in another, you can use `::' + repeatedly if necessary, for example in an expression like + `SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by + reference to source files, in both C and C++ debugging (*note + Program variables: Variables.). + + +File: gdb.info, Node: C Defaults, Next: C Checks, Prev: Cplus expressions, Up: C + +C and C++ defaults +------------------ + + If you allow GDB to set type and range checking automatically, they +both default to `off' whenever the working language changes to C or +C++. This happens regardless of whether you, or GDB, selected the +working language. + + If you allow GDB to set the language automatically, it sets the +working language to C or C++ on entering code compiled from a source +file whose name ends with `.c', `.C', or `.cc'. *Note Having GDB infer +the source language: Automatically, for further details. + + +File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C + +C and C++ type and range checks +------------------------------- + + By default, when GDB parses C or C++ expressions, type checking is +not used. However, if you turn type checking on, GDB will consider two +variables type equivalent if: + + * The two variables are structured and have the same structure, + union, or enumerated tag. + + * Two two variables have the same type name, or types that have been + declared equivalent through `typedef'. + + Range checking, if turned on, is done on mathematical operations. +Array indices are not checked, since they are often used to index a +pointer that is not itself an array. + + +File: gdb.info, Node: Debugging C, Next: Debugging C plus plus, Prev: C Checks, Up: C + +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' will also be printed. Otherwise, it will appear as `{...}'. + + The `@' operator aids in the debugging of dynamic arrays, formed +with pointers and a memory allocation function. *Note Expressions: +Expressions. + + +File: gdb.info, Node: Debugging C plus plus, Prev: Debugging C, Up: C + +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 breakpoint menus help you specify which function definition + you want. *Note Breakpoint menus: Breakpoint Menus. + +`rbreak REGEX' + Setting breakpoints using regular expressions is helpful for + setting breakpoints on overloaded functions that are not members + of any special classes. *Note Setting breakpoints: Set Breaks. + +`catch EXCEPTIONS' +`info catch' + Debug C++ exception handling using these commands. *Note + Breakpoints and exceptions: Exception Handling. + +`ptype TYPENAME' + Print inheritance relationships as well as other information for + type TYPENAME. *Note Examining the Symbol Table: Symbols. + +`set print demangle' +`show print demangle' +`set print asm-demangle' +`show print asm-demangle' + Control whether C++ symbols display in their source form, both when + displaying code as C++ source and when displaying disassemblies. + *Note Print settings: Print Settings. + +`set print object' +`show print object' + Choose whether to print derived (actual) or declared types of + objects. *Note Print settings: Print Settings. + +`set print vtbl' +`show print vtbl' + Control the format for printing virtual function tables. *Note + Print settings: Print Settings. + +`Overloaded symbol names' + You can specify a particular definition of an overloaded symbol, + using the same notation that is used to declare such symbols in + C++: type `SYMBOL(TYPES)' rather than just SYMBOL. You can also + use the GDB command-line word completion facilities to list the + available choices, or to finish the type list for you. *Note + Command completion: Completion, for details on how to do this. + + +File: gdb.info, Node: Modula-2, Prev: C, Up: Support + +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 will most likely result in an error +as GDB reads in the executable's symbol table. + +* Menu: + +* M2 Operators:: Built-in operators +* Built-In Func/Proc:: Built-in functions and procedures +* M2 Constants:: Modula-2 constants +* M2 Defaults:: Default settings for Modula-2 +* Deviations:: Deviations from standard Modula-2 +* M2 Checks:: Modula-2 type and range checks +* M2 Scope:: The scope operators `::' and `.' +* GDB/M2:: GDB and Modula-2 + + +File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 + +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, greater than, 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 conjuction. Defined on boolean types. + +`@' + The GDB "artificial array" operator (*note Expressions: + Expressions.). + +`+, -' + Addition and subtraction on integral and floating-point types, or + union and difference on set types. + +`*' + Multiplication on integral and floating-point types, or set + intersection on set types. + +`/' + Division on floating-point types, or symmetric set difference on + set types. Same precedence as `*'. + +`DIV, MOD' + Integer division and remainder. Defined on integral types. Same + precedence as `*'. + +`-' + Negative. Defined on `INTEGER' and `REAL' data. + +`^' + Pointer dereferencing. Defined on pointer types. + +`NOT' + Boolean negation. Defined on boolean types. Same precedence as + `^'. + +`.' + `RECORD' field selector. Defined on `RECORD' data. Same + precedence as `^'. + +`[]' + Array indexing. Defined on `ARRAY' data. Same precedence as `^'. + +`()' + Procedure argument list. Defined on `PROCEDURE' objects. Same + precedence as `^'. + +`::, .' + GDB and Modula-2 scope operators. + + *Warning:* Sets and their operations are not yet supported, so GDB + will treat the use of the operator `IN', or the use of operators + `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>=' on sets as an + error. + + +File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 + +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. 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. 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. + +`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 will treat the use of procedures `INCL' and `EXCL' as an error. + + +File: gdb.info, Node: M2 Constants, Next: M2 Defaults, Prev: Built-In Func/Proc, Up: Modula-2 + +Constants +--------- + + GDB allows you to express the constants of Modula-2 in the following +ways: + + * Integer constants are simply a sequence of digits. When used in an + expression, a constant is interpreted to be type-compatible with + the rest of the expression. Hexadecimal integers are specified by + a trailing `H', and octal integers by a trailing `B'. + + * Floating point constants appear as a sequence of digits, followed + by a decimal point and another sequence of digits. An optional + exponent can then be specified, in the form `E[+|-]NNN', where + `[+|-]NNN' is the desired exponent. All of the digits of the + floating point constant must be valid decimal (base 10) digits. + + * Character constants consist of a single character enclosed by a + pair of like quotes, either single (`'') or double (`"'). They may + also be expressed by their ordinal value (their ASCII value, + usually) followed by a `C'. + + * String constants consist of a sequence of characters enclosed by a + pair of like quotes, either single (`'') or double (`"'). Escape + sequences in the style of C are also allowed. *Note C and C++ + constants: C Constants, for a brief explanation of escape + sequences. + + * Enumerated constants consist of an enumerated identifier. + + * Boolean constants consist of the identifiers `TRUE' and `FALSE'. + + * Pointer constants consist of integral values only. + + * Set constants are not yet supported. + + +File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Constants, Up: Modula-2 + +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' will set the +working language to Modula-2. *Note Having GDB set the language +automatically: Automatically, for further details. + + +File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 + +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 will print out strings + with these escape sequences embedded. Single non-printable + characters are printed using the `CHR(NNN)' format. + + * The assignment operator (`:=') returns the value of its right-hand + argument. + + * All built-in procedures both modify *and* return their argument. + + +File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 + +Modula-2 type and range checks +------------------------------ + + *Warning:* in this release, GDB does not yet perform type or range + checking. + + GDB considers two Modula-2 variables type equivalent if: + + * They are of types that have been declared equivalent via a `TYPE + T1 = T2' statement + + * They have been declared on the same line. (Note: This is true of + the GNU Modula-2 compiler, but it may not be true of other + compilers.) + + As long as type checking is enabled, any attempt to combine variables +whose types are not equivalent is an error. + + Range checking is done on all mathematical operations, assignment, +array index bounds, and all built-in functions and procedures. + + +File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 + +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 will search all scopes enclosing the one specified by +SCOPE. + + Using the `.' operator makes GDB search the current scope for the +identifier specified by ID that was imported from the definition module +specified by MODULE. With this operator, it is an error if the +identifier ID was not imported from definition module MODULE, or if ID +is not an identifier in MODULE. + + +File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 + +GDB and Modula-2 +---------------- + + Some GDB commands have little use when debugging Modula-2 programs. +Five subcommands of `set print' and `show print' apply specifically to +C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'. +The first four apply to C++, and the last to the C `union' type, which +has no direct analogue in Modula-2. + + The `@' operator (*note Expressions: Expressions.), while available +while using 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. (*note Expressions: Expressions.) + + In GDB scripts, the Modula-2 inequality operator `#' is interpreted +as the beginning of a comment. Use `<>' instead. + + +File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top + +Examining the Symbol Table +************************** + + The commands described in this section allow you to inquire about the +symbols (names of variables, functions and types) defined in your +program. This information is inherent in the text of your program and +does not change as your program executes. GDB finds it in your +program's symbol table, in the file indicated when you started GDB +(*note Choosing files: File Options.), or by one of the file-management +commands (*note Commands to specify files: Files.). + + Occasionally, you may need to refer to symbols that contain unusual +characters, which GDB ordinarily treats as word delimiters. The most +frequent case is in referring to static variables in other source files +(*note Program variables: Variables.). File names are recorded in +object files as debugging symbols, but GDB would ordinarily parse a +typical file name, like `foo.c', as the three words `foo' `.' `c'. To +allow GDB to recognize `foo.c' as a single symbol, enclose it in single +quotes; for example, + + p 'foo.c'::x + +looks up the value of `x' in the scope of the file `foo.c'. + +`info address SYMBOL' + Describe where the data for SYMBOL is stored. For a register + variable, this says which register it is kept in. For a + non-register local variable, this prints the stack-frame offset at + which the variable is always stored. + + Note the contrast with `print &SYMBOL', which does not work at all + for a register variable, and for a stack local variable prints the + exact address of the current instantiation of the variable. + +`whatis EXP' + Print the data type of expression EXP. EXP is not actually + evaluated, and any side-effecting operations (such as assignments + or function calls) inside it do not take place. *Note + Expressions: Expressions. + +`whatis' + Print the data type of `$', the last value in the value history. + +`ptype TYPENAME' + Print a description of data type TYPENAME. TYPENAME may be the + name of a type, or for C code it may have the form `class + CLASS-NAME', `struct STRUCT-TAG', `union UNION-TAG' or `enum + ENUM-TAG'. + +`ptype EXP' +`ptype' + Print a description of the type of expression EXP. `ptype' + differs from `whatis' by printing a detailed description, instead + of just the name of the type. + + For example, for this variable declaration: + + struct complex {double real; double imag;} v; + + the two commands give this output: + + (gdb) whatis v + type = struct complex + (gdb) ptype v + type = struct complex { + double real; + double imag; + } + + As with `whatis', using `ptype' without an argument refers to the + type of `$', the last value in the value history. + +`info types REGEXP' +`info types' + Print a brief description of all types whose name matches REGEXP + (or all types in your program, if you supply no argument). Each + complete typename is matched as though it were a complete line; + thus, `i type value' gives information on all types in your + program whose name includes the string `value', but `i type + ^value$' gives information only on types whose complete name is + `value'. + + This command differs from `ptype' in two ways: first, like + `whatis', it does not print a detailed description; second, it + lists all source files where a type is defined. + +`info source' + Show the name of the current source file--that is, the source file + for the function containing the current point of execution--and + the language it was written in. + +`info sources' + Print the names of all source files in your program for which + there is debugging information, organized into two lists: files + whose symbols have already been read, and files whose symbols will + be read when needed. + +`info functions' + Print the names and data types of all defined functions. + +`info functions REGEXP' + Print the names and data types of all defined functions whose + names contain a match for regular expression REGEXP. Thus, `info + fun step' finds all functions whose names include `step'; `info + fun ^step' finds those whose names start with `step'. + +`info variables' + Print the names and data types of all variables that are declared + outside of functions (i.e., excluding local variables). + +`info variables REGEXP' + Print the names and data types of all variables (except for local + variables) whose names contain a match for regular expression + REGEXP. + +`maint print symbols FILENAME' +`maint print psymbols FILENAME' +`maint print msymbols FILENAME' + Write a dump of debugging symbol data into the file FILENAME. + These commands are used to debug the GDB symbol-reading code. Only + symbols with debugging data are included. If you use `maint print + symbols', GDB includes all the symbols for which it has already + collected full details: that is, FILENAME reflects symbols for + only those files whose symbols GDB has read. You can use the + command `info sources' to find out which files these are. If you + use `maint print psymbols' instead, the dump shows information + about symbols that GDB only knows partially--that is, symbols + defined in files that GDB has skimmed, but not yet read + completely. Finally, `maint print msymbols' dumps just the + minimal symbol information required for each object file from + which GDB has read some symbols. *Note Commands to specify files: + Files, for a discussion of how GDB reads symbols (in the + description of `symbol-file'). + |
