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 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