diff options
Diffstat (limited to 'gdb/doc/gdb.info-5')
| -rw-r--r-- | gdb/doc/gdb.info-5 | 1185 |
1 files changed, 1185 insertions, 0 deletions
diff --git a/gdb/doc/gdb.info-5 b/gdb/doc/gdb.info-5 new file mode 100644 index 00000000000..854e34f209c --- /dev/null +++ b/gdb/doc/gdb.info-5 @@ -0,0 +1,1185 @@ +This is Info file ./gdb.info, produced by Makeinfo version 1.68 from +the input file gdb.texinfo. + +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +END-INFO-DIR-ENTRY + This file documents the GNU debugger GDB. + + This is the Seventh Edition, February 1999, of `Debugging with GDB: +the GNU Source-Level Debugger' for GDB Version 4.18. + + Copyright (C) 1988-1999 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the entire resulting derived work is distributed under the terms +of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions. + + +File: gdb.info, Node: 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. + +* Menu: + +* C Constants:: + + +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' (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. + + * 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. + +* Menu: + +* Cplus expressions:: +* C Defaults:: + +* C Checks:: + +* Debugging C:: + + +File: gdb.info, Node: Cplus expressions, Next: C Defaults, Prev: C Constants, Up: C + +C++ expressions +............... + + GDB expression handling can interpret most C++ expressions. + + *Warning:* GDB can only debug C++ code if you use the proper + compiler. Typically, C++ debugging depends on the use of + additional debugging information in the symbol table, and thus + requires special support. In particular, if your compiler + generates a.out, MIPS ECOFF, RS/6000 XCOFF, or ELF with stabs + extensions to the symbol table, these facilities are all + available. (With GNU CC, you can use the `-gstabs' option to + request stabs debugging extensions explicitly.) Where the object + code format is standard COFF or DWARF in ELF, on the other hand, + most of the C++ support in GDB does *not* work. + + 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 resolves 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 does 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 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++. *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 Constants + +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 considers two +variables type equivalent if: + + * The two variables are structured and have the same structure, + union, or enumerated tag. + + * The two variables have the same type name, or types that have been + declared equivalent through `typedef'. + + Range checking, if turned on, is done on mathematical operations. +Array indices are not checked, since they are often used to index a +pointer that is not itself an array. + + +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' is also printed. Otherwise, it appears as `{...}'. + + The `@' operator aids in the debugging of dynamic arrays, formed +with pointers and a memory allocation function. *Note Expressions: +Expressions. + +* Menu: + +* Debugging C plus plus:: + + +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 throw' +`catch catch' + Debug C++ exception handling using these commands. *Note Setting + catchpoints: Set Catchpoints. + +`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 is most likely to give 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, Prev: Modula-2, 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 + treats 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 treats 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' sets 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 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. + + +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 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. + + +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. + + Some systems allow individual object files that make up your + program to be replaced without stopping and restarting your + program. For example, in VxWorks you can simply recompile a + defective object file and keep on running. If you are running on + one of these systems, you can allow GDB to reload the symbols for + automatically relinked modules: + + `set symbol-reloading on' + Replace symbol definitions for the corresponding source file + when an object file with a particular name is seen again. + + `set symbol-reloading off' + Do not replace symbol definitions when re-encountering object + files of the same name. This is the default state; if you + are not running on a system that permits automatically + relinking modules, you should leave `symbol-reloading' off, + since otherwise GDB may discard symbols when linking large + programs, that may contain several modules (from different + directories or libraries) with the same name. + + `show symbol-reloading' + Show the current `on' or `off' setting. + +`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'). + + +File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top + +Altering Execution +****************** + + Once you think you have found an error in your program, you might +want to find out for certain whether correcting the apparent error +would lead to correct results in the rest of the run. You can find the +answer by experiment, using the GDB features for altering execution of +the program. + + For example, you can store new values into variables or memory +locations, give your program a signal, restart it at a different +address, or even return prematurely from a function. + +* Menu: + +* Assignment:: Assignment to variables +* Jumping:: Continuing at a different address + +* Signaling:: Giving your program a signal + +* Returning:: Returning from a function +* Calling:: Calling your program's functions +* Patching:: Patching your program + + +File: gdb.info, Node: Assignment, Next: Jumping, Prev: Altering, Up: Altering + +Assignment to variables +======================= + + To alter the value of a variable, evaluate an assignment expression. +*Note Expressions: Expressions. For example, + + print x=4 + +stores the value 4 into the variable `x', and then prints the value of +the assignment expression (which is 4). *Note Using GDB with Different +Languages: Languages, for more information on operators in supported +languages. + + If you are not interested in seeing the value of the assignment, use +the `set' command instead of the `print' command. `set' is really the +same as `print' except that the expression's value is not printed and +is not put in the value history (*note Value history: Value History.). +The expression is evaluated only for its effects. + + If the beginning of the argument string of the `set' command appears +identical to a `set' subcommand, use the `set variable' command instead +of just `set'. This command is identical to `set' except for its lack +of subcommands. For example, if your program has a variable `width', +you get an error if you try to set a new value with just `set +width=13', because GDB has the command `set width': + + (gdb) whatis width + type = double + (gdb) p width + $4 = 13 + (gdb) set width=47 + Invalid syntax in expression. + +The invalid expression, of course, is `=47'. In order to actually set +the program's variable `width', use + + (gdb) set var width=47 + + GDB allows more implicit conversions in assignments than C; you can +freely store an integer value into a pointer variable or vice versa, +and you can convert any structure to any other structure that is the +same length or shorter. + + To store values into arbitrary places in memory, use the `{...}' +construct to generate a value of specified type at a specified address +(*note Expressions: Expressions.). For example, `{int}0x83040' refers +to memory location `0x83040' as an integer (which implies a certain size +and representation in memory), and + + set {int}0x83040 = 4 + +stores the value 4 into that memory location. + + +File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering + +Continuing at a different address +================================= + + Ordinarily, when you continue your program, you do so at the place +where it stopped, with the `continue' command. You can instead +continue at an address of your own choosing, with the following +commands: + +`jump LINESPEC' + Resume execution at line LINESPEC. Execution stops again + immediately if there is a breakpoint there. *Note Printing source + lines: List, for a description of the different forms of LINESPEC. + It is common practice to use the `tbreak' command in conjunction + with `jump'. *Note Setting breakpoints: Set Breaks. + + The `jump' command does not change the current stack frame, or the + stack pointer, or the contents of any memory location or any + register other than the program counter. If line LINESPEC is in a + different function from the one currently executing, the results + may be bizarre if the two functions expect different patterns of + arguments or of local variables. For this reason, the `jump' + command requests confirmation if the specified line is not in the + function currently executing. However, even bizarre results are + predictable if you are well acquainted with the machine-language + code of your program. + +`jump *ADDRESS' + Resume execution at the instruction at address ADDRESS. + + You can get much the same effect as the `jump' command by storing a +new value into the register `$pc'. The difference is that this does +not start your program running; it only changes the address of where it +*will* run when you continue. For example, + + set $pc = 0x485 + +makes the next `continue' command or stepping command execute at +address `0x485', rather than at the address where your program stopped. +*Note Continuing and stepping: Continuing and Stepping. + + The most common occasion to use the `jump' command is to back +up--perhaps with more breakpoints set--over a portion of a program that +has already executed, in order to examine its execution in more detail. + + +File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering + +Giving your program a signal +============================ + +`signal SIGNAL' + Resume execution where your program stopped, but immediately give + it the signal SIGNAL. SIGNAL can be the name or the number of a + signal. For example, on many systems `signal 2' and `signal + SIGINT' are both ways of sending an interrupt signal. + + Alternatively, if SIGNAL is zero, continue execution without + giving a signal. This is useful when your program stopped on + account of a signal and would ordinary see the signal when resumed + with the `continue' command; `signal 0' causes it to resume + without a signal. + + `signal' does not repeat when you press <RET> a second time after + executing the command. + + Invoking the `signal' command is not the same as invoking the `kill' +utility from the shell. Sending a signal with `kill' causes GDB to +decide what to do with the signal depending on the signal handling +tables (*note Signals::.). The `signal' command passes the signal +directly to your program. + + +File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering + +Returning from a function +========================= + +`return' +`return EXPRESSION' + You can cancel execution of a function call with the `return' + command. If you give an EXPRESSION argument, its value is used as + the function's return value. + + When you use `return', GDB discards the selected stack frame (and +all frames within it). You can think of this as making the discarded +frame return prematurely. If you wish to specify a value to be +returned, give that value as the argument to `return'. + + This pops the selected stack frame (*note Selecting a frame: +Selection.), and any other frames inside of it, leaving its caller as +the innermost remaining frame. That frame becomes selected. The +specified value is stored in the registers used for returning values of +functions. + + The `return' command does not resume execution; it leaves the +program stopped in the state that would exist if the function had just +returned. In contrast, the `finish' command (*note Continuing and +stepping: Continuing and Stepping.) resumes execution until the +selected stack frame returns naturally. + + +File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering + +Calling program functions +========================= + +`call EXPR' + Evaluate the expression EXPR without displaying `void' returned + values. + + You can use this variant of the `print' command if you want to +execute a function from your program, but without cluttering the output +with `void' returned values. If the result is not void, it is printed +and saved in the value history. + + For the A29K, a user-controlled variable `call_scratch_address', +specifies the location of a scratch area to be used when GDB calls a +function in the target. This is necessary because the usual method of +putting the scratch area on the stack does not work in systems that +have separate instruction and data spaces. + + +File: gdb.info, Node: Patching, Prev: Calling, Up: Altering + +Patching programs +================= + + By default, GDB opens the file containing your program's executable +code (or the corefile) read-only. This prevents accidental alterations +to machine code; but it also prevents you from intentionally patching +your program's binary. + + If you'd like to be able to patch the binary, you can specify that +explicitly with the `set write' command. For example, you might want +to turn on internal debugging flags, or even to make emergency repairs. + +`set write on' +`set write off' + If you specify `set write on', GDB opens executable and core files + for both reading and writing; if you specify `set write off' (the + default), GDB opens them read-only. + + If you have already loaded a file, you must load it again (using + the `exec-file' or `core-file' command) after changing `set + write', for your new setting to take effect. + +`show write' + Display whether executable files and core files are opened for + writing as well as reading. + + +File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top + +GDB Files +********* + + GDB needs to know the file name of the program to be debugged, both +in order to read its symbol table and in order to start your program. +To debug a core dump of a previous run, you must also tell GDB the name +of the core dump file. + +* Menu: + +* Files:: Commands to specify files +* Symbol Errors:: Errors reading symbol files + |